Complete Video API Standard

This is the customer-facing standard for asynchronous video generation through cnAPI. Always use the public cnAPI model name and the public task id returned by the API.

All current public video models share the create, polling/webhook, and download lifecycle. Reference-media fields are model-family specific, however; do not apply one family's media example to every model.

Endpoints

Authorization: Bearer sk-your-api-key
Content-Type: application/json
Accept: application/json

Keep API keys on your server. Never embed them in browser, mobile, or desktop client code.

Basic text-to-video request

curl --request POST 'https://cnapi.vip/v1/videos' \
  --header 'Authorization: Bearer sk-xxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "SD2.5 720P",
    "prompt": "A silver sports car driving through a neon city at night, cinematic tracking shot",
    "duration": 8,
    "size": "16:9"
  }'

You may use an integer duration or a string seconds, for example "8".

Common request fields

Output resolution is fixed by the public model name. Do not attempt to change a model tier by overriding resolution.

Reference media

Reference images

Use the top-level images array for consistent behavior across current models:

{
  "model": "SD2.5 720P",
  "prompt": "Keep the same character identity and clothes, walking by the sea",
  "duration": 10,
  "size": "16:9",
  "images": [
    "https://cdn.example.com/character-front.jpg",
    "https://cdn.example.com/character-side.jpg"
  ]
}

Reference videos and audio for multi-reference models

For the SD, Seedance, H3, Wan, and Kling families that support multiple references, put video and audio references in metadata:

{
  "model": "SD2.5 720P",
  "prompt": "Use the product appearance, camera motion, and sound rhythm from the references",
  "duration": 12,
  "size": "16:9",
  "images": ["https://cdn.example.com/product.jpg"],
  "metadata": {
    "referenceVideos": [
      "https://cdn.example.com/camera-motion.mp4"
    ],
    "referenceAudios": [
      "https://cdn.example.com/sound-reference.mp3"
    ]
  }
}

Do not submit multiple aliases for the same media type. For example, do not send both top-level images and metadata.referenceImages; compatibility aliases are selected, not guaranteed to be merged.

For minimax-h3-768p, an audio reference requires at least one image, video, or first frame.

First and last frames

{
  "model": "Seedance-2.5-720p官方版",
  "prompt": "Smoothly transition from the morning frame to the night frame",
  "duration": 10,
  "size": "16:9",
  "metadata": {
    "firstFrame": "https://cdn.example.com/start.jpg",
    "lastFrame": "https://cdn.example.com/end.jpg"
  }
}

lastFrame requires firstFrame. For models marked as exclusive below, keyframes cannot be mixed with ordinary image, video, or audio references.

Media URL requirements

• Prefer directly downloadable public HTTPS URLs.
• URLs must not require cookies, login state, Referer, or custom headers.
• Do not use localhost, private IPs, container hostnames, or intranet-only URLs.
• Keep URLs valid for at least 60 minutes after task creation.
• Recommended formats: JPG/PNG/WebP, MP4/MOV, and MP3/WAV.
• Keep each reference video below 50 MB and each reference audio file below 15 MB when possible.
• Only submit material you are authorized to use.

Current public model capabilities

Veo

The two public Veo models support 4/6/8 seconds and 720P/1080P. They accept text or one input image, but not reference video or reference audio. Use metadata.negativePrompt, metadata.seed, and metadata.generateAudio for Veo-specific controls.

{
  "model": "veo-3.1-fast",
  "prompt": "Keep the subject from the reference image and slowly push the camera forward",
  "duration": 8,
  "size": "1920x1080",
  "images": ["https://cdn.example.com/reference.jpg"],
  "metadata": {
    "negativePrompt": "blur, distortion",
    "generateAudio": true
  }
}

Grok video

Grok video accepts text or one input image. It does not accept multiple images, reference video, or reference audio. Set 480P/720P with metadata.resolution; the -1080p model is fixed at 1080P.

{
  "model": "grok-imagine-video-1.5",
  "prompt": "Keep the subject and slowly pull the camera back",
  "duration": 8,
  "size": "16:9",
  "images": ["https://cdn.example.com/start.jpg"],
  "metadata": { "resolution": "720p" }
}

Gemini Omni video

gemini-omni-flash outputs 720P and accepts up to ten images or one reference video. Its reference video must use top-level video/videos, not metadata.referenceVideos. The video must be MP4/MOV, no longer than ten seconds, and no larger than 64 MiB.

{
  "model": "gemini-omni-flash",
  "prompt": "Use the motion from the video and the product from the image",
  "duration": 6,
  "size": "16:9",
  "images": ["https://cdn.example.com/product.jpg"],
  "video": "https://cdn.example.com/reference.mp4"
}

Available models and account access may change. Use the live model list for discovery.

Model-specific rules: Veo, Grok, and Gemini Omni must use their family examples above rather than the multi-reference fields; SD2.0 720P allows at most 12 ordinary references in total; minimax-h3-768p requires a visual reference when reference audio is present; wan3.0-video-* can omit the prompt when media is supplied, although a prompt is still recommended; and kling-3.0-turbo-* does not accept reference audio but does support generate_audio. Resolution suffixes are part of the exact model name and must not be removed.

Create response

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "SD2.5 720P",
  "status": "queued",
  "progress": 0,
  "created_at": 1788249600
}

Save id. task_id is retained for legacy compatibility. HTTP 200 means the task was accepted, not that generation has finished.

Polling

curl 'https://cnapi.vip/v1/videos/task_xxx' \
  --header 'Authorization: Bearer sk-xxxx'

Wait 3–5 seconds before the first query, poll every 10–15 seconds, and use a total timeout of at least 30 minutes. Do not submit a duplicate while the original task is still active.

Webhooks

Set a public callback_url in the create request. It must be no longer than 2048 characters, must not target localhost or private networks, and should return a 2xx response within 15 seconds.

Terminal events are video.completed and video.failed:

{
  "id": "evt_task_xxx_completed",
  "type": "video.completed",
  "created_at": 1788250200,
  "data": {
    "task_id": "task_xxx",
    "model": "SD2.5 720P",
    "status": "completed",
    "progress": "100%",
    "output_url": "https://cnapi.vip/v1/videos/task_xxx/content",
    "created_at": 1788249600,
    "completed_at": 1788250200
  }
}

Relevant headers:

X-NewAPI-Event: video.completed
X-NewAPI-Delivery: evt_task_xxx_completed
X-NewAPI-Timestamp: 1788250200
X-NewAPI-Signature: sha256=<hex-hmac>

Verify HMAC-SHA256 over:

X-NewAPI-Timestamp + "." + raw request body bytes

Use the full API key, including the sk- prefix, as the HMAC secret. Compare signatures in constant time and deduplicate deliveries using X-NewAPI-Delivery or the event id.

Reject callbacks whose timestamp differs from your server time by more than five minutes to reduce replay risk.

Failed deliveries use exponential backoff. Each attempt has a 15-second timeout; delivery is attempted up to eight times, with a maximum backoff of 15 minutes. Polling may be used as a fallback alongside webhooks.

Downloading the result

After status=completed:

curl --location \
  'https://cnapi.vip/v1/videos/task_xxx/content' \
  --header 'Authorization: Bearer sk-xxxx' \
  --output result.mp4

Clients must follow HTTP redirects. Copy completed assets to your own object storage if you need permanent retention.

Treat webhook output_url as opaque and potentially temporary. Do not parse or depend on its hostname or path layout.

Retry and error rules

• 400: invalid model, duration, ratio, field placement, or reference count.
• 401: missing or invalid API key.
• 403: the key cannot access the model or group.
• 404: task not found, not owned by the account, or content not ready.
• 429: apply Retry-After or exponential backoff.
• 5xx: status queries may be retried with backoff.
• status=failed: the HTTP query succeeded but generation failed; inspect error.message.

POST /v1/videos does not currently guarantee customer-provided idempotency keys. If a fully transmitted create request ends with an ambiguous network timeout, do not blindly resubmit it because duplicate tasks may be generated and billed.