REST API - Modellix

Steps

Get API Key

In the Modellix console, go to “API Key” and create an API Key.

The API Key is only displayed once after creation, so be sure to save it first.

Use the API

Find the model you want to use in Model API, or Model Index, and call the API using your API Key. For example:

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:

{
  "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"
    }
  }
}

Get the Result

You can query the task result later using the task_id. For example:

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:

{
  "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"
      }
    }
  }
}

The model’s generated results will all be placed in the result object.

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

{
  "url": "https://cdn.example.com/images/abc123.png"
}

Enjoy the Result

You have now successfully used the Modellix model API and obtained the generated result.

Generated results are only saved for 7 days, so please make sure to save them promptly.

Error Handling

All error responses follow a unified JSON format:

{
  "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

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.

Webhooks

Modellix supports webhooks to notify your application automatically when a media generation task is completed. Instead of polling the task status, you can configure a Webhook URL to receive the task results asynchronously.

Triggering Webhooks

To enable webhooks for a task, include the X-Webhook-URL header when calling any prediction creation API:

X-Webhook-URL: https://example.com/webhook

Once the task reaches a terminal state, the system asynchronously sends a POST request to this URL. Terminal states include:

success
failed
canceled

Webhook URL Requirements

Your webhook endpoint must meet the following requirements:

Must be a publicly accessible HTTPS address.
Cannot be localhost or 127.0.0.1.
Cannot be a private IP address (e.g., 10.x.x.x, 172.16.x.x to 172.31.x.x, 192.168.x.x).
Cannot contain username and password credentials in the URL.

For local development and testing, you can use tools like ngrok or cloudflared to expose your local server via a public HTTPS URL.

Callback Request

The system will initiate a POST request to your configured X-Webhook-URL with the following headers:

Header	Description
`Content-Type`	Always `application/json`
`User-Agent`	Always `modellix-webhook/1.0`
`X-Modellix-Event`	The event type that triggered the webhook
`X-Modellix-Task-ID`	The unique ID of the generation task
`X-Modellix-Delivery-ID`	The unique ID of this webhook delivery attempt
`X-Modellix-Retry-Count`	The number of retries for this delivery (starts at `0`)

Event Types

The X-Modellix-Event header can have one of the following values:

prediction.task.succeeded — Sent when the task completes successfully.
prediction.task.failed — Sent when the task fails.
prediction.task.canceled — Sent when the task is canceled.

Callback Payload

The webhook request body structure is identical to the response of the Query Task Result API.

{
  "code": 0,
  "message": "success",
  "data": {
    "status": "success",
    "task_id": "task_id",
    "model_id": "provider/model",
    "duration": 12345,
    "result": {},
    "billing": {
      "status": "succeeded",
      "amount": "12.3456"
    }
  }
}

{
  "code": 0,
  "message": "success",
  "data": {
    "status": "failed",
    "task_id": "task_id",
    "model_id": "provider/model",
    "error": "provider timeout"
  }
}

Receiver Response Requirements

To acknowledge receipt of the webhook, your server must return an HTTP 2xx status code.

Recommended response: HTTP/1.1 200 OK with a plain text body of ok.
Alternative response: HTTP/1.1 204 No Content with an empty body.

The Modellix webhook system only checks the HTTP status code and does not parse or validate the response body.

Retry Rules

If delivery fails, the system will attempt to redeliver the webhook under specific conditions.

Retried Errors

The system will automatically retry delivery for the following errors:

HTTP status 429 (Too Many Requests)
HTTP status 5xx (Server Errors)
Network timeouts
Temporary network errors

Non-Retried Errors

The system will not retry delivery for the following errors:

HTTP status 3xx (Redirection)
HTTP status 4xx (Client Errors, except 429)
Invalid Webhook URLs
URLs pointing to private networks or localhost
Permanent connection errors (e.g., connection refused, unresolved DNS)

Best Practices

To ensure reliable and secure webhook processing, we recommend following these guidelines:

Idempotency: Use the X-Modellix-Delivery-ID header to deduplicate incoming webhooks and prevent processing the same event multiple times.
Asynchronous Processing: To avoid timeouts, quickly persist the incoming payload or push it to a message queue, and immediately return a 200 or 204 response. Perform any heavy business logic asynchronously.
Security: Verify the request source or signature (if signature verification is supported in a future update).

​Steps

​Error Handling

​Error Codes

​Webhooks

​Triggering Webhooks

​Webhook URL Requirements

​Callback Request

​Event Types

​Callback Payload

​Receiver Response Requirements

​Retry Rules

​Retried Errors

​Non-Retried Errors

​Best Practices

Steps

Error Handling

Error Codes

Webhooks

Triggering Webhooks

Webhook URL Requirements

Callback Request

Event Types

Callback Payload

Receiver Response Requirements

Retry Rules

Retried Errors

Non-Retried Errors

Best Practices