Vidu Video API Overview

Vidu video generation is asynchronous: create a task, retain its returned ID, poll its state, and download the successful result. This series references the official Vidu Q4 Preview image-to-video API and describes the models and interfaces currently available through ModelSell.

Models and available operations

Generation and billing have been verified for these six Q2 / Q3 models. Use the exact model names above and an API Key with access to the required group and model. Official Q3 Turbo reference-to-video capability does not mean that operation is enabled on the current channel.

Protocol support exists for viduq4-preview, and this series includes its parameters and a conditional example. A usable production channel has not been confirmed. Call it only after the model catalog, permissions, and channel support it; this page does not announce Q4 availability.

Base URL and authentication

export MODELSELL_BASE_URL="https://api.modelsell.com"
export MODELSELL_API_KEY="<your-modelsell-api-key>"

Send requests to ModelSell with Authorization: Bearer $MODELSELL_API_KEY. Creation requests use Content-Type: application/json; allow at least 300 seconds for the HTTP request. For a custom gateway domain, replace only MODELSELL_BASE_URL.

The official api.vidu.cn domain and Authorization: Token ... header apply to direct Vidu access. ModelSell requests use the address and Bearer authentication above.

Choose a request format

Use native requests to migrate official examples or access complete model parameters. Generic video requests reuse common fields such as model, prompt, images, seconds, and size.

The returned task_… is a ModelSell public task ID. Query with the real ID from the creation response and the same ModelSell API Key. Do not substitute an official example ID, upstream ID, or callback ID.

Create a Q3 text-to-video task

curl --max-time 300 "$MODELSELL_BASE_URL/ent/v2/text2video" \
  -H "Authorization: Bearer $MODELSELL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "viduq3-turbo",
    "prompt": "A red ceramic teapot sits on a wooden table in warm morning light. The camera slowly moves closer.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "audio": false,
    "is_rec": false,
    "watermark": false,
    "seed": 0
  }'

Example creation response; fields can vary by model:

{
  "task_id": "task_example_vidu",
  "state": "created",
  "model": "viduq3-turbo"
}

Poll and retrieve the video

Save the actual task_id and poll every 10–15 seconds:

export TASK_ID="<returned-task-id>"
curl --max-time 300 "$MODELSELL_BASE_URL/ent/v2/tasks/$TASK_ID/creations" \
  -H "Authorization: Bearer $MODELSELL_API_KEY"

The public ID is the top-level id in native query responses, whereas creation responses use task_id. A successful result has this shape:

{
  "id": "task_example_vidu",
  "state": "success",
  "err_code": "",
  "credits": 35,
  "creations": [{
    "id": "creation_example",
    "url": "https://example.com/generated-video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "watermarked_url": "https://example.com/watermarked-video.mp4"
  }]
}

Credits and URLs above are illustrative. Official documentation gives video, cover, and watermarked result URLs a 24-hour lifetime. Download or copy results promptly. See Python Polling and Download for a complete example.

Billing and error handling

Creation reserves quota. Successful tasks settle against task credits and the model price; failed tasks follow the refund workflow. Queries do not incur another generation charge. credits represents Vidu credits, not dollars or token usage. See ModelSell Vidu pricing and your group's prices.

Current channels provide immediate generation and reject off_peak: true. Q3 prompt expansion with is_rec: true is not enabled; provide a clear prompt and send is_rec: false. Native requests preserve explicit false and 0 values.

For HTTP errors, retain the status, response body, and request identifier. If creation times out, establish whether the task was accepted before retrying. A local polling timeout does not cancel a task or establish that a refund occurred. This series exposes creation and query APIs; task listing, cancellation, deletion, and account-balance APIs are not available.

The upstream service delivers callback_url notifications directly and may use an upstream task ID. Confirm results using the public ID returned by ModelSell creation.