OmniHuman 1.5 Subject Detection

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 subject detection task. Upload a portrait image and the model will detect subjects in the image, supporting up to 5 subjects.

• 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.

TIP

This endpoint is free.

Related Resources

• 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 subject detection. This field is required. - This endpoint must use the omnihuman-1-5/subject-detection model Default："omnihuman-1-5/subject-detection"。 Allowed values：omnihuman-1-5/subject-detection。 示例：omnihuman-1-5/subject-detection。
input	object	Yes	Input parameters for the subject detection task.
input.image_url	string	Yes	Portrait image URL. Supports detection of up to 5 subjects in the image. Accepted file types: image/jpeg, image/png, image/jpg. Max file size: 5MB.
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

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/subject-detection",
  "input": {
    "image_url": "https://your-domain.com/image/portrait.png"
  },
  "callBackUrl": "https://your-domain.com/api/callback"
}'

{
  "model": "omnihuman-1-5/subject-detection",
  "input": {
    "image_url": "https://your-domain.com/image/portrait.png"
  },
  "callBackUrl": "https://your-domain.com/api/callback"
}

Response

200 — Request successful

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

Callback

videoTaskCompleted

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

The system sends this callback when the omnihuman-1-5/subject-detection 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/subject-detection。 示例：omnihuman-1-5/subject-detection。
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

{
  "code": 200,
  "msg": "Playground task completed successfully.",
  "data": {
    "taskId": "task_example_video_webhook_001",
    "model": "omnihuman-1-5/subject-detection",
    "state": "success",
    "param": "{\"input\":\"{\\\"image_url\\\":\\\"https://example.com/input-image.jpg\\\"}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"omnihuman-1-5/subject-detection\"}",
    "resultJson": "{\"resultObject\":{\"mask_urls\":[\"https://example.com/mask-1.png\",\"https://example.com/mask-2.png\"]}}",
    "costTime": 12,
    "completeTime": 1234567890,
    "createTime": 1234560000,
    "updateTime": 1234567890,
    "creditsConsumed": 1.23
  }
}

Task failed

{
  "code": 501,
  "msg": "Playground task failed.",
  "data": {
    "taskId": "task_example_video_webhook_001",
    "model": "omnihuman-1-5/subject-detection",
    "state": "fail",
    "param": "{\"input\":\"{\\\"image_url\\\":\\\"https://example.com/input-image.jpg\\\"}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"omnihuman-1-5/subject-detection\"}",
    "failCode": "400",
    "failMsg": "<error detail>",
    "costTime": 12,
    "creditsConsumed": 0
  }
}