Model CenterGlobalAiOpc

Digital Human Video Synthesis

POST/kyyReactApiServer/v2/model-center/tasks

Pricing

Generate a digital human video from your source media and speech for presentations and narration. See the request parameters below for supported inputs, versions and limits.

Submit a request to receive 1 task ID(s), then query them to get your results.

Quick start

Replace <API_KEY> in the example with your API key, edit the content and send the request.
Save every ID in task_ids and query each one every 3–5 seconds.
When status is completed, use the returned file URL to access your result.

Endpoint

http

POST https://zcbservice.aizfw.cn/kyyReactApiServer/v2/model-center/tasks

Authentication

Get Key

An API key is required. Use these headers when submitting a request, replacing <API_KEY> with your key.

http

Authorization: Bearer <API_KEY>
Content-Type: application/json

Prepare your inputs

Upload your media and provide directly accessible file URLs, not local paths or sharing pages that require sign-in. Check that each URL works and that the format meets the parameter requirements.

Start with the request example below and save the returned task ID. Once the task completes, use the video URL in the completed response to retrieve the generated file. See the completion example for its field name.

Duration billing

Billing uses the actual duration of the input audio in audioUrl, rounded up to whole seconds. For example, 12.3 seconds is billed as 13 seconds. The charge is billable seconds × price per second. You do not need to provide a separate media duration.

No charge is made if the input cannot be read or measured. A failed generation is refunded. If generation succeeds but file delivery fails, the charge is retained while the platform resolves the delivery issue.

Request parameters

Send these parameters in the JSON request body. Always include required fields; provide the remaining fields for your chosen creation mode.

modelstringrequired

Use this model name.

Values and limits: digital_human

audioUrlstringrequired

Direct URL of the audio used to drive lip movements.

Values and limits: No Chinese characters in the URL; supported formats: mp4, mp3, wav, m4a, aar (query parameters allowed)

videoUrlstringrequired

Direct URL of the source video containing the person.

Values and limits: The URL must not contain Chinese characters

sideFaceinteger

Side-face optimization: set to 1 for a pronounced side view; omit for typical inputs.

Values and limits: Allowed values: 0; 1

tiltedFaceinteger

Tilted-face optimization: set to 1 for a front-facing person with a tilted head; omit for typical inputs.

Values and limits: Allowed values: 0; 1

modelVersioninteger

Generation version. Choose one of the currently allowed values.

Values and limits: Allowed values: 7777777 (or send "v3"); 666666 (or send "v3-bigface")

Request examples

This minimal request follows the parameter rules above and omits optional fields. Replace example with your content, YOUR_ values with available identifiers (such as a voice ID), and example.com URLs with actual media URLs before submitting.

Choose a creation mode to view its request body. Full cURL, Python and JavaScript examples are available in the code panel. Install requests for Python; JavaScript examples can run with Node.js 18+.

JSON

{
  "model": "digital_human",
  "audioUrl": "https://example.com/media.mp3",
  "videoUrl": "https://example.com/media.mp4"
}

Submission response

HTTP 202 means your request is queued. Generation takes time; query the tasks to retrieve your results.

Field	Description
task_ids	All task IDs for this request. Save and query each one to retrieve every result.
id	The first task ID.
status	queued means the task is waiting to start.
error	Error message, or null when no error occurred.

Query results

http

GET https://zcbservice.aizfw.cn/kyyReactApiServer/v2/model-center/tasks/{task_id}

task_idstringrequired

Replace {task_id} in the URL with one ID from the submission response task_ids, using the same API key. Query every task separately and retain all task IDs.

Task status

status	Meaning	What to do
queued	Queued	Query again in 3–5 seconds.
processing	Processing generation or file delivery	Query again in 3–5 seconds.
completed	Completed	Read the returned result fields and use the media URLs for playback or download.
failed	Generation failed	Read error for the cause and refund_status for refund progress.
delivery_exception	Generated, but the file is unavailable	Stop polling and contact support. Do not submit again.
manual_required	The task requires review	Stop polling, keep the task ID and contact support. Do not submit again.

Completed response example

JSON

{
  "id": "mcp_00000000000000000000000000000001",
  "model": "digital_human",
  "object": "video",
  "created": 1792022400,
  "status": "completed",
  "amount": 0.25,
  "billing_status": "deducted",
  "refund_status": "none",
  "computing_power": 0,
  "data_project_id": "Example text",
  "video_url": "https://storage.example.com/video.bin",
  "error": null
}

Example URLs and credits are illustrative. Actual charges follow your account pricing and task record. Generated files are available when status is completed.

Response fields

Field	Description
id	The task ID being queried.
model	The model used for generation.
object	Result type, such as audio or video.
created	Task creation time as a Unix timestamp in seconds.
status	Task status; completed means the result is ready.
amount / billing_status / refund_status	Credits consumed, charge status and refund status for this task.
error	Error message; null on success.
error_code	Platform error code, returned when an error occurs.

Media URL field	Description
video_url	Video download URL; returned on completion

Result fields

Field	Type	Required	Description
computing_power	integer	No	本次任务消耗的算力
data_project_id	string	No	任务id

Media URLs refer to platform-stored files and can be used for playback or download. Optional URLs are omitted when unavailable.

Billing and troubleshooting

Each task is charged separately. Check refund_status for refund progress after a failed generation.

Submission timeout: check whether the original request succeeded before submitting again to avoid duplicate generation and charges. If you have a task ID, query that task.
Temporary query error: retry the query with the same task ID; do not create a new generation.
delivery_exception: the generation charge is retained. Contact support to restore file access.