Reference

make_video

Make a video from a prompt

POST /api/v2/make_video

Starts a video job. Send dry_run: true first to get the price without spending. Video takes 1-10 minutes: poll GET /results/{id} or pass callback_url. Needs the generate scope.

Auth: API key (Authorization: Bearer)
Key scope needed: generate
Raw spec: https://app.diffusr.ai/api/v2/openapi.json

Headers

Name	Type	Required	Description
`Idempotency-Key`	string	no	1-255 visible ASCII characters you make up for this request (a UUID is fine). Send the same key to retry safely: you get the first job back instead of paying twice. Reusing a key for a different request answers 409 IDEMPOTENCY_CONFLICT. Wins over `idempotency_key` in the body.

Request body (JSON)

Name	Type	Required	Description
`prompt`	string	yes	The shot: subject, action, camera, setting, sound.
`image_urls`	string[]	no	Optional reference pictures (a person, a product, a room, a first frame). Say in the prompt what each one is, by its place in this list — on Seedance: “Image 1 is Mia, the speaker”. Public URLs — upload_asset gives you one for a local file.
`audio_urls`	string[]	no	Optional voice or sound clips (models with takes_audio in list_models — the Seedance family). E.g. 5–10 s of the speaker’s voice cut from an earlier clip, so the next clip keeps that voice. Name each in the prompt: “Audio 1 is Mia’s voice”. Public URLs.
`duration_sec`	integer	no	Length in seconds. Leave out for the model’s default.
`aspect_ratio`	string	no	e.g. “9:16”, “16:9”, “1:1”. Leave out for the model’s default.
`resolution`	string	no	e.g. “720p”. Leave out for the model’s default.
`model`	string	no	Leave out for the recommended model. Ids come from list_models.
`dry_run`	boolean	no	true = only check the request and return the price in credits. Nothing is made, nothing is spent.
`idempotency_key`	string	no	A unique string you make up for this request. Retry with the same key and you get the first result back instead of paying again.
`callback_url`	string	no	Optional. A public https:// link. When the job finishes (done, failed or canceled) we POST the finished result here, signed. See the docs for checking the signature. Polling get_result still works.

Example

curl -X POST https://app.diffusr.ai/api/v2/make_video \
  -H "Authorization: Bearer $DIFFUSR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "prompt": "A woman turns to camera on a sunny street, smiles",
  "model": "seedance-2-0-fast",
  "resolution": "720p",
  "duration_sec": 5,
  "aspect_ratio": "9:16"
}'

import { Diffusr } from "diffusr";

const d = new Diffusr(); // reads DIFFUSR_KEY
const job = await d.makeVideo({
  prompt: "A woman turns to camera on a sunny street, smiles",
  model: "seedance-2-0-fast",
  resolution: "720p",
  duration_sec: 5,
  aspect_ratio: "9:16",
});
const result = await d.waitFor(job.id);
console.log(result.output?.url);

from diffusr import Diffusr

d = Diffusr()  # reads DIFFUSR_KEY
job = d.make_video(
    prompt="A woman turns to camera on a sunny street, smiles",
    model="seedance-2-0-fast",
    resolution="720p",
    duration_sec=5,
    aspect_ratio="9:16",
)
result = d.wait_for(job["id"])
print(result["output"]["url"])

The same call as a dry run (the price, nothing made, nothing spent):

curl -X POST https://app.diffusr.ai/api/v2/make_video \
  -H "Authorization: Bearer $DIFFUSR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "prompt": "A woman turns to camera on a sunny street, smiles",
  "model": "seedance-2-0-fast",
  "resolution": "720p",
  "duration_sec": 5,
  "aspect_ratio": "9:16",
  "dry_run": true
}'

import { Diffusr } from "diffusr";

const d = new Diffusr(); // reads DIFFUSR_KEY
const job = await d.makeVideo({
  prompt: "A woman turns to camera on a sunny street, smiles",
  model: "seedance-2-0-fast",
  resolution: "720p",
  duration_sec: 5,
  aspect_ratio: "9:16",
  dry_run: true,
});
console.log(job); // the price, nothing was made

from diffusr import Diffusr

d = Diffusr()  # reads DIFFUSR_KEY
job = d.make_video(
    prompt="A woman turns to camera on a sunny street, smiles",
    model="seedance-2-0-fast",
    resolution="720p",
    duration_sec=5,
    aspect_ratio="9:16",
    dry_run=True,
)
print(job)  # the price, nothing was made

Response

200 ApiDryRun

dry_run was true: the price, nothing made, nothing spent.

Name	Type	Required	Description
`dry_run`	true	yes
`test`	true	no	true when a test key made the call: the price is real, nothing real ran. Absent for live keys.
`credits_estimated`	number	yes
`price`	object	no
`price.credits`	number	yes	The most this call costs, in whole credits (1 credit = $0.01).
`price.usd`	string	yes	The same price in US dollars, e.g. “0.0336”.
`price.tariff`	“direct” \| “outcome”	yes	“direct” = your prompt goes to the model as sent; “outcome” = a result we shape (Recast, creator video).
`price.tariff_version`	string	yes
`price.expires_at`	string	yes	The quoted price holds until then (ISO time).
`duration_sec`	number	no
`warnings`	string[]	no
`note`	string	yes

202 ApiStarted

The job started. Poll GET /results/{id}.

Name	Type	Required	Description
`id`	string	yes	The job id. Poll GET /results/{id} with it, or wait for the callback.
`status`	string	yes	“PENDING” on a new start; the run’s current status when a retried Idempotency-Key replays the first job.
`credits_estimated`	number	yes	The most this job can cost, in credits.
`idempotent_replay`	true	no	true when this is the FIRST job again, answering a retried Idempotency-Key.
`test`	true	no	true when a test key made the call: the price is real, nothing real ran. Absent for live keys.
`price`	object	no	The price, locked in at start.
`price.credits`	number	yes	The most this call costs, in whole credits (1 credit = $0.01).
`price.usd`	string	yes	The same price in US dollars, e.g. “0.0336”.
`price.tariff`	“direct” \| “outcome”	yes	“direct” = your prompt goes to the model as sent; “outcome” = a result we shape (Recast, creator video).
`price.tariff_version`	string	yes
`price.expires_at`	string	yes	The quoted price holds until then (ISO time).
`duration_sec`	number	no
`warnings`	string[]	no	Heads-ups that did not stop the call.
`next`	string	yes	What to do next, in words.

Errors

Every error body is { error, code, request_id, ... }. All codes and what to do.

401: Missing, wrong, revoked or expired API key (code UNAUTHORIZED, KEY_REVOKED, KEY_EXPIRED).
402: Not enough credits, or an API budget would be passed (INSUFFICIENT_CREDITS, BUDGET_EXCEEDED).
403: The key may not do this (SCOPE_DENIED, MODEL_NOT_ALLOWED, TEST_MODE_UNSUPPORTED, ACCOUNT_BLOCKED, allowance_exceeded).
409: IDEMPOTENCY_CONFLICT or CALLBACK_NOT_RETRYABLE.
413: The request or file is too large (TOO_LARGE, REFERENCE_TOO_LARGE).
422: The request is not valid (VALIDATION_FAILED, INVALID_JSON, PREFLIGHT_FAILED, CALLBACK_URL_INVALID, REFERENCE_*). `issues` lists each problem. Nothing was charged.
429: Too many requests or jobs (RATE_LIMITED, CONCURRENCY_LIMIT, UPLOAD_QUOTA, …). Wait Retry-After seconds, then retry.
500: Our fault (INTERNAL_ERROR). Quote request_id to support.
503: Paused or busy (API_PAUSED, MODEL_PAUSED, PROVIDER_PAUSED, PROVIDER_BUSY, UNAVAILABLE). Wait Retry-After seconds, then retry.

Charges

Costs credits (1 credit = $0.01). Send `dry_run: true` first: it answers with the price and spends nothing. You are charged when the result is delivered and never more than the quoted price. Work that fails, is canceled before it runs, or is never delivered is not charged. A test key quotes the same price and charges nothing. It is priced at the direct rate (your prompt goes to the model as sent), the same rate as the model prices on the Prices page.