Guides / Video models

Video models

Generate videos asynchronously with the MiniMax H3-compatible API. Start a text-to-video or image-guided task, poll its status, list recent tasks, and cancel or remove a task using the same API key.

Model · MiniMax-H3Asynchronous

API key required

Create an API key with video-generation access before calling the video model endpoint.

Create API Key →

Quickstart

Use https://open.wecoding.ai as the API host. Send your API key as a Bearer token on every request.

Authentication

Authorization: Bearer $WECODING_API_KEY

Generation flow

Create a task and store the returned task ID. task_id
Poll the task endpoint until its status is succeeded or failed.
When successful, read the generated video URL from task.content.url.

An API key can only access tasks created by that same key. Enable video-generation access when creating or editing the key in the console.

Supported inputs

Text-to-video with an explicit aspect ratio.
First-frame and optional last-frame image-to-video.
Reference image, video, and audio content accepted by the compatibility schema.

Currently unsupported: MiniMax-H3-Max,H3 Context IR, regeneration, callbacks, and aigc_watermark true.

Create a video task

POST/v2/video_generation

Creates an asynchronous generation task. Supply an idempotency key when retries may occur so the same logical request does not create duplicate tasks.

Text-to-video request

curl --request POST \
  --url https://open.wecoding.ai/v2/video_generation \
  --header 'Authorization: Bearer $WECODING_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: video-demo-001' \
  --data '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "A paper boat sailing through a neon city at night"
      }
    ],
    "duration": 6,
    "resolution": "768P",
    "ratio": "16:9"
  }'

Request body

Field	Type	Description
`model` Required	`string`	Must be MiniMax-H3.
`content` Required	`array`	One or more typed text, image, video, or audio content items.
`duration` Required	`integer`	Video length from 4 through 15 seconds.
`resolution` Required	`string`	768P or 2K.
`ratio`	`string`	Aspect ratio for text-to-video; adaptive for image-to-video.
`callback_url`	`string`	Reserved by the compatibility schema; currently unsupported.
`aigc_watermark`	`boolean`	Omit or set false. true is currently unsupported.

Content items

Field	Type	Description
`text`	`{ type, text }`	Prompt text. text must contain 1–7,000 characters.
`image_url`	`{ type, image_url, role }`	A URL with role first_frame, last_frame, or reference_image.
`video_url`	`{ type, video_url, role }`	A URL with role reference_video.
`audio_url`	`{ type, audio_url, role }`	A URL with role reference_audio.

Image-guided example

JSON body

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "Slow cinematic camera movement, soft morning light"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first-frame.jpg" },
      "role": "first_frame"
    }
  ],
  "duration": 6,
  "resolution": "768P",
  "ratio": "adaptive"
}

Accepted response

200 OK

{
  "task_id": "task_01K4..."
}

Query video tasks

Get one task

GET/v2/query/video_generation/{task_id}

Request

curl --request GET \
  --url https://open.wecoding.ai/v2/query/video_generation/task_01K4... \
  --header 'Authorization: Bearer $WECODING_API_KEY'

Succeeded response

{
  "task": {
    "id": "task_01K4...",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1788451200,
    "updated_at": 1788451264,
    "content": {
      "url": "https://.../generated-video.mp4"
    },
    "resolution": "768P",
    "duration": 6,
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video",
    "usage": {}
  }
}

Task states

Field	Type	Description
`queued`	`status`	Accepted and waiting to start.
`running`	`status`	Generation is in progress.
`succeeded`	`status`	Generation completed; content.url contains the video.
`failed`	`status`	Generation failed; error contains code and message.
`cancelled`	`status`	The queued task was cancelled.

List recent tasks

GET/v2/query/video_generation

Returns tasks created by the authenticated API key during the last seven days.

Filtered request

curl --get \
  --url https://open.wecoding.ai/v2/query/video_generation \
  --header 'Authorization: Bearer $WECODING_API_KEY' \
  --data-urlencode 'page_num=1' \
  --data-urlencode 'page_size=20' \
  --data-urlencode 'filter.status=succeeded' \
  --data-urlencode 'filter.model=MiniMax-H3' \
  --data-urlencode 'filter.task_type=generation'

Field	Type	Description
`page_num`	`integer`	Page number, starting at 1. Default: 1.
`page_size`	`integer`	Items per page from 1 through 100. Default: 20.
`filter.status`	`string`	queued, running, succeeded, failed, or cancelled.
`filter.task_ids`	`string[]`	Repeat the query parameter to filter by multiple task IDs.
`filter.model`	`string`	Currently only MiniMax-H3 is supported.
`filter.task_type`	`string`	Currently only generation is supported.

List response

{
  "items": [
    { "id": "task_01K4...", "model": "MiniMax-H3", "status": "running" }
  ],
  "total": 1
}

Cancel or delete a task

DELETE/v2/video_generation/{task_id}

For a queued task, this endpoint cancels it. For a succeeded or failed task, it deletes the task record. Running and already-cancelled tasks cannot be modified by this endpoint.

Request

curl --request DELETE \
  --url https://open.wecoding.ai/v2/video_generation/task_01K4... \
  --header 'Authorization: Bearer $WECODING_API_KEY'

200 OK

{
  "task_id": "task_01K4...",
  "action": "cancelled",
  "status": "cancelled"
}

Errors

Errors use a consistent envelope and include a request ID for support and tracing.

Error response

{
  "type": "error",
  "error": {
    "type": "bad_request_error",
    "message": "Invalid request fields",
    "http_code": "400"
  },
  "request_id": "req_01K4..."
}

Field	Type	Description
`400`	`Bad request`	Invalid fields, unsupported content combinations, filters, models, or task states.
`401`	`Unauthorized`	The API key is missing, invalid, expired, or revoked.
`402`	`Payment required`	Insufficient balance or credits when creating a task.
`403`	`Forbidden`	The key is not permitted to use generative models.
`404`	`Not found`	The task does not exist or belongs to another API key.
`429`	`Rate limited`	The request exceeded the applicable limit.
`500`	`Server error`	An internal error occurred. Retry with backoff and retain request_id.