Omnihuman 2.0

接口

POST /jobs/createTask

完整 URL: https://modelfold.ai/v1/jobs/createTask

鉴权：所有请求都需要 Authorization: Bearer <API_KEY> 请求头。

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

请求参数

请求体 (application/json)

参数	类型	必填	说明
`model`	`string`	是	The model name used for generation. This field is required. - This endpoint must use the `omnihuman-2-0` model 默认值：`"omnihuman-2-0"`。可选值：`omnihuman-2-0`。示例：`omnihuman-2-0`。
`input`	`object`	是	Input parameters for the OmniHuman 2.0 video generation task.
`input.image_urls`	`array<string>`	是	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`	是	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`	否	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`	否	Whether to add a watermark to the output video. Default: `true` (enabled). 默认值：`true`。示例：`true`。
`callBackUrl`	`string`	否	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

请求示例

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"
}

响应

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"
  }
}

回调

videoTaskCompleted

回调地址：{request.body#/callBackUrl}（即请求体里的 callBackUrl）。

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

回调体参数

参数	类型	必填	说明
`code`	`integer`	是	Unified callback code: 200 for success, 501 for failure. 可选值：`200` / `501`。示例：`200`。
`msg`	`string`	是	Unified callback message. 可选值：`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. 可选值：`omnihuman-2-0`。示例：`omnihuman-2-0`。
`data.state`	`string`	是	Terminal task state. 可选值：`success` / `fail`。示例：`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 ​

接口 ​

Create Task ​

File Upload ​

Related Resources ​

请求参数 ​

请求体 (application/json) ​

请求示例 ​

响应 ​

200 — Request successful ​

回调 ​

videoTaskCompleted ​

Omnihuman 2.0

接口

Create Task

File Upload

Related Resources

请求参数

请求体 (application/json)

请求示例

响应

200 — Request successful

回调

videoTaskCompleted