Submit a video-generation task (text-to-video / image-to-video) — async task model, returns a task_id for polling

Submit a video-generation task. Video generation is asynchronous: this endpoint returns a task_id immediately after validation. Use Get Video Task Status to poll until status=completed, then download the video.

Field	Value
Method	`POST`
Path	`/v1/video/generations`
Full URL	`https://api.amux.ai/v1/video/generations`
Auth	`Authorization: Bearer <API_TOKEN>`
Request format	`application/json`
Response format	`application/json`

Universal contract: this endpoint provides a vendor-neutral schema. amux-api converts the universal request into vendor-native formats (Doubao Seedance / Kling / Jimeng / Aliyun Wan, etc.) at the gateway. There is also an OpenAI Sora-compatible alias POST /v1/videos that accepts the same request body.

Request Body

Prop

Type

Passthrough: amux-api forwards vendor-specific fields to the upstream via the metadata field. For example:

Doubao Seedance family: aspect_ratio / camera_fixed / watermark, etc.
Kling: negative_prompt / cfg_scale / mode / aspect_ratio / camera_control
Jimeng: negative_prompt / aspect_ratio
Aliyun Wan: negative_prompt / prompt_extend

Refer to the upstream model's documentation for the exact set of supported fields.

Examples

Text-to-Video

curl https://api.amux.ai/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AMUX_API_KEY" \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "A cute baby sea otter wearing a beret, rolling in a spring courtyard with falling cherry blossoms",
    "duration": 5,
    "width": 1280,
    "height": 720,
    "fps": 24,
    "metadata": {
      "aspect_ratio": "16:9"
    }
  }'

import os
import httpx

response = httpx.post(
    "https://api.amux.ai/v1/video/generations",
    headers={"Authorization": f"Bearer {os.environ['AMUX_API_KEY']}"},
    json={
        "model": "doubao-seedance-2.0",
        "prompt": "A cute baby sea otter wearing a beret, rolling in a spring courtyard with falling cherry blossoms",
        "duration": 5,
        "width": 1280,
        "height": 720,
        "fps": 24,
        "metadata": {"aspect_ratio": "16:9"},
    },
)

task = response.json()
print(f"Task ID: {task['task_id']}, Status: {task['status']}")

const response = await fetch('https://api.amux.ai/v1/video/generations', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.AMUX_API_KEY}`,
  },
  body: JSON.stringify({
    model: 'doubao-seedance-2.0',
    prompt: 'A cute baby sea otter wearing a beret, rolling in a spring courtyard with falling cherry blossoms',
    duration: 5,
    width: 1280,
    height: 720,
    fps: 24,
    metadata: { aspect_ratio: '16:9' },
  }),
});

const task = await response.json();
console.log(`Task ID: ${task.task_id}, Status: ${task.status}`);

Image-to-Video

curl https://api.amux.ai/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AMUX_API_KEY" \
  -d '{
    "model": "kling-v2-master",
    "image": "https://example.com/source.jpg",
    "prompt": "Camera slowly zooms in as the subject begins to walk forward",
    "duration": 5,
    "metadata": {
      "negative_prompt": "blurry, low quality",
      "cfg_scale": 0.7,
      "mode": "std",
      "aspect_ratio": "16:9"
    }
  }'

Response Example

{
  "task_id": "abcd1234efgh",
  "status": "queued"
}

Response Fields

Prop

Type

Status Enum

Possible status values (see Get Task Status for details):

Status	Meaning
`queued`	Queued, awaiting execution
`in_progress`	Generating
`completed`	Done — video is ready
`failed`	Failed
`unknown`	Unknown state (fallback)

Error Response

{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "param": "model",
    "code": "invalid_value"
  }
}

HTTP Status	Meaning
`200`	Task submitted successfully
`400`	Bad request parameters (model not a video model, missing fields, etc.)
`401`	Missing or invalid API key
`403`	Model not authorized or blocked by content safety policy
`429`	Rate limit triggered or insufficient balance
`500` / `502` / `503`	Server-side error or upstream unavailable

Next Steps

Get Video Task Status — poll progress and retrieve the final video
Doubao Seedance 2.0 Series — dedicated parameter reference for doubao-seedance-2.0 and doubao-seedance-2.0-fast

Create Video Generation Task