Omnihuman 1.5

This page is generated from the upstream official OpenAPI documentation. Endpoints, parameters and examples match the official docs; brand and API domain are replaced with ModelFold.

Endpoint

POST /jobs/createTask

Full URL: https://ai.modelfold.online/v1/jobs/createTask

Authentication: every request must include the Authorization: Bearer <API_KEY> header.

Create Task

Use this endpoint to create a new audio-driven portrait animation task. Upload a portrait image and an audio file, and the model will generate a video of the subject speaking or moving in sync with the audio.

Get Task Details — After submission, use the unified query endpoint to check task progress and retrieve results

TIP

For production use, we recommend providing the callBackUrl parameter so your service can receive completion notifications instead of polling for task status.

File Upload

TIP

Need to upload files before calling this endpoint? See File Upload API Quickstart.

Model Marketplace — Explore all available models and capabilities
Common API — Check account credits and usage

Request Parameters

Body (application/json)

Parameter	Type	Required	Description
`model`	`string`	Yes	The model name used for generation. This field is required. - This endpoint must use the `omnihuman-1-5` model Default：`"omnihuman-1-5"`。 Allowed values：`omnihuman-1-5`。示例：`omnihuman-1-5`。
`input`	`object`	Yes	Input parameters for the audio-driven portrait animation task.
`input.image_url`	`string`	Yes	Portrait image URL. Supports any aspect ratio with subjects including people, pets, anime, etc. Accepted file types: image/jpeg, image/png, image/webp. Max file size: 10MB.
`input.mask_url`	`array<string>`	No	Optional mask image URL(s). To have a specific subject in the image speak, use 'Subject Detection' to get the corresponding mask image and pass it as input. Accepted file types: image/jpeg, image/png, image/webp. Max file size: 10MB. Multiple file upload is supported, up to 5 files.
`input.audio_url`	`string`	Yes	Audio URL. Duration must be less than 60 seconds (recommended 15 seconds or less; exceeding this will cause quality degradation). Accepted file types: audio/mpeg, audio/wav, audio/x-wav, audio/aac, audio/ogg, audio/mp4. Max file size: 10MB.
`input.prompt`	`string`	No	Optional. Supported languages: Chinese, English, Japanese, Korean, Spanish, Indonesian. Up to 300 characters.
`input.output_resolution`	`string`	No	Output video resolution. - `720`: 720P - `1080`: 1080P (default) The output keeps the aspect ratio of the input image; 720 and 1080 are resolution tiers, not exact heights. The output is an MP4 as long as the audio. Default：`"1080"`。 Allowed values：`720` / `1080`。示例：`1080`。
`input.pe_fast_mode`	`boolean`	No	Fast mode. Sacrifices some quality to speed up generation. Default value: `false`. Default：`false`。示例：`false`。
`input.seed`	`integer`	No	Random seed. Default is `-1` (random). When using the same positive integer and keeping all other parameters identical, the result will be highly consistent. Default：`-1`。示例：`-1`。
`callBackUrl`	`string`	No	Callback URL. Once the task is fully completed, ModelFold will send the result to the business webhook URL. To verify callbacks, see Webhook Verification Guide.

Request Example

bash

curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "omnihuman-1-5",
  "input": {
    "image_url": "https://your-domain.com/image/portrait.png",
    "mask_url": [
      "https://your-domain.com/image/mask.png"
    ],
    "audio_url": "https://your-domain.com/audio/speech.mp3",
    "prompt": "A person speaking naturally with gentle expressions.",
    "output_resolution": "1080",
    "pe_fast_mode": false,
    "seed": -1
  },
  "callBackUrl": "https://your-domain.com/api/callback"
}'

json

{
  "model": "omnihuman-1-5",
  "input": {
    "image_url": "https://your-domain.com/image/portrait.png",
    "mask_url": [
      "https://your-domain.com/image/mask.png"
    ],
    "audio_url": "https://your-domain.com/audio/speech.mp3",
    "prompt": "A person speaking naturally with gentle expressions.",
    "output_resolution": "1080",
    "pe_fast_mode": false,
    "seed": -1
  },
  "callBackUrl": "https://your-domain.com/api/callback"
}

Response

200 — Request successful

参数	类型	必填	说明
`code`	`integer`	否	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值：`200` / `401` / `402` / `404` / `422` / `429` / `433` / `455` / `500` / `501` / `505`。示例：`200`。
`msg`	`string`	否	Response message, error description upon failure 示例：`success`。
`data`	`object`	是	—
`data.taskId`	`string`	是	The task ID can be used with the "Get Task Details" endpoint to query the task status. 示例：`dc1928bfcbc77cb6c85f3359a9c718b3`。

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_omnihuman-1-5_1234567890"
  }
}

Callback

videoTaskCompleted

Callback URL: {request.body#/callBackUrl} (the callBackUrl in the request body).

The system sends this callback when the omnihuman-1-5 task succeeds or fails.

Callback body parameters

参数	类型	必填	说明
`code`	`integer`	是	Unified callback code: 200 for success, 501 for failure. Allowed values：`200` / `501`。示例：`200`。
`msg`	`string`	是	Unified callback message. Allowed values：`Playground task completed successfully.` / `Playground task failed.`。示例：`Playground task completed successfully.`。
`data`	`object`	是	—
`data.taskId`	`string`	是	The unique task identifier.
`data.model`	`string`	是	The model used for the task. Allowed values：`omnihuman-1-5`。示例：`omnihuman-1-5`。
`data.state`	`string`	是	Terminal task state. Allowed values：`success` / `fail`。示例：`success`。
`data.param`	`string`	是	JSON string containing the submitted task parameters.
`data.resultJson`	`string`	否	JSON string containing resultUrls, firstFrameUrl, lastFrameUrl, or resultObject when successful. Present only when state is success.
`data.failCode`	`string`	否	Failure code, a numeric string such as "400" or "500". Present only when state is fail.
`data.failMsg`	`string`	否	Failure reason. Present only when state is fail.
`data.costTime`	`integer`	否	Processing time in seconds. Present on both success and failure callbacks.
`data.completeTime`	`integer`	否	Task completion timestamp.
`data.createTime`	`integer`	否	Task creation timestamp.
`data.updateTime`	`integer`	否	Use completeTime as the completion time; updateTime may equal createTime.
`data.creditsConsumed`	`number`	否	Credits consumed by the task; 0 for failed tasks.

Task completed successfully

json

{
  "code": 200,
  "msg": "Playground task completed successfully.",
  "data": {
    "taskId": "task_example_video_webhook_001",
    "model": "omnihuman-1-5",
    "state": "success",
    "param": "{\"input\":\"{\\\"image_url\\\":\\\"https://example.com/input-image.jpg\\\",\\\"mask_url\\\":[\\\"https://example.com/input-image.jpg\\\"],\\\"audio_url\\\":\\\"https://example.com/input-audio.mp3\\\",\\\"prompt\\\":\\\"A person speaking naturally with gentle expressions.\\\",\\\"output_resolution\\\":\\\"1080\\\",\\\"pe_fast_mode\\\":false,\\\"seed\\\":-1}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"omnihuman-1-5\"}",
    "resultJson": "{\"resultUrls\":[\"https://example.com/generated-video.mp4\"]}",
    "costTime": 12,
    "completeTime": 1234567890,
    "createTime": 1234560000,
    "updateTime": 1234567890,
    "creditsConsumed": 1.23
  }
}

Task failed

json

{
  "code": 501,
  "msg": "Playground task failed.",
  "data": {
    "taskId": "task_example_video_webhook_001",
    "model": "omnihuman-1-5",
    "state": "fail",
    "param": "{\"input\":\"{\\\"image_url\\\":\\\"https://example.com/input-image.jpg\\\",\\\"mask_url\\\":[\\\"https://example.com/input-image.jpg\\\"],\\\"audio_url\\\":\\\"https://example.com/input-audio.mp3\\\",\\\"prompt\\\":\\\"A person speaking naturally with gentle expressions.\\\",\\\"output_resolution\\\":\\\"1080\\\",\\\"pe_fast_mode\\\":false,\\\"seed\\\":-1}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"omnihuman-1-5\"}",
    "failCode": "400",
    "failMsg": "<error detail>",
    "costTime": 12,
    "creditsConsumed": 0
  }
}

Omnihuman 1.5 ​

Endpoint ​

Create Task ​

File Upload ​

Related Resources ​

Request Parameters ​

Body (application/json) ​

Request Example ​

Response ​

200 — Request successful ​

Callback ​

videoTaskCompleted ​

Omnihuman 1.5

Endpoint

Create Task

File Upload

Related Resources

Request Parameters

Body (application/json)

Request Example

Response

200 — Request successful

Callback

videoTaskCompleted