Guides / Video models

Video models

Create videos from text, images, or reference media, then query the task to get the result.

Asynchronous

API key required

Create an API key and select the required video model under Supported models before calling the video model endpoint.

Supported models

Choose a model below and check its supported inputs, aspect ratios, and resolutions.

Model	Generation mode	Aspect ratio	Resolution	Price
`minimax-h3`	`t2v, i2v, r2v`	`16:9, 4:3, 1:1, 3:4, 9:16, adaptive`	`768P`	$0.10/s
`minimax-h3-pai`	`t2v, i2v, r2v`	`21:9, 16:9, 4:3, 1:1, 3:4, 9:16, adaptive`	`768P`	$0.10/s
`minimax-h3-vdn-8step`	`t2v, i2v`	`16:9, 4:3, 1:1, 3:4, 9:16, adaptive`	`768P`	$0.05/s

t2v means text-to-video, i2v means image-to-video, and r2v means reference-to-video. adaptive is only available for image-to-video and reference-to-video.

Set model to a video model ID. Model names are case-insensitive. Charges follow the selected model's pricing.

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. To generate videos, select the required video model under Supported models when creating the key in the console.

Supported inputs

Available inputs and aspect ratios depend on the selected model. Check Supported models before creating a task.

Text-to-video with an explicit aspect ratio.
First-frame and optional last-frame image-to-video.
Reference images, videos, and audio supported by the selected model.

Currently unsupported:H3 Context IR, regeneration, and callbacks.

Discover models

GET/v1/models

Field	Type	Description
`include_generative_models`	`boolean`	Defaults to true. Set to false to exclude generative models from the model list.

Request

curl --request GET \
  --url 'https://open.wecoding.ai/v1/models' \
  --header 'Authorization: Bearer $WECODING_API_KEY'

Use /v1/models to find video models and their supported parameters. Make sure your API key has access to the model you choose.

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`	Video model ID from /v1/models. Case-insensitive.
`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`	MiniMax-H3 supports 768P or 2K.
`ratio`	`string`	Required for text-to-video. For image-to-video, fixed values are ignored and Owl infers the nearest supported output ratio from frame dimensions; reference-to-video infers from its first image/video by default or accepts a fixed ratio.

Content items

Field	Type	Description
`text`	`{ type, text }`	Prompt text. text must contain 1–7,000 characters.
`image_url`	`{ type, image_url, role? }`	HTTPS or data URL image: JPEG, PNG, WebP, HEIC, or HEIF; up to 30 MiB, 256–5760 px per side, and width/height ratio 0.4–2.5. Roles are first_frame, last_frame, or reference_image; one image without a role defaults to first_frame. Owl checks dimensions for supported JPEG, PNG, WebP, HEIC, and HEIF files.
`video_url`	`{ type, video_url, role }`	HTTPS MP4/MOV or data:video/mp4 URL, role reference_video. Up to 50 MiB and 2–15 seconds each; 256–5760 px per side, width/height ratio 0.4–2.5, and 23.976–60 fps. Official codecs are H.264/H.265 video with AAC/MP3 audio. Owl checks video codec and average frame rate when MP4/MOV is parseable; the Worker/provider checks audio codec and unsupported containers.
`audio_url`	`{ type, audio_url, role }`	HTTPS WAV/MP3 or data:audio/wav or data:audio/mpeg URL, role reference_audio. Up to 15 MiB and 2–15 seconds each; total reference audio is limited to 15 seconds. Reference audio requires a reference image or video.

Image-guided example

JSON body

{
  "model": "minimax-h3-turbo-v4",
  "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-turbo-v4",
    "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-turbo-v4' \
  --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`	Filter by video model ID. Case-insensitive.
`filter.task_type`	`string`	Currently only generation is supported.

List response

{
  "items": [
    { "id": "task_01K4...", "model": "minimax-h3-turbo-v4", "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 requested video model is not selected for this API key.
`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.