POST
https://vidbudget.com/v1/videos/generations
Asynchronous video generation · Billed per second · No charge for failed tasks
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 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"
]
}'
curl https://vidbudget.com/v1/videos/jobs/TASK_ID -H "Authorization: Bearer $VIDBUDGET_API_KEY"
import os, time, uuid, requests
BASE = "https://vidbudget.com"
headers = {"Authorization": "Bearer " + os.environ["VIDBUDGET_API_KEY"]}
response = requests.post(BASE + "/v1/videos/generations", headers={**headers,
"Idempotency-Key": str(uuid.uuid4())}, json={'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']}, timeout=85)
response.raise_for_status()
job = response.json()
print("Task ID (save it to keep polling after a disconnect):", job["id"])
deadline = time.monotonic() + 7200
while job["status"] not in ("succeeded", "failed") and time.monotonic() < deadline:
time.sleep(5)
response = requests.get(BASE + "/v1/videos/jobs/" + job["id"], headers=headers, timeout=85)
response.raise_for_status()
job = response.json()
if job["status"] == "succeeded":
url = job["data"][0]["url"]
if not url.startswith("https://media.vidbudget.com/videos/"):
raise RuntimeError("Unexpected media URL")
with requests.get(url, stream=True, timeout=85) as media:
media.raise_for_status()
with open("video.mp4", "wb") as output:
for chunk in media.iter_content(1024 * 1024):
output.write(chunk)
elif job["status"] == "failed":
print("Failed; the hold was refunded:", job["error"])
else:
print("Not finished yet; keep polling the original task:", job["id"])
// Node.js 18+; save the task ID before polling.
const base = "https://vidbudget.com";
const headers = {Authorization: `Bearer ${process.env.VIDBUDGET_API_KEY}`};
async function request(path, options = {}) {
const response = await fetch(base + path, {...options, signal: AbortSignal.timeout(85000)});
const data = await response.json();
if (!response.ok) throw new Error(JSON.stringify(data.error));
return data;
}
let job = await request('/v1/videos/generations', {method: 'POST', headers: {...headers,
'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID()},
body: JSON.stringify({"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"]})});
console.log('Task ID:', job.id);
const deadline = Date.now() + 7200000;
while (!['succeeded', 'failed'].includes(job.status) && Date.now() < deadline) {
await new Promise(resolve => setTimeout(resolve, 5000));
job = await request('/v1/videos/jobs/' + job.id, {headers});
}
console.log(job.status === 'succeeded' ? job.data[0].url : job);
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.
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.
{
"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.
{
"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 https://vidbudget.com/v1/uploads -H "Authorization: Bearer $VIDBUDGET_API_KEY" -F "file=@reference.png"
POST /v1/uploads/presign
{"content_type":"video/mp4","size":100000000}
PUT <upload_url> (raw file bytes, with the returned headers)
POST /v1/uploads/<upload_id>/complete
GET /v1/tasks/<task_id>
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 |
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())
import crypto from 'node:crypto';
// header = the VidBudget-Signature value; rawBody = the request bytes (a Buffer), not re-encoded JSON.
export function verify(secret, header, rawBody, tolerance = 300) {
const fields = Object.fromEntries(header.split(',').map(p => [p.slice(0, p.indexOf('=')), p.slice(p.indexOf('=') + 1)]));
const stamp = Number(fields.t);
if (!Number.isInteger(stamp) || Math.abs(Date.now() / 1000 - stamp) > tolerance) return false;
const expected = crypto.createHmac('sha256', secret).update(`${stamp}.`).update(rawBody).digest('hex');
const given = Buffer.from(fields.v1 || '');
return given.length === expected.length && crypto.timingSafeEqual(given, Buffer.from(expected));
}
// Express: app.post('/vidbudget', express.raw({ type: 'application/json' }), (req, res) =>
// res.sendStatus(verify(SECRET, req.get('VidBudget-Signature'), req.body) ? 204 : 400));