API Overview

Base Information

Base URL

export BASE_URL="https://api.modellix.ai"

Protocol & Encoding

Protocol: HTTP/HTTPS
Encoding: UTF-8
Data Format: JSON

Authentication

All API requests require an API Key in the HTTP header:

Authorization: Bearer YOUR_API_KEY

Rate Limiting

Global limit: 1000 requests/minute
Per API Key: 100 requests/minute
Per model: Subject to provider limitations

Interface Types

The Prediction API provides two calling methods:

Interface Type	Endpoint	Description	Use Cases
Async Interface	`POST /api/v1/{type}/{provider}/{model_id}/async`	Submit task and receive task_id immediately, query results via task query interface	Long-running tasks, batch processing
Stream Interface	`POST /api/v1/{type}/{provider}/{model_id}/stream`	SSE real-time push of progress and results	Scenarios requiring real-time progress feedback

Not all models support both interface types. Check the API documentation for each model’s supported interfaces.

Unified Interface Definition

1. Async Prediction Interface

Endpoint: POST /api/v1/{type}/{provider}/{model_id}/async Description: Submit async prediction task, immediately returns task ID. Query task status and results via result query interface.

Path Parameters

Parameter	Type	Description	Example
type	string	Business type	text-to-image, text-to-video, image-to-image, image-to-video
provider	string	Provider identifier	alibaba, minimax, kling, doubao
model_id	string	Model ID	qwen-image-plus, flux-schnell, video-01

Supported Business Types (type):

text-to-image - Text to Image
image-to-image - Image to Image (image editing, image translation, etc.)
text-to-video - Text to Video
image-to-video - Image to Video

Request Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Request Body

The request body contains flattened parameters, specific parameters vary by model. See the API documentation for detailed parameter descriptions. Common parameters (across most models):

prompt: Prompt text (required)
negative_prompt: Negative prompt (optional)
size: Size specification (optional)
style: Style parameter (optional)
seed: Random seed (optional)

Response Fields

Top-level fields:

Field	Type	Description
code	integer	Response code, 0 indicates success
message	string	Response message
data	object	Task information, see below

data object fields:

Field	Type	Description
status	string	Task status (pending, processing, success, failed)
task_id	string	Unique task identifier
model_id	string	Model ID
duration	integer	Response duration (milliseconds)

Task Status Description:

pending: Task queued
processing: Task processing
success: Task completed successfully
failed: Task failed

2. Stream Prediction Interface

Endpoint: POST /api/v1/{type}/{provider}/{model_id}/stream Description: Stream prediction results via SSE (Server-Sent Events), suitable for scenarios requiring real-time progress.

Path Parameters, Request Headers, Request Body

Same as async prediction interface.

Response Format

Response Headers:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

SSE Event Stream: Progress Event (message):

event: message
data: {"status":"processing","progress":10,"message":"Task processing"}

event: message
data: {"status":"processing","progress":50,"message":"Generating..."}

Result Event (message):

event: message
data: {"result":{"image_url":"https://example.com/result.png"}}

Completion Event (status):

event: status
data: {"status":"completed"}

Error Event (error):

event: error
data: {"error":"Error description"}

Important Notes:

Client must support SSE protocol
Use -N or --no-buffer parameter to disable buffering (curl)
Connection remains open until task completes or errors
Client disconnection automatically cancels task

3. Task Query Interface

Endpoint: GET /api/v1/tasks/{task_id} Description: Query async task status and results.

Path Parameters

Parameter	Type	Description
task_id	string	Task ID (returned by async interface)

Request Headers

Authorization: Bearer YOUR_API_KEY

Response Fields

Top-level fields:

Field	Type	Description
code	integer	Response code, 0 indicates success
message	string	Response message
data	object	Task information, see below

data object fields:

Field	Type	Description
status	string	Task status (success, pending, processing, failed)
task_id	string	Unique task identifier
model_id	string	Model ID
duration	integer	Processing time (milliseconds, returned only on completion/failure)
result	object	StandardResponse object containing standardized result data

result object structure (StandardResponse):

Field	Type	Description
resources	array	Resource list containing generated images/videos
metadata	object	Metadata (image count, video count, request ID, etc.)
extensions	object	Extension fields (provider-specific information)

resources array element structure (Resource):

Field	Type	Description
url	string	Resource URL (CDN address)
type	string	Resource type (image, video, audio)
width	integer	Image/video width (optional)
height	integer	Image/video height (optional)
duration	integer	Video/audio duration in seconds (optional)
size	integer	File size in bytes (optional)
role	string	Resource role (primary, cover, thumbnail)
quality	string	Quality identifier (1080p, 720p, etc., optional)
format	string	File format (png, jpg, mp4, etc., optional)

Response Format Specification

All API responses follow a unified JSON format:

Unified Response Structure

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

Response Field Description

Top-level Fields

Field	Type	Description
code	integer	Response code, 0 indicates success
message	string	Response message
data	object	Response data (returned on success)

data Object Fields

Field	Type	Description
status	string	Task status (success, pending, processing, failed)
task_id	string	Unique task identifier
model_id	string	Model ID
duration	integer	Processing time (milliseconds)
result	object	StandardResponse object containing standardized result data

result Field Description (StandardResponse)

The result field contains a standardized response structure, consistent across all models: Core Fields:

resources: Resource array containing generated images/videos and other media resources
metadata: Metadata (statistics, request ID, etc.)
extensions: Extension fields (provider-specific information)

resources Array: Each resource object contains:

url: Resource URL
type: Resource type (image, video, audio)
width, height: Dimension information (optional)
duration: Video/audio duration in seconds (optional)
role: Resource role (primary, cover, thumbnail)
format: File format (png, jpg, mp4, etc., optional)

See “Success Response Examples” below for specific examples.

Success Response Examples

Text-to-Image Task (Single Image):

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

Text-to-Video Task:

{
  "code": 0,
  "message": "success",
  "data": {
    "status": "success",
    "task_id": "task-video-456",
    "model_id": "kling-v1",
    "duration": 15000,
    "result": {
      "resources": [
        {
          "url": "https://cdn.example.com/videos/video123.mp4",
          "type": "video",
          "width": 1280,
          "height": 720,
          "duration": 5,
          "format": "mp4",
          "role": "primary"
        },
        {
          "url": "https://cdn.example.com/videos/cover123.jpg",
          "type": "image",
          "format": "jpg",
          "role": "cover"
        }
      ],
      "metadata": {
        "video_count": 1,
        "request_id": "req-video-789"
      },
      "extensions": {
        "progress": 100
      }
    }
  }
}

Error Response Examples

Error responses have code field equal to HTTP status code, and message field in format "<Category>: <detail>": Parameter Error (HTTP 400 / code 400):

{
  "code": 400,
  "message": "Invalid parameters: parameter 'prompt' is required"
}

Unauthorized (HTTP 401 / code 401):

{
  "code": 401,
  "message": "Authentication failed: invalid API key"
}

Task Not Found (HTTP 404 / code 404):

{
  "code": 404,
  "message": "Resource not found: task 'task-abc123' does not exist"
}

Too Many Requests (HTTP 429 / code 429):

{
  "code": 429,
  "message": "Rate limit exceeded: 100 requests per minute, retry after 60 seconds"
}

Server Error (HTTP 500 / code 500):

{
  "code": 500,
  "message": "Internal server error"
}

Response Code Specification

code Field Rules

Success: code = 0, HTTP status code is 200
Error: code = HTTP status code (e.g., 400, 401, 404, 429, 500, 503)

HTTP Status Code Reference

HTTP Status	code	Description	Common Scenarios
200	0	Success	Request processed successfully
400	400	Invalid request parameters	Missing required parameters, invalid parameter format
401	401	Unauthorized	Invalid or missing API Key
404	404	Resource not found	Task ID doesn’t exist, model doesn’t exist
429	429	Too many requests	Rate limit triggered
500	500	Server error	Internal processing exception
503	503	Service unavailable	Service temporarily unavailable, circuit breaker open

For detailed error codes and handling methods, see errors.

Data Format Specification

Time Format

All time fields use UNIX timestamp (seconds). Example: 1703865600 represents 2023-12-29 16:00:00 UTC

Boolean Values

Use JSON standard boolean values: true / false

Enum Values

Enum values use lowercase strings with hyphens for multiple words. Example: text-to-image, success, pending

Quick Start

Want to get started immediately? Check out:

📚 Quick Start - Simplest examples
❌ Error Handling - Error codes and best practices

API Reference

Model API

Common API

Base Information

Base URL

Protocol & Encoding

Authentication

Rate Limiting

Interface Types

Unified Interface Definition

1. Async Prediction Interface

Path Parameters

Request Headers

Request Body

Response Fields

2. Stream Prediction Interface

Path Parameters, Request Headers, Request Body

Response Format

3. Task Query Interface

Path Parameters

Request Headers

Response Fields

Response Format Specification

Unified Response Structure

Response Field Description

Top-level Fields

data Object Fields

result Field Description (StandardResponse)

Success Response Examples

Error Response Examples

Response Code Specification

code Field Rules

HTTP Status Code Reference

Data Format Specification

Time Format

Boolean Values

Enum Values

Quick Start

API Reference

Model API

Common API

​Base Information

​Base URL

​Protocol & Encoding

​Authentication

​Rate Limiting

​Interface Types

​Unified Interface Definition

​1. Async Prediction Interface

​Path Parameters

​Request Headers

​Request Body

​Response Fields

​2. Stream Prediction Interface

​Path Parameters, Request Headers, Request Body

​Response Format

​3. Task Query Interface

​Path Parameters

​Request Headers

​Response Fields

​Response Format Specification

​Unified Response Structure

​Response Field Description

​Top-level Fields

​data Object Fields

​result Field Description (StandardResponse)

​Success Response Examples

​Error Response Examples

​Response Code Specification

​code Field Rules

​HTTP Status Code Reference

​Data Format Specification

​Time Format

​Boolean Values

​Enum Values

​Quick Start

Base Information

Base URL

Protocol & Encoding

Authentication

Rate Limiting

Interface Types

Unified Interface Definition

1. Async Prediction Interface

Path Parameters

Request Headers

Request Body

Response Fields

2. Stream Prediction Interface

Path Parameters, Request Headers, Request Body

Response Format

3. Task Query Interface

Path Parameters

Request Headers

Response Fields

Response Format Specification

Unified Response Structure

Response Field Description

Top-level Fields

data Object Fields

result Field Description (StandardResponse)

Success Response Examples

Error Response Examples

Response Code Specification

code Field Rules

HTTP Status Code Reference

Data Format Specification

Time Format

Boolean Values

Enum Values

Quick Start