Video generation

Search /

Video models answer as tasks rather than as a single response. POST /v1/videos returns a task id with "status": "queued", and GET /v1/videos/{task_id} reports progress until the task reaches completed or failed. On completion the finished file is the signed URL under metadata.url; it carries an Expires parameter, so download the file rather than storing the link. A failed task carries the upstream code and text in error.code and error.message, which is usually enough to see which field the request was missing. POST /v1/video/generations reaches the same handler for clients already written against that path.

POST /v1/videos

curl https://api.chinaapi.ai/v1/videos \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-i2v",
    "prompt": "the cat turns and walks toward the camera",
    "input_reference": "https://example.com/first-frame.jpg",
    "size": "1280*720",
    "duration": 5
  }'

# {"id":"task_9f2c...","task_id":"task_9f2c...","object":"video",
#  "model":"wan2.7-i2v","status":"queued","progress":0}

GET /v1/videos/{task_id}

curl https://api.chinaapi.ai/v1/videos/task_9f2c... \
  -H "Authorization: Bearer $CHINAAPI_KEY"

# {"id":"task_9f2c...","object":"video","model":"wan2.7-i2v",
#  "status":"completed","progress":100,
#  "metadata":{"url":"https://.../output.mp4?Expires=..."}}

Text to video

wan2.7-t2v

model and prompt are the only required fields. Without size and duration the gateway submits 1280*720 for five seconds.

Image to video

wan2.7-i2v

Animate a still image. input_reference takes a publicly reachable image URL and becomes the first frame; send size and duration with it.

Reference to video

wan2.7-r2v

Build a video from reference material. input_reference takes one reference image; to pass several use images instead, and video_url adds a reference video — references count together, up to five. Do not send input_reference and images together, because the gateway keeps only input_reference.

Video editing

wan2.7-videoedit

Edit an existing clip from a prompt. video_url takes the source video, which has to be 2 to 10 seconds of MP4 or MOV, and size sets the output.

30-second video

doubao-seedance-2-5-260628

Reference images go in images, and input_reference takes a single one; sending both keeps both. Length goes in seconds or duration, and vendor parameters go in metadata, where resolution is either 480p or 720p.

Seedance 2.0

doubao-seedance-2-0-260128

Same request shape as doubao-seedance-2-5-260628, including the role rules for metadata.content. doubao-seedance-2-0-fast-260128 and doubao-seedance-2-0-mini-260615 trade quality for speed and cost, and the 2.0 line needs at least one image or video reference where 2.5 also accepts audio alone.

Kling 3.0

kling-v3

The first frame goes in image; this family never reads input_reference. mode defaults to std and duration to 5 seconds. metadata carries the rest: image_tail for a closing frame, sound as on or off (off by default), plus negative_prompt, cfg_scale and camera_control.

Value tier

kling-3.0-turbo

Send prompt for text to video, or add image and the gateway builds the contents array upstream expects. Sizing lives under metadata.settings: resolution is 720p or 1080p, duration runs 3 to 15 seconds, and aspect_ratio is 16:9, 9:16 or 1:1. Audio is always included and has no switch.

Multi-image reference

kling-v3-omni

Reference-driven generation from several images at once. Every parameter lives in metadata, and there is no resolution field — mode is the quality tier. See the worked example below.

Native audio

MiniMax-H3

Takes the gateway's own fields and assembles the upstream payload for you: image or input_reference becomes the first frame, images become reference images, and video_url becomes a reference video. size selects 768P or 2K and duration is a whole number from 4 to 15. Text-only requests need an explicit metadata.ratio other than adaptive.

Hailuo

MiniMax-Hailuo-2.3

Together with MiniMax-Hailuo-2.3-Fast and MiniMax-Hailuo-02. These read only prompt, duration and size from the top level; every image goes through metadata, as first_frame_image, last_frame_image or subject_reference.

480P tier

happyhorse-1.1-t2v

With happyhorse-1.1-i2v and happyhorse-1.1-r2v. The fields match the wan2.7 family — prompt, input_reference, size, duration — and 480P is priced here, so 832*480 is accepted where wan2.7 refuses it. Multiple references go in metadata.input.media, because the automatic assembly the images field triggers is specific to wan2.7-r2v.

Tip Spell size as width and height joined by an asterisk, as in 1280*720. The letter x is not accepted: 832x480 comes back as invalid size: 832x480, example: 1920*1080. duration is a whole number of seconds. For wan2.7-i2v, wan2.7-r2v and wan2.7-videoedit the gateway folds size into a resolution tier and upstream has only two, so send 1280*720 for 720P or 1920*1080 for 1080P. A 480P size such as 832*480 has no price at these three and is either refused outright or accepted and then failed upstream with InvalidParameter; a failed task is refunded, but the round trip is wasted either way. wan2.7-t2v takes the value as written.

Tip The Kling family reads the aspect ratio from size through a fixed table that spells sizes with the letter x — 1280x720, 1920x1080, 720x1280, 1080x1920, 1024x1024, 512x512 — and anything it does not recognise becomes 1:1 without an error. Sending the asterisk form 1280*720 to kling-v3 therefore returns a square video rather than a complaint, so set metadata.aspect_ratio directly when the framing matters.

Tip MiniMax-Hailuo-2.3, MiniMax-Hailuo-2.3-Fast and MiniMax-Hailuo-02 drop top-level image, input_reference, images and video_url without saying so: the request succeeds, but it runs as text to video and is billed as such. Put the image in metadata.first_frame_image instead, add metadata.last_frame_image for a closing frame, and use metadata.subject_reference for subject references. MiniMax-H3 is the exception in this family and does read the top-level fields.

kling-v3-omni · multi-image reference

curl https://api.chinaapi.ai/v1/video/generations \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "prompt": "the character from the references walks through a neon-lit street",
    "metadata": {
      "image_list": [
        {"image_url": "https://example.com/character.jpg"},
        {"image_url": "https://example.com/outfit.jpg"},
        {"image_url": "https://example.com/scene.jpg"}
      ],
      "mode": "std",
      "duration": "5",
      "aspect_ratio": "16:9",
      "sound": "off"
    }
  }'

GET /v1/video/generations/{task_id}

curl https://api.chinaapi.ai/v1/video/generations/task_9f2c... \
  -H "Authorization: Bearer $CHINAAPI_KEY"

# {"code":"success",
#  "data":{"task_id":"task_9f2c...","status":"SUCCESS",
#          "progress":"100%","fail_reason":"",
#          "result_url":"https://.../output.mp4"}}

Tip A reference image carries no type; the field exists only to mark first_frame or end_frame, and aspect_ratio is required whenever no first frame is present. mode is the quality tier — std, pro or 4k — and the upstream default is pro, which bills 1.33x the listed price, while 4k bills 5x; send mode explicitly so the charge is the one you expect. duration is a string from "3" to "15" and sound defaults to off. A reference video goes in video_list and must set "refer_type": "feature": the editing mode base is billed by the length of the video you supply, cannot be priced before submission, and is refused. Reference images also have a minimum size upstream, and an icon-sized file passes submission only to fail the task with Image pixel is invalid; the failed task is refunded, but the round trip is lost.

Tip The two paths report results in different shapes. GET /v1/videos/{task_id} answers in the OpenAI video format, where the file is metadata.url and progress is a number. GET /v1/video/generations/{task_id} answers {"code": "success", "data": {…}}, where the file is data.result_url, data.status is an upper-case word such as SUCCESS or FAILURE, data.progress is a string such as "100%", and a failure explains itself in data.fail_reason. Poll whichever path you submitted to.

doubao-seedance-2-5-260628 · first frame

curl https://api.chinaapi.ai/v1/videos \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "the subject slowly turns toward the camera",
    "images": ["https://example.com/first-frame.jpg"],
    "seconds": "5",
    "metadata": {"resolution": "480p"}
  }'

doubao-seedance-2-5-260628 · reference mode

curl https://api.chinaapi.ai/v1/videos \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "keep the subject from the reference image",
    "seconds": "5",
    "metadata": {
      "resolution": "480p",
      "ratio": "16:9",
      "content": [
        {
          "type": "image_url",
          "image_url": {"url": "https://example.com/reference.jpg"},
          "role": "reference_image"
        }
      ]
    }
  }'

Tip An image with no role is read as the first frame rather than as a reference: the output follows the aspect ratio of that image, sending ratio alongside it is refused with InvalidParameter.TaskTypeConstraint, and a seconds of 2 is refused there as well, while 5 works. generate_audio defaults to true upstream, so the file comes back with an audio track unless you set it to false in metadata. Tag every part of metadata.content with a role to reach the full reference mode — up to 30 images, 10 videos and 10 audio clips, audio-only input, and 30 seconds in one shot — where ratio is accepted.