Omnihuman 2.0

Endpoint

POST /jobs/createTask

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

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

Create Task

Use this endpoint to create an OmniHuman 2.0 video generation task. Provide an image, an audio file, and an optional text prompt. The model generates a video whose appearance matches the input image and whose motion is driven by 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

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-2-0` model Default：`"omnihuman-2-0"`。 Allowed values：`omnihuman-2-0`。 Example：`omnihuman-2-0`。
`input`	`object`	Yes	Input parameters for the OmniHuman 2.0 video generation task.
`input.image_urls`	`array<string>`	Yes	Source image URL. Only one image is supported. Pass it as a one-element array. - Formats: jpeg, png, webp, bmp, tiff, gif, heic, heif (`image/jpeg`, `image/png`, `image/webp`, `image/bmp`, `image/tiff`, `image/gif`, `image/heic`, `image/heif`) - Size: less than 30 MB - Aspect ratio (width/height): `[0.4, 2.5]` - Dimension: `[300, 6000]` px
`input.audio_url`	`string`	Yes	Audio URL that drives motion and lip sync. - Duration: `[4, 300]` seconds - Formats: wav, mp3 (`audio/wav`, `audio/x-wav`, `audio/mpeg`) - Size: less than 15 MB
`input.prompt`	`string`	No	Optional text prompt for precise control of the scene, character motion, and camera movement. Supported languages: Chinese, English, Japanese, Korean, Spanish (Mexican), Indonesian. Up to 300 characters. maxLength: `300`.
`input.enable_watermark`	`boolean`	No	Whether to add a watermark to the output video. Default: `true` (enabled). Default：`true`。 Example：`true`。
`callBackUrl`	`string`	No	The URL to receive generation task completion updates. Optional but recommended for production use. - The system POSTs task status and results to this URL when generation completes (success or failure) - On success, `data.resultJson` contains `resultUrls` with the generated MP4 video URL - `data.param` echoes the submitted OmniHuman 2.0 input (`image_urls`, `audio_url`, `prompt`, `enable_watermark`) - Your endpoint should accept POST requests with a JSON payload - Alternatively, poll task status with the Get Task Details endpoint - To verify callbacks, see Webhook Verification Guide

Request Example

bash

curl -X POST "https://modelfold.ai/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "omnihuman-2-0",
  "input": {
    "image_urls": [
      "https://static.aiquickdraw.com/tools/example/1792734497529_2RcDODp8.png"
    ],
    "audio_url": "https://static.aiquickdraw.com/tools/example/1792734490067_FvBSDOOl.wav",
    "prompt": "A museum guide explains how starlight lets us look into the universe’s past in a friendly, engaging manner.",
    "enable_watermark": true
  },
  "callBackUrl": "https://your-domain.com/api/callback"
}'

python

import os
import requests

resp = requests.post(
    "https://modelfold.ai/v1/jobs/createTask",
    headers={
        "Authorization": "Bearer " + os.environ["MODELFOLD_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "model": "omnihuman-2-0",
        "input": {
            "image_urls": [
                "https://static.aiquickdraw.com/tools/example/1792734497529_2RcDODp8.png",
            ],
            "audio_url": "https://static.aiquickdraw.com/tools/example/1792734490067_FvBSDOOl.wav",
            "prompt": "A museum guide explains how starlight lets us look into the universe’s past in a friendly, engaging manner.",
            "enable_watermark": True,
        },
        "callBackUrl": "https://your-domain.com/api/callback",
    },
)
print(resp.json())

javascript

const resp = await fetch("https://modelfold.ai/v1/jobs/createTask", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.MODELFOLD_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "omnihuman-2-0",
    "input": {
      "image_urls": [
        "https://static.aiquickdraw.com/tools/example/1792734497529_2RcDODp8.png"
      ],
      "audio_url": "https://static.aiquickdraw.com/tools/example/1792734490067_FvBSDOOl.wav",
      "prompt": "A museum guide explains how starlight lets us look into the universe’s past in a friendly, engaging manner.",
      "enable_watermark": true
    },
    "callBackUrl": "https://your-domain.com/api/callback"
  }),
});
console.log(await resp.json());

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{"model":"omnihuman-2-0","input":{"image_urls":["https://static.aiquickdraw.com/tools/example/1792734497529_2RcDODp8.png"],"audio_url":"https://static.aiquickdraw.com/tools/example/1792734490067_FvBSDOOl.wav","prompt":"A museum guide explains how starlight lets us look into the universe’s past in a friendly, engaging manner.","enable_watermark":true},"callBackUrl":"https://your-domain.com/api/callback"}`)
	req, _ := http.NewRequest("POST", "https://modelfold.ai/v1/jobs/createTask", body)
	req.Header.Set("Authorization", "Bearer " + os.Getenv("MODELFOLD_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(string(out))
}

java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String body = "{\"model\":\"omnihuman-2-0\",\"input\":{\"image_urls\":[\"https://static.aiquickdraw.com/tools/example/1792734497529_2RcDODp8.png\"],\"audio_url\":\"https://static.aiquickdraw.com/tools/example/1792734490067_FvBSDOOl.wav\",\"prompt\":\"A museum guide explains how starlight lets us look into the universe’s past in a friendly, engaging manner.\",\"enable_watermark\":true},\"callBackUrl\":\"https://your-domain.com/api/callback\"}";
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create("https://modelfold.ai/v1/jobs/createTask"))
            .header("Authorization", "Bearer " + System.getenv("MODELFOLD_API_KEY"))
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> resp = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(resp.body());
    }
}

php

<?php
$ch = curl_init('https://modelfold.ai/v1/jobs/createTask');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv("MODELFOLD_API_KEY"),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{"model":"omnihuman-2-0","input":{"image_urls":["https://static.aiquickdraw.com/tools/example/1792734497529_2RcDODp8.png"],"audio_url":"https://static.aiquickdraw.com/tools/example/1792734490067_FvBSDOOl.wav","prompt":"A museum guide explains how starlight lets us look into the universe’s past in a friendly, engaging manner.","enable_watermark":true},"callBackUrl":"https://your-domain.com/api/callback"}',
]);
echo curl_exec($ch);
curl_close($ch);

csharp

using System;
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var req = new HttpRequestMessage(new HttpMethod("POST"), "https://modelfold.ai/v1/jobs/createTask");
req.Headers.TryAddWithoutValidation("Authorization", "Bearer " + Environment.GetEnvironmentVariable("MODELFOLD_API_KEY"));
req.Content = new StringContent("{\"model\":\"omnihuman-2-0\",\"input\":{\"image_urls\":[\"https://static.aiquickdraw.com/tools/example/1792734497529_2RcDODp8.png\"],\"audio_url\":\"https://static.aiquickdraw.com/tools/example/1792734490067_FvBSDOOl.wav\",\"prompt\":\"A museum guide explains how starlight lets us look into the universe’s past in a friendly, engaging manner.\",\"enable_watermark\":true},\"callBackUrl\":\"https://your-domain.com/api/callback\"}", Encoding.UTF8, "application/json");
var resp = await client.SendAsync(req);
Console.WriteLine(await resp.Content.ReadAsStringAsync());

json

{
  "model": "omnihuman-2-0",
  "input": {
    "image_urls": [
      "https://static.aiquickdraw.com/tools/example/1792734497529_2RcDODp8.png"
    ],
    "audio_url": "https://static.aiquickdraw.com/tools/example/1792734490067_FvBSDOOl.wav",
    "prompt": "A museum guide explains how starlight lets us look into the universe’s past in a friendly, engaging manner.",
    "enable_watermark": true
  },
  "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 balance; 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": "dc1928bfcbc77cb6c85f3359a9c718b3"
  }
}

Callback

videoTaskCompleted

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

The system sends this callback when the omnihuman-2-0 task succeeds or fails.

Callback body parameters

参数	类型	必填	说明
`code`	`integer`	是	Unified callback code: 200 for success, 501 for failure. Allowed values：`200` / `501`。 Example：`200`。
`msg`	`string`	是	Unified callback message. Allowed values：`Playground task completed successfully.` / `Playground task failed.`。 Example：`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-2-0`。 Example：`omnihuman-2-0`。
`data.state`	`string`	是	Terminal task state. Allowed values：`success` / `fail`。 Example：`success`。
`data.param`	`string`	是	JSON string containing the submitted task parameters. The nested `input` object includes `image_urls` (one image), `audio_url`, `prompt`, and `enable_watermark`.
`data.resultJson`	`string`	否	JSON string containing `resultUrls` with the generated MP4 video URL 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.

Task completed successfully

json

{
  "code": 200,
  "msg": "Playground task completed successfully.",
  "data": {
    "taskId": "task_omnihuman-2-0_1234567890",
    "model": "omnihuman-2-0",
    "state": "success",
    "param": "{\"input\":\"{\\\"image_urls\\\":[\\\"https://static.aiquickdraw.com/tools/example/1792734497529_2RcDODp8.png\\\"],\\\"audio_url\\\":\\\"https://static.aiquickdraw.com/tools/example/1792734490067_FvBSDOOl.wav\\\",\\\"prompt\\\":\\\"A museum guide explains how starlight lets us look into the universe’s past in a friendly, engaging manner.\\\",\\\"enable_watermark\\\":true}\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"omnihuman-2-0\"}",
    "resultJson": "{\"resultUrls\":[\"https://static.aiquickdraw.com/tools/example/1792734516894_OplehJyL.mp4\"]}",
    "costTime": 12,
    "completeTime": 1234567890,
    "createTime": 1234560000,
    "updateTime": 1234567890
  }
}

Task failed

json

{
  "code": 501,
  "msg": "Playground task failed.",
  "data": {
    "taskId": "task_omnihuman-2-0_1234567890",
    "model": "omnihuman-2-0",
    "state": "fail",
    "param": "{\"input\":\"{\\\"image_urls\\\":[\\\"https://static.aiquickdraw.com/tools/example/1792734497529_2RcDODp8.png\\\"],\\\"audio_url\\\":\\\"https://static.aiquickdraw.com/tools/example/1792734490067_FvBSDOOl.wav\\\",\\\"prompt\\\":\\\"A museum guide explains how starlight lets us look into the universe’s past in a friendly, engaging manner.\\\",\\\"enable_watermark\\\":true}\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"omnihuman-2-0\"}",
    "failCode": "400",
    "failMsg": "<error detail>",
    "costTime": 12
  }
}

Omnihuman 2.0 ​

Endpoint ​

Create Task ​

File Upload ​

Related Resources ​

Request Parameters ​

Body (application/json) ​

Request Example ​

Response ​

200 — Request successful ​

Callback ​

videoTaskCompleted ​

Omnihuman 2.0

Endpoint

Create Task

File Upload

Related Resources

Request Parameters

Body (application/json)

Request Example

Response

200 — Request successful

Callback

videoTaskCompleted