Video Generation

Video generation is asynchronous, in three steps: create the job, poll for status, download the result.

Full example

import time, requests

BASE = "https://api.modelsite.ai/v1"
H = {"Authorization": "Bearer ms_live_sk_xxx", "Content-Type": "application/json"}

# 1. Create the job
job = requests.post(f"{BASE}/videos/generations", headers=H, json={
"model": "wan2.5-t2v-preview",
"prompt": "A cat playing piano on a rooftop at sunset",
"seconds": 5,
"size": "1280x720",
}).json()
video_id = job["id"]

# 2. Poll
while True:
v = requests.get(f"{BASE}/videos/{video_id}", headers=H).json()
if v["status"] in ("completed", "failed"):
    break
time.sleep(5)

if v["status"] == "failed":
raise RuntimeError(v["error"]["message"])

# 3. Download
mp4 = requests.get(f"{BASE}/videos/{video_id}/content", headers=H).content
open("out.mp4", "wb").write(mp4)

The API cards below are rendered from the OpenAPI spec (request-body parameter table, response schema).

curl -X POST "https://example.com/videos/generations" \  -H "Content-Type: application/json" \  -d '{    "model": "string",    "prompt": "string"  }'

{  "id": "string",  "object": "video",  "status": "processing",  "model": "string",  "seconds": 0,  "created_at": 0,  "completed_at": 0,  "output_url": "string",  "usage": {    "completion_tokens": 0,    "total_tokens": 0  },  "error": {    "code": "string",    "message": "string"  },  "vendor_data": {}}

curl -X GET "https://example.com/videos/video_ual7J0gEbKHcrUcqI7nV7wkR6_V57Y_vlasce6jMjWOSfTKbgVcoIhA5"

{  "id": "string",  "object": "video",  "status": "processing",  "model": "string",  "seconds": 0,  "created_at": 0,  "completed_at": 0,  "output_url": "string",  "usage": {    "completion_tokens": 0,    "total_tokens": 0  },  "error": {    "code": "string",    "message": "string"  },  "vendor_data": {}}

curl -X GET "https://example.com/videos/string/content"

"string"

Full vendor-native parameter compatibility

The standard fields above are only the cross-vendor common subset. Any parameter the upstream vendor accepts can be written at the top level of the request under its original vendor name and is forwarded verbatim — no wrapper needed, and no waiting for the platform to add field support.

{
  "model": "veo-3.0-generate-001",
  "prompt": "A cat playing piano",
  "seconds": 8,
  "sampleCount": 2,
  "personGeneration": "dont_allow",
  "storageUri": "gs://my-bucket/output/"
}

Three rules:

• Native names win. When a standard field and a native field both set the same thing, the native one wins. {"seconds": 8, "durationSeconds": 4} sends 4 upstream — if you write a native parameter you want exact control, so the translation layer yields.
• Each model only accepts its own vendor's parameters. Sending a parameter that belongs to a different vendor is rejected with a 400 — for example passing Seedance's camera_fixed to a DashScope (wan) model, or Sora's n_seconds to a Veo model. Look up parameters under the vendor of the model you are actually calling. Cross-vendor-common names (duration, seed, size, resolution, negative_prompt, …) are not restricted.
• Nested structures merge recursively. Nova Reel's videoGenerationConfig: {"fps": 30} merges with the durationSeconds / dimension derived from standard fields instead of replacing the whole object.

The response side is lossless too: every non-standard field the vendor returns is preserved under vendor_data, including fields this documentation does not yet cover.

Native parameter names by vendor

The same concept often has a different name and type at each vendor. Standard fields are translated for you; when writing native parameters you must use the original names below.

Commonly used native parameters

Vertex AI Veo (land in the request's parameters object):

Instance-level native fields (last_frame, input_video, mask, mask_mode, reference_images) are placed correctly into Veo's instances rather than leaking into parameters.

ModelArk Seedance (merged into the top level of the request):

DashScope wan: input-level native parameters (media, template, reference_urls, first_frame_url, last_frame_url, audio_url, …) are routed into the request's input object automatically, while other generation knobs go to parameters — write them at the top level and the platform places them.

Image-to-video and reference material

Two field groups with different semantics — don't mix them up:

{
  "model": "wan2.5-i2v-preview",
  "prompt": "The cat stands up and walks away",
  "seconds": 5,
  "frame_images": [
    { "image_url": "https://example.com/first.jpg", "frame_type": "first_frame" },
    { "image_url": "https://example.com/last.jpg", "frame_type": "last_frame" }
  ],
  "input_references": [
    { "type": "video", "url": "https://example.com/motion.mp4", "role": "reference_video" }
  ]
}

Vendor support for reference material varies widely; vendors that don't support it silently ignore input_references rather than erroring.

Size: two equivalent forms

size and resolution + aspect_ratio express the same thing — pick one:

{ "size": "1280x720" }
{ "resolution": "720p", "aspect_ratio": "16:9" }

Sending both with conflicting values returns 400. The alias ratio (the DashScope / ModelArk native name) is equivalent to aspect_ratio.

Billing

Billed by video duration: cost = duration (seconds) × the model's per-second rate. Duration is taken from the actual generated result; failed jobs are not billed. Rates are on the models page.

Error handling

When status is failed, read the error object:

{
  "id": "video_xxx",
  "object": "video",
  "status": "failed",
  "error": { "code": "content_policy_violation", "message": "..." }
}

Common causes: the prompt tripped content moderation, a reference image was unreachable, or the requested duration / size combination is unsupported by that model. Parameter errors are returned as 400 at creation time and never enter the async flow. Full error codes are on the error handling page.