Vidu API

The Vidu API turns a prompt and public media URLs into a video clip, image, sound effect, speech, or finished film. You choose an operation, pass the Vidu Enterprise v2 request body as input, and receive the result as an OmnAPI Task under /api/v1/vidu.

Auth: send your API key in x-api-key. Quote and create need task:create; reading needs task:read; cancelling needs task:cancel.
Async: every create returns a taskId. Poll it or set config.webhookUrl.
URLs only: OmnAPI does not upload, download, inspect, transcode, or store media for this API. Every media field takes a public http:// or https:// URL; Base64, data:, and blob: values are rejected.
Short-lived output: download finished files within one hour.

For a finished music video built around a song, use Music Video instead; its pricing is separate from this API.

Models

Pick the operation first, then the Vidu input.model it supports. Model IDs are case-sensitive.

`input.model`	Operations	Output	Notes
`viduq3-pro`	`image-to-video`, `text-to-video`, `start-end-to-video`	540p–1080p video	Q3 Pro for prompt and frame video.
`viduq3-turbo`	Image, text, start/end, and reference video	540p–1080p video	Lower-cost Q3; the Quickstart model.
`viduq3-pro-fast`	`image-to-video` only	720p or 1080p video	Q3 Pro Fast is priced only for image-to-video.
`viduq3-mix`, `viduq3`	`reference-to-video`	Q3 Mix 720p/1080p; Q3 540p–1080p	Q3 Mix has no off-peak rate.
`viduq2`, `viduq2-turbo`, `viduq2-pro`, `viduq2-pro-fast`	Image, text, start/end, reference video; `extend-video`; `multi-frame-video`	540p–1080p video	Priced by a per-second formula; see Q2 video generation.
`viduq1`, `viduq1-classic`	Image, reference, start/end, and text video (`viduq1-classic`: image and start/end only)	5-second 1080p video	Fixed price per clip.
`vidu2.0`	Image, start/end, and reference video	4- or 8-second clips, 360p–1080p	Fixed price per clip.
`viduq2`, `viduq1`	`reference-to-image`	Image, 1080p–4K (`viduq1`: 1080p)	`viduq2` takes 0–7 references; `viduq1` takes 1–7.

Supported operations

The operation value selects a fixed Vidu endpoint. Copy the fields from the linked Vidu reference into input.

Category	`operation`	What it does	Vidu `input` reference
Video	`image-to-video`	Animate one image.	Image to Video
Video	`reference-to-video`	Generate video from subject or style references.	Reference to Video
Video	`start-end-to-video`	Generate between a start frame and an end frame.	Start/End to Video
Video	`text-to-video`	Generate video from a prompt.	Text to Video
Image	`reference-to-image`	Text-to-image, reference generation, and image editing with 0–7 references.	Reference to Image
Audio	`text-to-audio`	Generate a sound effect or short audio clip.	Text to Audio
Audio	`timing-to-audio`	Generate timed audio segments.	Timing to Audio
Speech	`text-to-speech`	Synthesize speech with a Vidu voice.	Text to Speech
Speech	`voice-clone`	Clone a voice and synthesize a preview.	Voice Clone
Video edit	`lip-sync`	Synchronize video speech to text or audio.	Lip Sync
Motion	`motion-sync-v1`	Transfer motion from a reference video.	Motion Sync
Motion	`motion-sync-v2`	Use the current motion-control template.	Motion Sync; OmnAPI sets `template` to `motion_control_2` unless you send one
Video edit	`extend-video`	Extend an existing Vidu creation or public video.	Video Extension
Video edit	`multi-frame-video`	Generate transitions across multiple keyframes.	Multi-Frame
Video edit	`upscale-video`	Upscale a video to 1080p, 2K, 4K, or 8K.	Upscale Pro
Video edit	`replace-video`	Replace an object or region in a video.	Video Replacement
Character	`digital-human`	Generate a speaking character from an image and text or audio.	Digital Human
Prompt	`prompt-recommendation`	Recommend image-to-video prompts.	Prompt Recommendation
Template	`template`	Run a Vidu effect template.	Template
Template	`template-story`	Run a story template.	Template Story
Film	`general-film-create`	Create a general-purpose finished film.	One Click General Film — create
Film	`general-film-edit`	Edit a general-film job; `input.id` selects the parent.	One Click General Film — edit
Film	`general-film-compose`	Compose selected general-film jobs; `input.id` selects the parent.	One Click General Film — compose
Advertising	`ad-film-create`	Create a finished advertising film.	One Click Ad-Film — create
Advertising	`ad-film-edit`	Edit advertising footage, narration, or music.	One Click Ad-Film — edit
Advertising	`ad-film-compose`	Compose selected advertising jobs.	One Click Ad-Film — compose
Trends	`trending-replicate`	Recreate a trending video format.	One Click Trending Replicate

Real-time Vidu S1 sessions are not available: they need a live RTC connection, not an asynchronous task.

Pricing

Every Vidu credit costs 2 OmnAPI credits:

OmnAPI credits = ceil(Vidu credits) × 2

At the $0.002 public credit benchmark that is $0.004 per Vidu credit, 80% of Vidu’s $0.005 list price; your actual cash cost depends on the credit package you buy. Vidu bills whole credits, so fractional results round up before the ×2 conversion.

Example: image-to-video with viduq3-turbo, 720p, 5 seconds = 11 × 5 = 55 Vidu credits = 110 OmnAPI credits.

Video rates depend on model, resolution, duration, and off_peak. Call /quote for the exact amount before you create a task; the quote is authoritative if Vidu changes a supported combination. Vidu Direct is never priced at the Music Video rate of 1.75 OmnAPI credits per Vidu credit — that rate applies only to Vidu components inside the Music Video API. Failed and cancelled tasks follow the shared settlement rules.

Complete price matrix

Each table shows Vidu credits and the OmnAPI credits you are charged. “Normal / off-peak” values appear in that order; set input.off_peak: true for the off-peak rate. Source rate card: Vidu API Pricing.

Q3 image, text, and start/end video

Per generated second, for image-to-video, text-to-video, and start-end-to-video.

Model	Resolution	Vidu credits/s normal / off-peak	OmnAPI credits/s normal / off-peak
Q3 Pro	540p	9 / 5	18 / 10
Q3 Pro	720p	20 / 10	40 / 20
Q3 Pro	1080p	24 / 12	48 / 24
Q3 Turbo	540p	7 / 4	14 / 8
Q3 Turbo	720p	11 / 6	22 / 12
Q3 Turbo	1080p	13 / 7	26 / 14
Q3 Pro Fast (image-to-video)	720p	20 / 10	40 / 20
Q3 Pro Fast (image-to-video)	1080p	25 / 13	50 / 26

Q3 reference-to-video

Model	Resolution	Vidu credits/s normal / off-peak	OmnAPI credits/s normal / off-peak
Q3 Mix	720p	24 / not supported	48 / not supported
Q3 Mix	1080p	29 / not supported	58 / not supported
Q3 Turbo	540p	4 / 2	8 / 4
Q3 Turbo	720p	10 / 5	20 / 10
Q3 Turbo	1080p	13 / 7	26 / 14
Q3	540p	7 / 4	14 / 8
Q3	720p	12 / 6	24 / 12
Q3	1080p	15 / 7	30 / 14

Q2 video generation

s = ceil(duration in seconds). Off-peak is half the normal Vidu total, rounded up, then ×2. audio: true on Q2 image-to-video or reference-to-video adds 15 Vidu / 30 OmnAPI credits. is_rec: true on any supported video operation adds 10 Vidu / 20 OmnAPI credits.

Operation and model	Resolution	Vidu credit formula	OmnAPI credit formula
Image/start-end · Q2 Turbo	540p	`6 + 2 × (s−1)`	`12 + 4 × (s−1)`
Image/start-end · Q2 Turbo	720p	`s=1: 8`; `s≥2: 10 + 10 × (s−2)`	`s=1: 16`; `s≥2: 20 + 20 × (s−2)`
Image/start-end · Q2 Turbo	1080p	`35 + 10 × (s−1)`	`70 + 20 × (s−1)`
Image/start-end · Q2 Pro	540p	`s=1: 8`; `s≥2: 10 + 5 × (s−2)`	`s=1: 16`; `s≥2: 20 + 10 × (s−2)`
Image/start-end · Q2 Pro	720p	`15 + 10 × (s−1)`	`30 + 20 × (s−1)`
Image/start-end · Q2 Pro	1080p	`55 + 15 × (s−1)`	`110 + 30 × (s−1)`
Image/start-end · Q2 Pro Fast	720p	`8 + 2 × (s−1)`	`16 + 4 × (s−1)`
Image/start-end · Q2 Pro Fast	1080p	`16 + 4 × (s−1)`	`32 + 8 × (s−1)`
Text-to-video · Q2	540p	`10 + 2 × (s−1)`	`20 + 4 × (s−1)`
Text-to-video · Q2	720p	`15 + 5 × (s−1)`	`30 + 10 × (s−1)`
Text-to-video · Q2	1080p	`20 + 10 × (s−1)`	`40 + 20 × (s−1)`
Reference-to-video · Q2	540p	`15 + 5 × (s−1)`	`30 + 10 × (s−1)`
Reference-to-video · Q2	720p	`25 + 5 × (s−1)`	`50 + 10 × (s−1)`
Reference-to-video · Q2	1080p	`75 + 10 × (s−1)`	`150 + 20 × (s−1)`
Reference-to-video · Q2 Pro	540p	`20 + 5 × (s−1)`	`40 + 10 × (s−1)`
Reference-to-video · Q2 Pro	720p	`30 + 5 × (s−1)`	`60 + 10 × (s−1)`
Reference-to-video · Q2 Pro	1080p	`85 + 10 × (s−1)`	`170 + 20 × (s−1)`

Q1 and Vidu 2.0 video

Model and operation	Supported output	Vidu credits normal / off-peak	OmnAPI credits normal / off-peak
Q1 image/reference/start-end/text	5s · 1080p	80 / 40	160 / 80
Vidu 2.0 image/start-end	4s · 360p	20 / 10	40 / 20
Vidu 2.0 image/start-end	4s · 720p	40 / 20	80 / 40
Vidu 2.0 image/start-end	4s · 1080p	100 / 50	200 / 100
Vidu 2.0 image/start-end	8s · 720p	100 / 50	200 / 100
Vidu 2.0 reference-to-video	4s · 360p or 720p	80 / 40	160 / 80

Image, audio, and speech

Operation	Scope	Vidu credits	OmnAPI credits
Q2 text-to-image (0 references)	1080p / 2K / 4K	6 / 8 / 10	12 / 16 / 20
Q2 reference-to-image (1–3 references)	1080p / 2K / 4K	8 / 12 / 20	16 / 24 / 40
Q2 reference-to-image (4–7 references)	1080p / 2K / 4K	10 / 16 / 30	20 / 32 / 60
Q1 reference-to-image (1–7 references)	1080p	20	40
Text/timing-to-audio	up to 5s / over 5s through 10s	10 / 20	20 / 40
Text-to-speech	each started 500 characters	10, minimum 10	20, minimum 20
Voice clone	per voice + required TTS preview	300 + TTS	600 + TTS

Vidu lists Text to Speech at $0.05 / 500 characters and Voice Clone at $1.50 / voice, but its credit column for these rows still uses the old denomination. OmnAPI converts the dollar prices at $0.005 per credit (10 and 300 Vidu credits) and settles on reported usage when Vidu returns it.

Video tools, prompt, and motion

Operation	Billing unit	Vidu credits	OmnAPI credits
Prompt recommendation	each started 5 prompts, per requested type	10	20
Lip sync	each started 5 seconds	20	40
Motion Sync V1	each started second · 720p	10	20
Motion Control 2	each started second · 720p	19	38
Motion Control 2.5	each started second · 1080p	34	68
Upscale Pro	each started second · 1080p / 2K / 4K / 8K	10 / 20 / 40 / 160	20 / 40 / 80 / 320

These operations take URL inputs whose length OmnAPI does not inspect. Send the known media duration in pricingContext.durationSec when input.duration is absent.

Video extension and multi-frame

s = ceil(extension or segment seconds). Multi-frame prices every frame-to-frame segment on its own and sums the results.

Model	Resolution	Vidu credit formula	OmnAPI credit formula
Q2 Turbo extension	540p	`10 + 2 × (s−1)`	`20 + 4 × (s−1)`
Q2 Turbo extension	720p	`15 + 5 × (s−1)`	`30 + 10 × (s−1)`
Q2 Turbo extension	1080p	`40 + 10 × (s−1)`	`80 + 20 × (s−1)`
Q2 Pro extension	540p	`15 + 5 × (s−1)`	`30 + 10 × (s−1)`
Q2 Pro extension	720p	`30 + 10 × (s−1)`	`60 + 20 × (s−1)`
Q2 Pro extension	1080p	`60 + 15 × (s−1)`	`120 + 30 × (s−1)`
Multi-frame	up to 9 segments	sum of Q2 segment prices	`2 × summed Vidu credits`

Film and advertising solutions

General-film and ad-film operations share these rates. ad-film-create is priced at 15 seconds when input.duration is omitted.

Operation	Billing unit	Vidu credits	OmnAPI credits
General film / Ad film create	1080p · per second	40	80
Edit footage	1080p · per second	40	80
Edit narration	each started 500 characters	10	20
Edit BGM	per second	2	4
Compose film	per call	1	2
Trending replicate	540p / 720p / 1080p · per second	12 / 16 / 20	24 / 32 / 40

Authorization-cap operations

template, template-story, replace-video, and digital-human have no fixed public rate. Each requires pricingContext.providerCreditCap (1–100,000 Vidu credits), and the quote returns pricingMode: "authorization-cap".

Step	Amount
At create	`providerCreditCap × 2` OmnAPI credits are debited.
On completion	Vidu’s reported credits × 2, never more than the original debit; the difference is refunded.
No usage reported	The original debit is the final charge.

The cap is a spend authorization only — it is not sent to Vidu and does not limit the job.

How it works

Quote — POST /api/v1/vidu/quote with operation, input, and any pricingContext. Nothing is charged.
Create — POST /api/v1/vidu/tasks with the same three fields plus an Idempotency-Key header and, optionally, maxCredits and config. The credits are debited when the task is accepted.
Wait — poll GET /api/v1/vidu/tasks/{taskId} or receive webhook events at config.webhookUrl.
Download — when status is COMPLETED, download every resource URL within one hour.

Retrying a create with the same key and the same body replays the original result instead of charging again; the same key with a different body returns 409. Saving and reusing keys is covered in Task recovery, and statuses in the Task model.

Quickstart

Animate one image with viduq3-turbo. Set OMNAPI_KEY to your API key and replace the example image and webhook URLs.

Quote

curl -X POST https://api.omnapi.com/api/v1/vidu/quote \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "image-to-video",
    "input": {
      "model": "viduq3-turbo",
      "images": ["https://cdn.example.com/frame.jpg"],
      "prompt": "A slow cinematic push-in",
      "duration": 5,
      "resolution": "720p"
    }
  }'

POST /api/v1/vidu/quote · HTTP 200 · full response

{
  "operation": "image-to-video",
  "viduCredits": 55,
  "credits": 110,
  "publicUsd": 0.22,
  "pricingMode": "rate-card",
  "pricingVersion": "vidu-direct-public-v1",
  "customerRate": 2
}

credits is what the task will cost in OmnAPI credits. viduCredits is the Vidu rate-card quantity, and publicUsd is a display estimate; your balance is always charged in OmnAPI credits. A quote may include notes, mainly for authorization-cap operations.

Create

Generate one key for this job and save it with the request body. If the response is lost, resend the same body with the same key.

export REQUEST_KEY="$(uuidgen)"

curl -X POST https://api.omnapi.com/api/v1/vidu/tasks \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "image-to-video",
    "input": {
      "model": "viduq3-turbo",
      "images": ["https://cdn.example.com/frame.jpg"],
      "prompt": "A slow cinematic push-in",
      "duration": 5,
      "resolution": "720p"
    },
    "maxCredits": 110,
    "config": {
      "webhookUrl": "https://example.com/webhooks/omnapi",
      "metadata": { "assetId": "asset_123" }
    }
  }'

POST /api/v1/vidu/tasks · HTTP 200 · receipt · full response

{
  "taskId": "task_01J...",
  "status": "PENDING",
  "creditsRequired": 110,
  "viduCredits": 55,
  "pricingMode": "rate-card",
  "pollUrl": "/api/v1/vidu/tasks/task_01J..."
}

Save taskId. maxCredits makes the create fail before any debit if the current quote is higher, so a price change cannot surprise you.

Poll and download

curl https://api.omnapi.com/api/v1/vidu/tasks/task_01J... \
  -H "x-api-key: $OMNAPI_KEY"

GET /api/v1/vidu/tasks/{taskId} · HTTP 200 · completed result · excerpt

{
  "taskId": "task_01J...",
  "status": "COMPLETED",
  "progress": 100,
  "resources": [
    {
      "id": "res_01J...",
      "index": 0,
      "role": "output",
      "type": "VIDEO",
      "url": "https://..."
    }
  ],
  "outputUrlTtlHours": 1
}

Poll until status is COMPLETED, FAILED, or CANCELLED, then download each resources[].url immediately.

Examples

Each body below goes to POST /api/v1/vidu/quote and then, with your Idempotency-Key, to POST /api/v1/vidu/tasks. Replace the example URLs.

Text to video

Generate a clip from a prompt alone.

{
  "operation": "text-to-video",
  "input": {
    "model": "viduq3-turbo",
    "prompt": "A paper boat drifting down a rain-soaked street at dusk",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }
}

Start and end frames

Generate the motion between two images; images holds exactly two URLs.

{
  "operation": "start-end-to-video",
  "input": {
    "model": "viduq3-turbo",
    "images": [
      "https://cdn.example.com/start.jpg",
      "https://cdn.example.com/end.jpg"
    ],
    "prompt": "The flower slowly opens",
    "duration": 5,
    "resolution": "720p"
  }
}

Reference to video

Keep a character or product consistent; each subject needs a name and its images.

{
  "operation": "reference-to-video",
  "input": {
    "model": "viduq3-turbo",
    "subjects": [
      {
        "name": "mia",
        "images": ["https://cdn.example.com/mia.jpg"]
      }
    ],
    "prompt": "The woman walks through a sunlit market and waves",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }
}

Reference to image

Create or edit an image from up to seven references. With viduq2 and three references at 2K this costs 12 Vidu / 24 OmnAPI credits.

{
  "operation": "reference-to-image",
  "input": {
    "model": "viduq2",
    "prompt": "Place the bottle on a marble counter in soft morning light",
    "images": [
      "https://cdn.example.com/bottle-front.jpg",
      "https://cdn.example.com/bottle-side.jpg",
      "https://cdn.example.com/counter.jpg"
    ],
    "resolution": "2K"
  }
}

Lip sync with a known duration

Duration-priced tools need the source length because OmnAPI does not inspect the file. An 11-second clip is three started 5-second units: 60 Vidu / 120 OmnAPI credits.

{
  "operation": "lip-sync",
  "input": {
    "video_url": "https://cdn.example.com/source.mp4",
    "audio_url": "https://cdn.example.com/voice.mp3"
  },
  "pricingContext": {
    "durationSec": 11
  }
}

Upscale a video

Upscale a 10-second clip to 4K: 400 Vidu / 800 OmnAPI credits.

{
  "operation": "upscale-video",
  "input": {
    "video_url": "https://cdn.example.com/clip.mp4",
    "upscale_resolution": "4K"
  },
  "pricingContext": {
    "durationSec": 10
  }
}

Effect template with a spend cap

Authorization-cap operations need providerCreditCap. This request debits 200 × 2 = 400 OmnAPI credits and refunds whatever Vidu does not report using. Replace template with a name from Vidu’s template list.

{
  "operation": "template",
  "input": {
    "template": "your-template-name",
    "images": ["https://cdn.example.com/portrait.jpg"]
  },
  "pricingContext": {
    "providerCreditCap": 200
  },
  "maxCredits": 400
}

Edit a general film

Film edit and compose operations reference IDs returned in the parent task’s output. Put the parent film id in input; OmnAPI moves it into the Vidu URL path. Never substitute an OmnAPI taskId for a Vidu id, job_id, or ad_one_click_task_id.

{
  "operation": "general-film-edit",
  "input": {
    "id": "PARENT_FILM_ID_FROM_OUTPUT",
    "job_id": "JOB_ID_FROM_OUTPUT",
    "prompt": "Make the final shot warmer and slower"
  }
}

Parameters

Request envelope

Quote takes operation, input, and pricingContext. Create takes the same fields plus maxCredits and config.

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

Only the listed fields are accepted in this object.

Request · inputRequired

object

Selected Vidu Enterprise v2 request body. Use public http(s) media URLs only. callback_url and callbackUrl are rejected; use config.webhookUrl on task creation. The complete operation-by-operation field index and nested shapes are documented at https://docs.omnapi.com/guides/vidu/#complete-input-field-index.
1 field
- Request · input[key]Each value
  
  any JSON value
  
  Key pattern: ^(.*)$.
Request · operationRequired

"image-to-video" | "reference-to-video" | "start-end-to-video" | "text-to-video" | "reference-to-image" | "text-to-audio" | "timing-to-audio" | "text-to-speech" | "voice-clone" | "lip-sync" | "motion-sync-v1" | "motion-sync-v2" | "extend-video" | "multi-frame-video" | "upscale-video" | "replace-video" | "digital-human" | "prompt-recommendation" | "template" | "template-story" | "general-film-create" | "general-film-edit" | "general-film-compose" | "ad-film-create" | "ad-film-edit" | "ad-film-compose" | "trending-replicate"

Allowlisted Vidu operation. OmnAPI maps this value to a fixed Vidu endpoint; arbitrary paths are never accepted.
Request · configOptional

object

Standard task configuration: priority, tags, metadata, and webhookUrl.
4 fields
- Request · config.metadataOptional
  
  object
  
  Open extension metadata. Keys are operation-specific and may change. Preserve unknown values if forwarding; do not use these keys instead of typed status, billing or resource fields.
  1 field
  - Request · config.metadata[key]Each value
    
    any JSON value
    
    Key pattern: ^(.*)$.
- Request · config.priorityOptional
  
  number
  
  Task priority 1-10 (higher = sooner). Default 5.
  
  Minimum: 1. Maximum: 10. Default: 5.
- Request · config.tagsOptional
  
  array<string>
  
  Free-form labels for filtering. Up to 20, 100 chars each.
  
  Maximum items: 20.
  1 field
  - Request · config.tags[]Each item
    
    string
    
    Maximum characters: 100.
- Request · config.webhookUrlOptional
  
  string
  
  URL to receive task.* lifecycle events via the central webhook service.
  
  Format: uri.
Request · maxCreditsOptional

number

Optional OmnAPI-credit ceiling checked before direct debit.

Minimum: 1.
Request · pricingContextOptional

object

Additional caller-supplied inputs required to calculate price.

Only the listed fields are accepted in this object.
2 fields
- Request · pricingContext.durationSecOptional
  
  number
  
  Billing duration for URL-only media operations. OmnAPI does not download or probe the media.
  
  Maximum: 3600. Exclusive lower bound: 0.
- Request · pricingContext.providerCreditCapOptional
  
  number
  
  Vidu-credit authorization reserve for operations without a deterministic published rate card.
  
  Minimum: 1. Maximum: 100000. Multiple of: 1.

Rules the schema cannot express:

pricingContext.durationSec is required for duration-priced lip-sync, motion, upscale, and film-edit calls when input.duration is absent.
pricingContext.providerCreditCap is required for replace-video, digital-human, template, and template-story.
input contains Vidu’s fields directly — do not wrap or rename them. Never send Vidu credentials or Vidu’s callback_url / callbackUrl; use config.webhookUrl.
For general-film-edit and general-film-compose, include the parent id in input; OmnAPI places it in the Vidu URL path and removes it from the body.

Complete `input` field index

input is an open object in the OpenAPI contract: OmnAPI validates the wrapper, pricing inputs, public-URL rule, and callback restriction, and Vidu validates the rest. Generated SDKs therefore do not check nested Vidu fields. The fields below are OmnAPI’s documented contract; other fields may be forwarded but are not guaranteed. Names are case-sensitive, and “one of” means at least one member of the group is required. Ranges, formats, and file-size limits come from the linked Vidu reference.

image-to-video

Required: model: string, images: string[1]

Optional: prompt, voice_id, is_rec, bgm, audio, audio_type, duration, seed, resolution, movement_amplitude, payload, off_peak

reference-to-video

Required: model, subjects[], prompt

Optional: auto_subjects, audio, audio_type, duration, seed, aspect_ratio, resolution, movement_amplitude, payload, off_peak; each subject requires name and images[], with optional voice_id

start-end-to-video

Required: model, images: string[2]

Optional: prompt, is_rec, duration, seed, resolution, movement_amplitude, bgm, audio, payload, off_peak

text-to-video

Required: model, prompt

Optional: style, duration, seed, aspect_ratio, resolution, movement_amplitude, bgm, audio, payload, off_peak

reference-to-image

Required: model, prompt

Optional: images (0–7 for viduq2, 1–7 for viduq1), seed, aspect_ratio, resolution, payload

text-to-audio

Required: model, prompt

Optional: duration, seed

timing-to-audio

Required: model, timing_prompts[]

Optional: duration, seed; each timing item uses from, to, and prompt

text-to-speech

Required: text, voice_setting_voice_id

Optional: voice_setting_speed, voice_setting_volume, voice_setting_pitch, voice_setting_emotion, payload

voice-clone

Required: audio_url, voice_id, text

Optional: prompt_audio_url, prompt_text, payload

lip-sync

Required: video_url, one of audio_url or text

Optional: speed, voice_id, ref_photo_url, volume

motion-sync-v1

Required: image_url, video_url

Optional: payload

motion-sync-v2

Required: images, video_urls

Optional: template (motion_control_2 by default; motion_control_2.5 is accepted), payload

extend-video

Required: model, one of video_creation_id or video_url

Optional: images, prompt, duration, resolution, payload

multi-frame-video

Required: model, start_image, image_settings[]

Optional: resolution, payload; every image_settings item requires key_image and may include prompt and duration

upscale-video

Required: one of video_url or video_creation_id

Optional: upscale_resolution, payload

replace-video

Required: video_url, object, image

Optional: prompt, start_from, payload; also requires pricingContext.providerCreditCap

digital-human

Required: model, image, plus the speech/prompt fields required by the selected mode

Optional: prompt, audio_url, text, voice_id, resolution, payload; also requires pricingContext.providerCreditCap

prompt-recommendation

Required: images, type[] (template, img2video, or both)

Optional: resolution, count (1–10)

template

Required: template, images[]

Optional: prompt, seed, aspect_ratio, area, beast, bgm, payload; also requires pricingContext.providerCreditCap

template-story

Required: story, images[]

Optional: payload; also requires pricingContext.providerCreditCap

general-film-create

Required: images[], duration (10–180)

Optional: prompt, aspect_ratio, payload

general-film-edit

Required: id, job_id, prompt

Optional: None

general-film-compose

Required: id, job_ids

Optional: None

ad-film-create

Required: images[]

Optional: prompt, duration, aspect_ratio, language

ad-film-edit

Required: ad_one_click_task_id, type, prompt

Optional: storyboard_video_index (required when type is generate_video), payload

ad-film-compose

Required: ad_one_click_task_id, video_task_ids[], bgm_task_id, narration_task_id

Optional: payload

trending-replicate

Required: video_url, images[]

Optional: prompt, aspect_ratio, resolution, remove_audio

Response and task status

The create receipt (see Create) returns taskId, status, creditsRequired, viduCredits, pricingMode, and pollUrl. Save taskId; the receipt does not mean the job has finished.

GET /api/v1/vidu/tasks/{taskId} returns:

Field	Meaning
`status`	`PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, or `CANCELLED`. The last three are final.
`progress`	0–100. An observation, not an ETA.
`resources[]`	Output files. Select by `type` and `role`, not array position.
`output`	Vidu’s operation-specific result, including `raw`. Read film and ad-film child IDs from here.
`errorCode`, `errorMessage`	Failure details. Branch on `errorCode`, not the message text.
`outputUrlTtlHours`	Always `1`: the download window.

The one-hour window is a conservative limit across operations. Some Vidu creation URLs stay valid for 24 hours, but finished outputs can expire sooner and OmnAPI keeps no copy, so download immediately. If a resource carries an earlier expiry, honor it.

Cancellation and callbacks

POST /api/v1/vidu/tasks/{taskId}/cancel cancels and refunds immediately if the task has not been submitted to Vidu yet. After submission, OmnAPI asks Vidu to cancel and refunds only when Vidu confirms. A 409 means cancellation was not confirmed: the task is still running and was not refunded, so keep polling.

Lifecycle callbacks use config.webhookUrl and the standard webhook contract, with signatures and retries. Vidu’s own callback_url is rejected.

Limits and notes

Media inputs must be public http:// or https:// URLs that Vidu can fetch.
pricingContext.durationSec must be greater than 0 and at most 3,600 seconds.
pricingContext.providerCreditCap must be a whole number from 1 to 100,000.
general-film-create takes 10–180 seconds; text/timing-to-audio up to 10 seconds; multi-frame up to 9 segments.
Q3 Pro Fast is image-to-video only; Q3 Mix has no off-peak rate.
Model-specific durations, resolutions, aspect ratios, formats, and file sizes follow the linked Vidu reference for each operation.
“Vidu Enterprise v2” names Vidu’s input format only. It does not select Omn MV API v2, and the endpoints stay under /api/v1/vidu.

Troubleshooting

Symptom	Cause	What to do
`400` mentioning `callback_url`	Vidu’s callback field was sent in `input`.	Remove it and set `config.webhookUrl`.
`400` “must use a public http(s) URL”	A media field holds Base64, `data:`, `blob:`, or a non-URL value.	Host the file and send its public URL.
`400` pricing error on quote	Missing `durationSec` / `providerCreditCap`, or a model, resolution, and duration combination with no published rate.	Add the pricing field or pick a combination from Pricing.
`402` with `details.reason: "MAX_CREDITS_EXCEEDED"`	The current quote is above `maxCredits`.	Quote again and raise `maxCredits` if the new price is acceptable. No credits were debited.
`402` insufficient credits	The balance cannot cover `creditsRequired`.	Add credits, then submit again.
`409` on create	The `Idempotency-Key` was reused with a different body.	Use a new key for a new job; resend the original body for a retry.
`409` on cancel	Vidu has not confirmed cancellation.	Keep polling; the task may still complete and be charged.
`FAILED` status	Vidu rejected or could not complete the job.	Read `errorCode`; check the operation’s Vidu reference for field rules.
Download returns `403` or `404`	The output URL expired.	Download within one hour of completion; OmnAPI keeps no copy.

POST /api/v1/vidu/quote — price a request without charging.
POST /api/v1/vidu/tasks — create a task.
GET /api/v1/vidu/tasks/{taskId} — read status and resources.
POST /api/v1/vidu/tasks/{taskId}/cancel — cancel a task.
Task operations — list, stream, and cancel tasks across products.

Vidu API

Models

Supported operations

Pricing

Complete price matrix

Q3 image, text, and start/end video

Q3 reference-to-video

Q2 video generation

Q1 and Vidu 2.0 video

Image, audio, and speech

Video tools, prompt, and motion

Video extension and multi-frame

Film and advertising solutions

Authorization-cap operations

How it works

Quickstart

Quote

Create

Poll and download

Examples

Text to video

Start and end frames

Reference to video

Reference to image

Lip sync with a known duration

Upscale a video

Effect template with a spend cap

Edit a general film

Parameters

Request envelope

Request · inputRequired

Request · input[key]Each value

Request · operationRequired

Request · configOptional

Request · config.metadataOptional

Request · config.metadata[key]Each value

Request · config.priorityOptional

Request · config.tagsOptional

Request · config.tags[]Each item

Request · config.webhookUrlOptional

Request · maxCreditsOptional

Request · pricingContextOptional

Request · pricingContext.durationSecOptional

Request · pricingContext.providerCreditCapOptional

Complete input field index

Response and task status

Cancellation and callbacks

Limits and notes

Troubleshooting

Related operations

Request · `input`Required

Request · `input[key]`Each value

Request · `operation`Required

Request · `config`Optional

Request · `config.metadata`Optional

Request · `config.metadata[key]`Each value

Request · `config.priority`Optional

Request · `config.tags`Optional

Request · `config.tags[]`Each item

Request · `config.webhookUrl`Optional

Request · `maxCredits`Optional

Request · `pricingContext`Optional

Request · `pricingContext.durationSec`Optional

Request · `pricingContext.providerCreditCap`Optional

Complete `input` field index