How Do You Generate AI Videos From Code With the VdoBloom API? (curl, Webhooks, Idempotency)
A VdoBloom API quickstart: create a vdb_ key, generate an image with wait true, start a video job, poll or receive a webhook, and handle idempotency and error codes.
The VdoBloom API turns the same credit balance you use in the app into a programmatic image and video pipeline: one key, seven endpoints, and no separate developer plan. A Nano Banana image costs 6 credits, a 5-second Seedance 2 Fast clip at 480p costs 24, and every generation returns a job you can poll or receive by webhook.
Updated October 2026.
What the API covers (images, image edits, text and image to video, jobs, balance)
The base URL is https://vdobloom.com/api/v1. Seven endpoints cover the whole surface, and they map closely to what the dashboard does.
| Endpoint | Method | What it does |
|---|---|---|
| /models | GET | Models with credit prices; filter with type=image, image_edit or video |
| /images/generations | POST | Text-to-image, with wait: true to hold for the result |
| /images/edits | POST | Edit or combine 1 to 10 input images |
| /videos/generations | POST | Text-to-video, or image-to-video with image_url |
| /jobs/{id} | GET | Status, credit cost and result for one job |
| /creations | GET | Your recent generations |
| /balance | GET | Remaining credits |
Images are fetched once from a public https URL and copied to VdoBloom storage, so your source link does not need to stay alive after the request. Image inputs must be PNG, JPEG, WebP, GIF, HEIC or AVIF and no larger than 10 MB. Prompts go through the same content rules as the app: a blocked prompt fails the job and is not charged.
What the API does not include is worth knowing before you plan a build. Effects, lip-sync and avatar jobs, UGC and ad tools, and timeline editing stay in the dashboard. The developer page is the reference for the full request and response shapes.
Get a key in Settings, Developer (vdb_ prefix, shown once)
Open Settings, Developer in the dashboard and create a key. It starts with vdb_ and is shown once; VdoBloom stores only a hash, so there is no way to display it again. Revoke it from the same page when it is no longer needed.
Every call carries the key as a bearer token:
Authorization: Bearer vdb_your_keyA key can create generations and read jobs, models and balance. It cannot create or revoke other keys, which limits what a leaked credential can do. Nothing else is required: the API spends the credits already in your VdoBloom balance, so there is no second billing account to set up and no per-seat developer plan. Credits you buy never expire.
Your first image call with wait: true
Images usually finish quickly, so the simplest first call asks the server to hold the connection. With wait: true the request returns the finished image, typically inside two minutes. Without it you get a job back immediately.
curl -X POST https://vdobloom.com/api/v1/images/generations -H "Authorization: Bearer vdb_your_key" -H "Content-Type: application/json" -d '{"prompt":"A brushed-steel travel mug on pale oak, soft window light from the left, 50mm, three-quarter view, space above for a headline","model":"nano-banana-pro","aspect_ratio":"4:5","resolution":"2K","wait":true}'Nano Banana Pro is 18 credits at 1K or 2K and 24 at 4K, and the response includes the job, the credit cost and the image URL. Save the URL and the job id. The price is also visible in advance from GET /models.
Your first video call: a job id, then poll every 20 to 60 seconds
Video takes one to ten minutes, so the call always returns a job rather than a file. Send the prompt, model, duration, resolution and aspect ratio, and keep the returned id.
curl -X POST https://vdobloom.com/api/v1/videos/generations -H "Authorization: Bearer vdb_your_key" -H "Content-Type: application/json" -H "Idempotency-Key: launch-clip-001" -d '{"prompt":"Steam rising from a ceramic cup on a wooden counter, slow push in, morning light","model":"bytedance/seedance-2-fast","duration":5,"resolution":"720p","aspect_ratio":"9:16"}'Then poll GET /jobs/{id} every 20 to 60 seconds. A short Python loop looks like this:
import json, time, urllib.request
API = "https://vdobloom.com/api/v1"
KEY = "vdb_your_key"
def get(path):
req = urllib.request.Request(API + path, headers={"Authorization": "Bearer " + KEY})
with urllib.request.urlopen(req) as r:
return json.load(r)
while True:
job = get("/jobs/" + job_id)
if job["status"] != "processing":
break
time.sleep(30)
print(job)When status is completed, the result carries the video URL. When it is failed, the error explains why and the generation is refunded. Polling every few seconds adds nothing: the model does not finish faster, and the account rate limits are shared across all your keys.
Webhooks: the signed job.completed event and how to verify it
Polling is fine for one clip. For a queue, add a webhook URL to the key in Settings, Developer and let VdoBloom call you. On completion the server posts a job.completed event with two headers: X-VdoBloom-Signature: t=<unix>,v1=<hex> and X-VdoBloom-Event: job.completed.
The signature is an HMAC-SHA256 of the timestamp, a dot, and the raw request body, using the signing secret shown with the webhook settings. Verify it against the raw bytes before parsing the JSON, compare in constant time, and reject timestamps that are too old. Answer any 2xx. A non-2xx response is retried after 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours, and the event id stays the same across retries, so store it and skip duplicates.
Webhook URLs must be https on port 443 and must resolve to a public address. A local server needs a tunnel or a staging endpoint. If none of that fits your setup, polling on a 30-second timer is a perfectly good fallback.
Idempotency keys, automatic refunds and the error codes (402, 422, 429)
Send an Idempotency-Key header on every generation call. Repeating a request with the same key returns the original job instead of charging again, which is what makes a retry after a network timeout safe. Reusing the same key for a genuinely different request is refused with 422, so generate a new key per distinct job.
| Status | Code | What to do |
|---|---|---|
| 400 | invalid_request | Fix the payload; check required fields and image URLs |
| 401 | unauthorized | Check the bearer key and whether it was revoked |
| 402 | insufficient_credits | Top up or lower the model, duration or resolution |
| 403 | forbidden | The feature or model is switched off for this account |
| 404 | not_found | Check the job id or path |
| 422 | reused idempotency key | Use a fresh key for a different request |
| 429 | rate_limited | Back off; the account allows 120 requests and 20 generations per minute across all keys |
For 5xx errors, retry with the same Idempotency-Key. A failed generation is refunded automatically, so a retry does not leave you paying twice for one clip. The credit rules behind those numbers are the same as the app and are explained in AI video credits explained.
Choosing a model: GET /models returns credit prices
GET /models is the price list. Call it with ?type=video to see only video models; each entry lists the model id you pass to the generation endpoints, and the credit cost for a given duration and resolution is shown on the model’s page under /models/. That is how you decide between a cheap draft and a finished render without guessing.
A practical pattern: draft on Seedance 2 Fast at 480p, then re-render the winner at 720p, or move it to a higher tier for delivery. The same prompt and aspect ratio travel between models, so testing is cheap and only the final render carries the full price. Prices for both models are visible on the Seedance 2 Fast page and Nano Banana Pro page. If you are running a whole batch of jobs, see AI video batch generation, and for the credit model in more depth, what AI credits are and how they work. One-time packs never expire, and the current options sit on the pricing page.
Frequently asked questions
Do I need a separate subscription for the API?
No. The API spends the credits in your VdoBloom balance at the same prices as the app. There is no developer plan and no per-seat fee, and credits you buy do not expire.
How long does an image request take with wait: true?
Usually under two minutes. If the job has not finished by then, the call returns the job so you can check GET /jobs/{id} instead of holding the connection.
How often should I poll a video job?
Every 20 to 60 seconds. Video takes one to ten minutes, and polling faster does not speed it up. A webhook is better once you are running more than a few jobs.
What happens if my request times out?
Retry with the same Idempotency-Key. If the original job was created, the retry returns that job rather than charging for a second one.
Which image formats can I send in?
PNG, JPEG, WebP, GIF, HEIC or AVIF, up to 10 MB, from a public https URL. VdoBloom fetches each image once and keeps its own copy.
Create a key in Settings, Developer, call GET /models with image to video open in another tab to compare the same prices, and run one image with wait: true before building a queue. New accounts start with 10 free credits and no card, which covers an image and leaves change for a short draft. There is no subscription needed, failed jobs are refunded, and one-time credits never expire.
Ready to try it?
Create your first AI video in minutes — no credit card required.
Start Creating Free →