Create Video Generation Task

Video generation is an asynchronous task: submit task → poll status → fetch result. This page documents the generic task format's creation endpoint; text-to-video, image-to-video, first/last-frame, multi-reference-image, and video-to-video all share the same endpoint (see Input Materials & Generation Modes below). Available models and prices are subject to the real-time listing on the Model Plaza.

TIP

Besides the generic task format, more formats are supported — Kling, Jimeng, Doubao / Seedance, and Sora. The first three mirror the vendors' official endpoint structures (Doubao reuses this endpoint), intended for users with existing code against those vendor APIs. MiniMax-H3 also reuses this endpoint, with hard channel differences (only 768p / 2K resolutions, aspect ratio required for text-to-video) — see the MiniMax format.

Endpoint

POST /v1/video/generations

Authentication

Send a Bearer token in the request header (see Base URLs & Auth for how to get one):

Authorization: Bearer sk-your-token

Request Body

FieldTypeRequiredNotes
promptstringYesText prompt describing the video; must not be empty
modelstringYesModel name — a video model on sale in the Model Plaza (the gateway routes by model)
imagestringNoFirst-frame image for image-to-video (URL or Base64); presence switches to image-to-video
imagesstring[]NoMulti-image input; for a single image use image (the gateway merges it into images automatically); multiple images make the multi-reference-image mode
modestringNoChannel-specific parameter. Kling channel: resolution tier, std (720p) / pro (1080p) etc.; defaults to std
sizestringNoFrame size, width x height (e.g. 1280x720). The Kling channel only derives the aspect ratio (16:9 / 9:16 / 1:1); the resolution tier is controlled by mode
durationintegerNoDuration (seconds); the gateway validates 1–3600. Defaults to 5 on the Kling channel
secondsstringNoString form of the duration; alternative to duration
input_referencestringNoReference material input (supported by some channels)
metadataobjectNoExtra parameters object, merged into the upstream request body as a whole: on the Kling channel you can pass negative_prompt, image_tail, callback_url, external_task_id etc. to override defaults
metadata.first_frame_url / metadata.last_frame_urlmetadatastringFirst/last-frame video: first and last frame image URLs, both passed together (mutually exclusive with images references)
metadata.video_urlsmetadatastring[]Video-to-video: source video URL list; multiple entries make multi-reference-video
metadata.audio_urlsmetadatastring[]Reference audio (mp3 / wav), some channels pair it with metadata.generate_audio
WARNING

The gateway (new-api rc.25) only accepts the fields above. width, height, fps, seed, n, response_format, user and similar fields are silently dropped — no error, no effect: control the frame with size + mode, and the duration with duration. Mind the channel difference: the Doubao (Seedance) channel takes the duration via seconds (a top-level duration has no effect there), and the frame via metadata — see Doubao / Seedance Format. Actual values supported per model (duration tiers, resolution, etc.) defer to the model details on the Model Plaza and real responses.

Input Materials & Generation Modes

The same endpoint routes to a generation mode automatically based on the material fields passed:

ModeTrigger
Text-to-videoprompt only
Image-to-videoone image via image / images
Multi-reference-imagemultiple images in images, each as a reference
First/last-framemetadata.first_frame_url + metadata.last_frame_url, both passed together
Video-to-videosource video in metadata.video_urls; multiple entries = multi-reference-video
Reference audiometadata.audio_urls with metadata.generate_audio (channel-dependent)

Material constraints: images png / jpg / jpeg / webp, videos mp4 / mov / webm, audio mp3 / wav; URLs must be publicly reachable (mainland CDN / OSS preferred — overseas image hosts may be blocked upstream); when passing several materials, describe each one's purpose in prompt.

WARNING

Material fields are merged into the upstream request body as a whole; the gateway does not validate their values. Top-level first_frame_url and the like are silently dropped. Supported input modes differ per model (channel differences for Doubao / Kling / MiniMax-H3 are on their own pages) — defer to the Model Plaza details and channel errors.

Request Example

Scenarios 3–5 below use MiniMax-H3 (metadata.resolution / ratio are required on that channel — see the MiniMax format); for other models swap model and the channel parameters accordingly.

cURL
Python
Node.js
# Scenario 1: text-to-video
curl -X POST https://api-model.shuntianchuang.cn/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-token" \
  -d '{
    "model": "kling-video-v2.5-turbo",
    "prompt": "An orange cat chasing butterflies on a lawn, cinematic shot, slow zoom in",
    "duration": 5,
    "size": "1280x720",
    "mode": "std"
  }'
# Scenario 2: image-to-video (image takes the first-frame image URL or Base64)
curl -X POST https://api-model.shuntianchuang.cn/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-token" \
  -d '{
    "model": "kling-video-v2.5-turbo",
    "prompt": "Make the cat in the frame run, camera slowly zooming in",
    "image": "https://example.com/first-frame.jpg"
  }'
# Scenario 3: first/last-frame video (frames passed through via metadata)
curl -X POST https://api-model.shuntianchuang.cn/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-token" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "Transition from the morning sky of the first frame to the dusk shore of the last frame, camera panning slowly",
    "metadata": {
      "resolution": "768p",
      "ratio": "16:9",
      "first_frame_url": "https://example.com/first-frame.jpg",
      "last_frame_url": "https://example.com/last-frame.jpg"
    }
  }'
# Scenario 4: multi-reference-image (multiple images in images, each a reference)
curl -X POST https://api-model.shuntianchuang.cn/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-token" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "The first image provides the subject, the second provides the background style; bring the subject to life in that background",
    "images": [
      "https://example.com/ref-1.jpg",
      "https://example.com/ref-2.jpg"
    ],
    "metadata": { "resolution": "768p" }
  }'
# Scenario 5: video-to-video (source video in metadata.video_urls; multiple = multi-reference-video)
curl -X POST https://api-model.shuntianchuang.cn/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-token" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "Convert the video content to a watercolor style while keeping the original motion",
    "metadata": {
      "resolution": "768p",
      "video_urls": ["https://example.com/source.mp4"]
    }
  }'

Response

A successful submission returns a task object — keep the task_id for querying:

{
  "id": "task_xxxxxxxx",
  "object": "video",
  "task_id": "task_xxxxxxxx",
  "status": "queued",
  "model": "kling-video-v2.5-turbo",
  "created_at": 1769473000
}

Failed request validation (e.g. empty prompt, out-of-range duration) returns 400 with an error description:

{
  "code": "invalid_seconds",
  "message": "seconds must be between 1 and 3600",
  "data": null
}

Billing is settled on actual usage at task completion (auto-refunded on failure). After submission, poll the task status — see Get Video Generation Task Status.