VidBudget
vidu-q4

Vidu Q4 · API

Markdown

POST https://vidbudget.com/v1/videos/generations

Asynchronous video generation · Billed per second · No charge for failed tasks

Try it online →

Quick start: submit → query → download

This is an asynchronous video API. A successful submit returns HTTP 202 and a task ID; video generation and media processing run in the background. Do not wait for the submit request to return the video.

Save the task ID and query it every 5–10 seconds. If a request is interrupted, keep querying the original task; if you need to resend the submit, use the same idempotency key and exactly the same parameters.

cURL · Submit
curl https://vidbudget.com/v1/videos/generations \
  -H "Authorization: Bearer $VIDBUDGET_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
  "model": "vidu-q4",
  "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
  "duration": 5,
  "resolution": "720P",
  "aspect_ratio": "16:9",
  "images": [
    "https://media.vidbudget.com/inputs/YOUR_IMAGE_UUID.png"
  ]
}'

Authentication and headers

Create an API key in the Console. The key is shown only once, when it is created; never put it in public browser code, URLs or logs.

HTTP
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_ID

Specs and scope

This model makes a video from reference images: send at least 1 image. Reference images describe characters, scenes, products and style; they do not set the first or last frame. Make sure you have the right to use your input media and the likeness of any person in it.

Whether each combination can be generated right now is given by availability in GET /v1/models; when one temporarily cannot be generated, you get 503 and nothing is charged.

Spec Supported
Durations 3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 / 13 / 14 / 15 / 16 seconds
Resolutions 720P
Aspect ratios 16:9 / 9:16 / 1:1 / 4:3 / 3:4
Reference images Up to 10 images
Reference videos Not supported
Reference audio Up to 3 audio clips
Prompt Up to 2000 characters / 6000 UTF-8 bytes
Billing unit Per generated second
Video retention 72 hours; download in time

Request parameters

Content-Type is application/json. Do not treat unsupported parameters as working settings: callback_url, n (several outputs), first/last frames and streaming output are not offered.

Parameter Type Required Description
model string Yes vidu-q4
prompt string Yes Describes the video. Refer to media as @Image1 / @Video1 / @Audio1; the number follows the order in each array.
duration integer No Default 5 seconds; see Specs for the range. Clip portrait requires an explicit 15 seconds.
resolution string No Default 720P; options: 720P
aspect_ratio string No Default 16:9. Aliases: size, ratio; they must not conflict.
images array<string> Yes Array of HTTPS image URLs. Aliases: reference_images, image_url, image; send only one field per media type.
video_references array<string> No Array of HTTPS video URLs; do not send it when this model does not support it. Aliases: video_reference, video_url.
audio_references array<string> No Array of HTTPS audio URLs; do not send it when this model does not support it. Aliases: audio_reference, audio_url.
audio boolean No Not allowed on per-clip products; defaults to true on the others. false does not guarantee a video without sound; that depends on the model itself. Alias: generate_audio.
seconds integer No Alias of duration; when you send both, they must be equal.
image_role string No Accepts only reference / reference_images / ref; first and last frames are not supported.

Pricing and billing

The prices below are read from the live price configuration, the same source the billing code uses. The hold and the task record are written in one transaction at submit; a success is settled, and a final failure returns the hold.

Resolution Unit price (USD) Example cost
720P 0.065 / second 5 seconds: $0.33

Reference media and examples

Upload your media first and query the upload task; once you have the media.vidbudget.com URL, put it in the matching array. Publicly downloadable HTTPS media URLs work too. base64 and data: URIs are not accepted.

Images can serve as character and style references, videos as motion and camera-movement references, and audio as sound and rhythm references. Which types are supported, and how many, follows this model’s specs.

Media is downloaded and validated in the background; media that cannot be read, has an invalid format or breaks the content rules can make the task fail. A failed task returns the hold to your balance.

Photos of real people may be restricted by the generation service’s content rules; we cannot guarantee that every request is accepted or that every output meets your subjective expectations.

Videos are kept for 72 hours; download them in time. Uploaded media is also kept for 72 hours; do not use temporary links as permanent storage.

JSON · Image reference
{
  "model": "vidu-q4",
  "prompt": "Soft light shimmers across the lake as the camera slowly pushes forward",
  "duration": 5,
  "resolution": "720P",
  "aspect_ratio": "16:9",
  "images": [
    "https://media.vidbudget.com/inputs/YOUR_IMAGE_UUID.png"
  ]
}

Response format

The submit response uses the same structure, but with status queued, completed_at null and data an empty array. error is an error code string when the task failed, and null on success or while it runs.

JSON · Finished task
{
  "id": "TASK_UUID",
  "object": "task",
  "kind": "video",
  "model": "vidu-q4",
  "status": "succeeded",
  "created_at": 1793354400,
  "completed_at": 1793354700,
  "elapsed_seconds": 300,
  "retry_count": 0,
  "error": null,
  "data": [
    {
      "url": "https://media.vidbudget.com/videos/VIDEO_UUID.mp4"
    }
  ]
}

Task status and retries

retry_count counts the extra generation attempts of this task, 0 at first; queries do not count. completed_at is written only on final success or failure, and the elapsed time includes queueing, retries and media transfer.

When the generation service has a temporary fault, the system reschedules the generation automatically (up to 4 times per task) at no extra charge; failures caused by the prompt, the media or content moderation are not retried. When a submit result cannot be confirmed, nothing is bought twice: the task fails and the hold is returned. Each task is held once and finally settled or refunded once, and every balance change is recorded in your history.

Status Meaning
queued Saved, waiting for background processing
processing Media processing, generation, polling or transfer in progress
succeeded Finished; read data[0].url
failed Ended in failure; read error. The hold is returned automatically

Generation time and timeouts

Generating a video can take several minutes or longer; duration, resolution and the queue all affect when it finishes. This new site has no real generation-time statistics yet, and timings measured elsewhere are not a promise of this service.

The HTTP request limit is 85 seconds; past it you get a JSON 504. The total time limit of a generation task is currently 7200 seconds. Closing the browser does not cancel the background task.

503 means this combination cannot be generated right now, and nothing was charged; retry later or change the settings instead of resubmitting again and again.

Errors and what to do

HTTP errors look like {"error":{"code":"..."}}; message is not guaranteed to be present. A failed task reports its error in the error string of the task object.

A failed task also carries error_message, a sentence you can show your users, and for content_rejected an error_reason that names the check: copyright, real_person or safety. The check is the model’s own; resubmitting the same prompt and references rarely passes.

HTTP / task Error code What to do
400 invalid_request Check the parameters, types, media fields and model constraints
401 invalid_api_key / login_required Check the key or your sign-in
402 insufficient_balance Top up, then submit again
404 task_not_found Make sure the task belongs to you and the ID is correct
409 conflict The model is switched off, or the idempotency key conflicts with different parameters
413 payload_too_large Use a presigned direct upload for large files
415 unsupported_media_type Upload images, videos or audio only
429 upload_rate_limit Wait for the window to reset
503 temporarily_unavailable This combination cannot be generated right now; nothing was charged. Retry later
504 request_timeout Query the original task to avoid buying twice
Task media_processing_failed Check that the media can be read and what its actual file format is
Task generation_timeout The task reached its total time limit; the hold was returned
Task content_rejected The prompt or media did not pass content moderation; change them and submit again
Task content_rejected · copyright The model’s copyright check: a named game, anime or film character, a celebrity, a brand or logo, or a song in the prompt or a reference. Use original characters and your own references
Task content_rejected · real_person The model’s real-person check: a reference or the video shows a real person’s face
Task content_rejected · safety The model’s content safety check on the prompt or the finished video, for example nudity, sexual or violent detail
Task reference_rejected The length, format or content of the reference media does not meet the requirements
Task request_not_accepted This duration, aspect ratio or media combination cannot be generated right now; adjust it and try again
Task generation_failed / service_unavailable Still not finished after automatic retries; try again later
Task service_busy The generation service is busy: the task waited in the queue past the limit (10 minutes by default) or was still busy after automatic retries. The hold was refunded in full; submit again later
Task submission_unconfirmed The submit result could not be confirmed; the hold was returned and you can simply submit again
429 too_many_active_tasks Your account already has the maximum number of video tasks queued or generating (50 by default). Nothing was charged. Submit again once some of them finish; the response carries Retry-After: 30
429 rate_limited Too many requests. Nothing was charged. Wait the number of seconds in the Retry-After response header, then retry; see "Rate limits"
503 service_busy The service is busy right now. The request had no effect and nothing was charged. Retry after the number of seconds in the Retry-After response header (usually 2 seconds), reusing the same Idempotency-Key when you submit
402 key_daily_budget_exceeded This key has used up its budget for today (UTC). Nothing was charged. It resets at 00:00 UTC, or raise it in the Console
403 key_ip_not_allowed This key only accepts calls from its IP allowlist, and the current IP is not on it
403 key_model_not_allowed This key is not allowed to call this model

Rate limits

Each API key is counted separately (Try it online uses your account’s own counter), with a token bucket: once the allowance is used up, it refills evenly at the per-minute rate. Defaults: queries (GET /v1/*) 1200 per minute, with short bursts of up to 100; generation submits and uploads (POST /v1/videos/generations, /v1/uploads*) 120 per minute, with short bursts of up to 30. Requests with an invalid key or without sign-in are counted per source IP: 60 per minute.

Over the limit you get HTTP 429 with error code rate_limited, and nothing is charged; the Retry-After response header is the number of seconds to wait. Every /v1 response carries X-RateLimit-Limit (the per-minute limit), X-RateLimit-Remaining (how many requests you can send right now) and X-RateLimit-Reset (seconds until the allowance is fully restored).

To track many tasks, fetch the latest 100 at once with GET /v1/tasks, or set up a webhook in the Console to be notified when tasks finish, instead of polling each task rapidly. Each account can have at most 50 video tasks queued or generating at the same time by default; beyond that you get 429 too_many_active_tasks.

Media uploads and large direct uploads

Each API key is currently limited to 150 uploads per hour by default. A regular upload is limited to 90000000 bytes; above that, use a presigned PUT. Direct uploads are limited to 1000000000 bytes, and the signature is valid for 15 minutes.

Image, video and audio MIME types are accepted, and the actual content is decoded and checked in the background. Recommended: PNG/JPEG/WebP, MP4, MP3/WAV/M4A. For a batch, send one request per file (at most 6 in parallel is recommended) and keep the order in which you added the files: it gives the media numbers.

When you PUT to upload_url, send only the upload headers returned, never your VidBudget API key. After the upload, call complete, then query the task for the final media URL.

cURL · Regular upload
curl https://vidbudget.com/v1/uploads -H "Authorization: Bearer $VIDBUDGET_API_KEY" -F "file=@reference.png"

Webhooks: get notified when a task ends

On the Webhooks page of the Console, register up to 3 https endpoints and choose their events. As soon as a task submitted with an API key ends (success, failure, timeout and refund all count), we POST once to every endpoint subscribed to that event; tasks submitted from Try it online are not pushed. You can also keep polling GET /v1/tasks/{id}; a per-request callback_url is not supported.

Request body: {"id":"evt_…","type":"task.succeeded","created":<Unix seconds>,"data":<the task object, the same as GET /v1/tasks/{id} returns>}. Retries of the same event keep the same id, so you can use it to deduplicate.

Signature: request header VidBudget-Signature: t=<Unix seconds>,v1=<hex HMAC-SHA256>. The signed content is t + "." + the raw request body, and the key is this endpoint’s signing secret (starts with whsec_, shown only once, when it is created or reset). Verify against the raw bytes, and reject any t older than 5 minutes.

Delivery: any 2xx response counts as delivered. With no response within 10 seconds, a failed connection or any other status code, we retry after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours: 6 attempts in total. Redirects are not followed; the endpoint must be public https on port 443, and private, loopback and reserved addresses are never called.

Synchronous uploads, other payment methods, other models and response fields specific to other services do not apply to this API. Account endpoints: GET /v1/balance, GET /v1/tasks, GET /v1/models.

Event When it is sent
task.succeeded The task succeeded; data.data[0].url is the video URL
task.failed The task ended in failure; data.error is the error code, and the hold was refunded in full
webhook.test You clicked "Send test event" in the Console
Python · Verify the signature
import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    """header = the VidBudget-Signature value; body = the raw request bytes, not re-encoded JSON."""
    fields = dict(part.split("=", 1) for part in header.split(","))
    stamp = int(fields["t"])
    if abs(time.time() - stamp) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{stamp}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, fields.get("v1", ""))

# Flask: verify(SECRET, request.headers["VidBudget-Signature"], request.get_data())

Sign in to VidBudget

Your balance, API keys and generation history are all in your account.

or
Sign in with Google

No account yet?Sign up free

Contact us

Questions about your account, top-ups, results or the API: we are here to help.

For a top-up, include the order number; for a generation, the task ID. Then we can check it right away.

Refund policy →API docs →