> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modellix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> The steps to use the Modellix models API, including how to get an API key, how to use the API, and how to get the result.

## Steps

<Steps>
  <Step title="Register Modellix">
    Log in to the [Modellix console](https://modellix.ai/console).
  </Step>

  <Step title="Get API Key">
    In the Modellix console, go to "[API Key](https://modellix.ai/console/api-key)" and create an API Key.

    <Note>The API Key is only displayed once after creation, so be sure to save it first.</Note>
  </Step>

  <Step title="Use the API">
    Find the model you want to use in **Model API**, and call the API using your API Key. For example:

    ```bash theme={null}
    curl --request POST \
      --url https://api.modellix.ai/api/v1/alibaba/qwen-image-plus/async \
      --header 'Authorization: Bearer <your_api_key>' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "prompt": "A cute cat playing in a garden on a sunny day"
    }
    '
    ```

    Since model calls are asynchronous tasks, after a successful call, you will first receive a `task_id` as shown below:

    ```json theme={null}
    {
      "code": 0,
      "message": "success",
      "data": {
        "status": "pending",
        "task_id": "task-abc123",
        "model_id": "qwen-image-plus",
        "get_result": {
          "method": "GET",
          "url": "https://api.modellix.ai/api/v1/tasks/task-abc123"
        }
      }
    }
    ```
  </Step>

  <Step title="Get the Result">
    You can query the task result later using the `task_id`. For example:

    ```bash theme={null}
    curl --request GET \
      --url https://api.modellix.ai/api/v1/tasks/{task_id} \
      --header 'Authorization: Bearer <your_api_key>'
    ```

    After a successful query, you will get the generated result. For example:

    ```json theme={null}
    {
      "code": 0,
      "message": "success",
      "data": {
        "status": "success",
        "task_id": "task-abc123",
        "model_id": "qwen-image-plus",
        "duration": 3500,
        "result": {
          "resources": [
            {
              "url": "https://cdn.example.com/images/abc123.png",
              "type": "image",
              "width": 1024,
              "height": 1024,
              "format": "png",
              "role": "primary"
            }
          ],
          "metadata": {
            "image_count": 1,
            "request_id": "req-123456"
          },
          "extensions": {
            "submit_time": "2024-01-01T10:00:00Z",
            "end_time": "2024-01-01T10:00:03Z"
          }
        }
      }
    }
    ```

    <Note>The model's generated results will all be placed in the `result` object.</Note>

    You can find the generated image URL in the `result`. For example:

    ```json theme={null}
    {
      "url": "https://cdn.example.com/images/abc123.png"
    }
    ```
  </Step>

  <Step title="Enjoy the Result">
    You have now successfully used the Modellix model API and obtained the generated result.

    <Warning>Generated results are only saved for 24 hours, so please make sure to save them promptly.</Warning>
  </Step>
</Steps>

## Error Handling

All error responses follow a unified JSON format:

```json theme={null}
{
  "code": 400,
  "message": "Invalid parameters: parameter 'prompt' is required"
}
```

* `code` (integer) — equals the HTTP status code (`0` on success)
* `message` (string) — formatted as `"<Category>: <detail>"`

### Error Codes

| HTTP Status | Description           | Common Scenarios                                            | Retryable                     |
| ----------- | --------------------- | ----------------------------------------------------------- | ----------------------------- |
| 400         | Bad Request           | Missing required parameters, invalid format, invalid values | No — fix parameters first     |
| 401         | Unauthorized          | Invalid API key, missing API key, expired API key           | No — provide a valid key      |
| 402         | Payment Required      | Insufficient balance, account in arrears                    | No — recharge your account    |
| 404         | Not Found             | Task ID not found, model not found, provider not found      | No — check resource ID        |
| 429         | Too Many Requests     | Rate limit exceeded, concurrent limit exceeded              | Yes — use exponential backoff |
| 500         | Internal Server Error | Internal processing error, unexpected error                 | Yes — retry up to 3 times     |
| 503         | Service Unavailable   | Service temporarily unavailable, circuit breaker open       | Yes — retry with backoff      |

<Tip>
  For **429** responses, check the `X-RateLimit-Reset` header to know when you can retry. Use exponential backoff (1 s → 2 s → 4 s) for **500** and **503** errors.
</Tip>