Avatar Offline Edition – Detailed Parameters
Create a Task
Creates a character video generation task, returning the task ID and initial state. The generation result is obtained via the "Query Task" API or through a callback.
Request
Request body example
Response example
Basic Field Descriptions
modelstringOptionalModel. Default: vidu-s1
imagestringRequiredCharacter image. Supports three forms: public URL, base64 (must include the MIME prefix, e.g., data:image/png;base64,{base64_encode}), and ssupload:?id=<asset_id>
image_recaptionstringOptionalImage caption (image-to-text result), up to 8,192 characters. When omitted, the system generates it automatically from the image
audiostringConditionalSpeech audio; supports URL / base64 / ssupload:?id=<asset_id>. At least one of audio and text must be provided; if both are provided, audio takes precedence
textstringConditionalSpeaking text; at least one of audio and text must be provided (audio takes precedence if both are given). UTF-8 encoded, up to 10,000 characters; when text is provided, the system synthesizes it into speech
voicestringOptionalVoice timbre; the default voice is used when omitted. Only effective in text mode (when audio is not provided); see the voice list
timelinestringOptionalAction timeline: a serialized ActionContent JSON string; see the [timeline] section for the format. When omitted, the system automatically generates it based on the audio
resolutionstringOptionalResolution. Options: 540p, 720p; default: 540p
callback_urlstringOptionalCallback URL for task state changes; see the "Callback Protocol" section for details
payloadstringOptionalPass-through parameter, processed in no way and returned as-is in responses and query results; commonly used to correlate business order numbers
watermarkboolOptionalWhether to add a watermark. Enabled by default when omitted — only an explicit false disables it. When enabled, the watermarked video can be obtained via watermarked_url in the query API
wm_positionenumOptionalPosition of the "Generated by AI" label in the frame; only effective when watermark=true. Options: top_left, top_right, bottom_left, bottom_right; default: bottom_right. Note: this field controls the position of the AI-generated compliance label; the Vidu brand watermark is fixed in the bottom-right corner and is not affected by this field. An invalid enum value causes the request to return 400; when omitted, the default position is used
wm_urlstringOptionalCustom watermark image URL
meta_datastringOptionalPass-through metadata, a JSON-format string. When empty, the default metadata label generated by Vidu is used
image / audio: Asset Input Methods
Both image and audio accept three forms — choose any one; they cannot be mixed within the same field.
| Form | Description |
|---|---|
| Public URL | Most common. Must be an HTTP(S) address accessible from the server; a download failure returns ImageDownloadFailure |
| base64 | Must include the content-type prefix, e.g., data:image/png;base64,{base64_encode}. Note that the HTTP request body itself has a size limit; for large files, using a URL is recommended |
| ssupload:?id=<asset_id> | Once the platform upload API returns an asset ID, pass it in this URI form. Suitable when the same asset is used repeatedly, saving the time of repeated uploads and downloads |
image supports only one single-person image; full-body or half-body, and any style, are all acceptable. If body or face detection on the image fails, the task will fail with error codes such as ImageCheckBodyJointsFailed, ImageCheckFaceFailed, or ImageObjectsUndetected; in that case, replace the character image and retry.
timeline
The value of timeline is a serialized JSON string, not a JSON object; the inner quotes must be escaped in the request body.
actionsArrayAction list describing the character's actions by time range
actions[].textstringAction description text. It can be a short command such as "make a heart gesture", or a detailed description covering expression, gaze, and body position — the more specific the description, the more controllable the actions
actions[].time_rangeArray[uint32]Action start and end times (in seconds); must contain exactly 2 uint32 values — start time, then end time. An interval of at least 5 seconds between actions is recommended
Note: when timeline is not provided, the system automatically generates an action timeline based on the audio, which is suitable for scenarios that do not require precise action control.
**Audio mode: ** audio + detailed action descriptions Call example
**text + voice mode: ** omit audio; the system synthesizes the speaking text into speech and automatically generates the action timeline Call example:
Response Field Descriptions
task_idint64Task ID, used to query the task status; make sure to save it
stateenumTask state; reuses the platform's existing State enum; usually created upon successful creation
modelstringModel identifier
resolutionstringResolution
payloadstringPass-through parameter returned as-is
created_attimestampTask creation time
Note: this API does not return credit consumption; see "Pricing" for when credits are pre-deducted and refunded.
Note: a successful creation only means the task has been accepted, not that the video has been generated. You must poll the query API with the returned task_id, or configure a callback_url and wait for the callback.
Query Task
Returns the status, credit consumption, error information, and artifact list by task ID.
Request example
Response example
Response Body Field Descriptions
idStringTask ID
stateStringProcessing status; see the "state enum" below for values
progressNumberTask progress percentage; may be a decimal (e.g., 33.05). The value advances non-linearly: during queueing and processing it rises in steps and stays at 99 for a long time, and only becomes 100 once the task enters success/failed — this is normal. For display only; do not use it to judge whether a task is stuck — use wall-clock time for timeout decisions
err_codeStringError code; see the "Error Codes" section; an empty string when there is no error
err_msgStringDetailed error description; an empty string when there is no error. Use this field for troubleshooting: err_code only gives the error category, while the specific cause (which field, which image failed) is here
creditsIntActual number of credits consumed by this task; the value equals duration (1 credit per second). Actual billing is based on this API; see "Pricing" for when credits are deducted
durationIntLength of the generated video, in seconds; billing basis
typeStringTask type; fixed to offline_avatar for non-real-time characters
modelStringActual model identifier used. Note that the query API returns vidus1 (without a hyphen), which differs from the vidu-s1 spelling passed at creation
resolutionStringActual output resolution
payloadStringPass-through parameter provided when this task was called
blocked_resourcesArrayList of resources blocked by risk control; normally an empty array
Artifact results; read only after state=success
creations.idStringArtifact ID, used to distinguish different artifacts
creations.urlStringArtifact video URL (no watermark); valid for 24 hours
creations.cover_urlStringArtifact cover; valid for 24 hours
creations.watermarked_urlStringWatermarked artifact URL; valid for 24 hours. Watermarking is on by default: this field has a value when watermark was not provided, and is empty when watermark=false was explicitly passed. Use url if you need the unwatermarked video
Note: url, cover_url, and watermarked_url are all temporary addresses that expire after 24 hours. Transfer them to your own storage promptly after receiving them; do not persist them as permanent links for external distribution.
state enum
| Value | Meaning | Terminal? |
|---|---|---|
| created | Created successfully | No — keep polling |
| queueing | Task queued | No — keep polling |
| processing | Task processing | No — keep polling |
| success | Task succeeded | Yes — read creations[] |
| failed | Task failed | Yes — read err_code |
A polling interval starting at 3–5 seconds with gradual back-off is recommended; do not go below 2 seconds, otherwise TooManyRequests may be triggered.
Callback Protocol
If callback_url is provided when creating a task, Vidu will send a POST request to that address when the task state changes; this can be used to replace polling.
- The callback request body structure is identical to the response body of the "Query Task" API.
- The states that trigger callbacks include: processing (task processing), success (task completed), and failed (task failed).
- If the delivery of a success or failed callback fails, it will be retried — up to 4 deliveries in total (the first attempt plus at most 3 retries, with intervals of 3s / 5s / 10s).
- Callbacks use HMAC-SHA256 signature authentication; the business side should verify the signature before trusting the callback content.
Signature Algorithm
| Parameter | Description |
|---|---|
| secret_key | The token used when creating the task |
| http_method | HTTP request method, must be all uppercase; POST for callbacks |
| http_uri | The path portion extracted from callback_url using standard URL parsing; must start with /; an empty path is / |
| canonical_query_string | The query-string portion extracted from callback_url; an empty string if there are no query parameters |
| access_key | API identifier, fixed as vidu |
| Date | The Date header of the request, in GMT format |
| signed_headers_string | The request headers listed in X-HMAC-SIGNED-HEADERS, in the specified order, joined as Key: Value\n lines (with the trailing newline kept) |
Callback Request Headers
| Header | Description |
|---|---|
| Date | GMT-format time, e.g., Tue, 06 May 2025 12:09:42 GMT |
| x-request-nonce | Random string used to prevent replay attacks |
| X-HMAC-SIGNED-HEADERS | List of header fields used in the signature, separated by semicolons, e.g., Date;x-request-nonce |
| X-HMAC-SIGNATURE | The final computed signature |
| X-HMAC-ALGORITHM | Signature algorithm, fixed as hmac-sha256 |
| X-HMAC-ACCESS-KEY | Access key identifier, fixed as vidu |
Taking the callback URL http://127.0.0.1:8080/vidu/callback?name=james&age=36 as an example, the generated signing string is:
The signing string has a trailing newline character; extract both the path and the query parameters from
callback_url using a standard URL parser — do not assemble them by hand.
Error Codes
The table below lists the common values of err_code when a task fails. For [asset-type] errors, replace the character image or audio and retry; for [quota-type] errors, adjust the calling pace or contact sales. The errors listed after it are triggered by the request itself and appear in the reason field of the HTTP response body — they are not the task's err_code.
| Error Code | Description | Suggested Handling |
|---|---|---|
| FieldInvalid | A provided parameter failed validation | Check the values and formats of fields such as resolution and timeline |
| ImageDownloadFailure | Failed to download the image URL | Make sure the image address is accessible from the server, requires no authentication, and has not expired |
| ImageFormatInvalid | Image format does not meet requirements | Switch to the PNG / JPG / JPEG / WEBP format |
| ImageSizeInvalid | Image is too large or too small | Resize the image and retry |
| ImageCheckFaceFailed | Face detection failed on the input image | Use a single-person image with a clear, front-facing, complete face |
| ImageCheckBodyJointsFailed | Body detection failed on the input image | Use a character image with the body's key parts visible |
| ImageObjectsUndetected | The person or face in the input image is occluded | Use an unoccluded character image |
| NoFaceDetected | No face detected | Use a character image containing a clear face |
| MultiFaceDetected | Multiple persons detected | Only single-person images are supported; crop to a single person and retry |
| AuditSubmitIllegal | The input did not pass the safety review | Adjust the input assets or text content |
| CreationPolicyViolation | The generated content triggered risk control | Adjust the input and retry |
| CreditInsufficient | Insufficient credits | Top up and retry |
| UserCancelled | The user manually terminated the task | No action needed |
| InternalServiceFailure | Internal server error | Retry after a short wait; if failures persist, provide the task_id and request time for investigation |
Request errors (HTTP errors triggered by the request itself; the field is reason, not the task's err_code)
| reason | Description | Suggested Handling |
|---|---|---|
| BadRequest | Invalid request | Fix the request according to the field descriptions in this page |
| FieldLacking | Missing field; the specific field is given in the error message | Fill in the required fields; note that at least one of audio and text must be provided |
| QuotaExceeded | Concurrency limit exceeded | Reduce concurrency; contact sales to raise the quota |
| TooManyRequests | Requests too frequent | Lower the polling frequency and use back-off retries |
| TaskNotFound | task_id not found | Confirm the task_id is correct and belongs to the account of the current API Key |
| Unauthorized | Not authenticated | Check that Authorization: Token vda_xxx is correct |
| Forbidden | The request lacks permission | Make sure you use the same API Key that created the task |
Integration Key Points
- image is required and supports only one single-person image; at least one of audio and text must be provided, and audio takes precedence when both are given.
- voice only takes effect in text mode (when audio is not provided); setting voice when audio is provided has no effect.
- timeline is a serialized JSON string, not a JSON object — mind the quote escaping; time_range must be exactly 2 uint32 values.
- Polling must have back-off, a total timeout, and cancellation; read creations[] only after state=success.
- Artifact URLs expire in 24 hours; for long-term retention, transfer them to your own storage promptly.
- When configuring callback_url, always verify the HMAC signature; do not trust callback content unconditionally.
- Tasks are asynchronous; you must implement polling or callbacks.
- Read creations[] only when state=success; when failed, use err_code to determine whether it is a parameter issue, a review issue, or a credits issue.
Pricing
- Billed by video duration: 1 credit (RMB 0.03125) per second, with the duration rounded up from the actual length of the input audio; when text is provided, billing is based on the duration of the synthesized speech (about 2–3 characters per second).
- A task cannot be initiated when the balance falls below 45 credits (about RMB 1.4).
- When credits are deducted: the create API only performs a balance pre-check and does not deduct credits; once the task enters the queue, credits are pre-deducted in one go based on the estimated duration. If the task fails or produces no artifact, the unconsumed portion is refunded automatically; the final deduction is the credits value returned by the query API (0 when failed).