Vmodel API Docs

Tasks INFO ​

Create a task ​

Endpoint ​

http
POST https://api.vmodel.ai/api/tasks/v1/create

Description ​

Create a task for the model version and inputs you provide.

Example cURL request:

http
curl --location 'https://api.vmodel.ai/api/tasks/v1/create' \
--header 'Authorization: Bearer $API_TOKEN"' \
--header 'Content-Type: application/json' \
--data '{
    "version": "d4f292d1ea72ac4e501e6ac7be938ce2a5c50c6852387b1b64dedee01e623029",
    "input": {
        "swap_image": "https://example.com/0.png",
        "target_image": "https://example.com/1.png"
    }
}'

Request Body ​

input object Required

The model's input as a JSON object. The input schema depends on what model you are running.

Files should be passed as HTTP URLs.

version object Required

The ID of the model version that you want to run.

Just the 64-character version ID: 9dcd6d78e7c6560c340d916fe32e9f24aabfa331e5cce95fe31f77fb03121426

webhook_url object Optional

When creating a task, you need to actively set the webhook_url with a POST request. When the generation task changes its status, Vmodel will send a callback request to this URL, containing the latest status of the task. The structure of the callback request content will be the same as the return body of the GET Task API. The “status” in the callback response includes the following states:

  • succeeded: Task is completed (if sending fails, it will retry the callback three times).
  • failed: Task failed (if sending fails, it will retry the callback three times).

Response Body ​

json
{
  "code": 200,
  "result": {
    "task_id": "d9o1w1f3fxqqv5514f",
    "task_cost": 10
  },
  "message": {
    "en": "Task created successfully"
  }
}

Get a task ​

Endpoint ​

http
GET https://api.vmodel.ai/api/tasks/v1/get/{task_id}

Description ​

Get the current state of a task.

Example cURL request:

http
curl --location 'https://api.vmodel.ai/api/tasks/v1/get//d9o1w1f3fxqqv5514f' \
--header 'Authorization: Bearer $API_TOKEN"'

The response will be the prediction object:

json
{
  "code": 200,
  "result": {
    "task_id": "d9opjevn1bd48r5czq",
    "user_id": 1,
    "version": "85e248d268bcc04f5302cf9645663c2c12acd03c953ec1a4bbfdc252a65bddc0",
    "error": "",
    "total_time": 0.0,
    "predict_time": 0.0,
    "logs": "",
    "output": {},
    "status": "processing",
    "create_at": 1746497063,
    "completed_at": null
  },
  "message": {}
}

status will be one of:

  • starting: the task is starting up. If this status lasts longer than a few seconds, then it's typically because a new worker is being started to run the task.
  • processing: the run() method of the model is currently executing the task.
  • succeeded: the task completed successfully.
  • failed: the task encountered an error during processing.
  • canceled: the task was canceled by its creator.

In the case of success, output will be an object containing the output of the model. Any files will be represented as HTTPS URLs. You'll need to pass the Authorization header to request them.

In the case of failure, error will contain the error encountered during the prediction.

All input parameters, output values, and logs are automatically removed after an hour, by default, for tasks created through the API.

URL Parameters ​

  • task_id string Required

The ID of the task to get.

Response Body ​

json
{
  "code": 200,
  "result": {
    "task_id": "d9opjevn1bd48r5czq",
    "user_id": 1,
    "version": "85e248d268bcc04f5302cf9645663c2c12acd03c953ec1a4bbfdc252a65bddc0",
    "error": null,
    "total_time": 68.0,
    "predict_time": 68.0,
    "logs": null,
    "output": [
      "https://data.vmodel.ai/datarm/user/result/20250506/883608af-289c-43c0-bdc4-ca3172d96a96.mp4"
    ],
    "status": "succeeded",
    "create_at": 1746497063,
    "completed_at": 1746497131
  },
  "message": {}
}

Task Status ​

  • starting: the task is starting up. If this status lasts longer than a few seconds, then it's typically because a new worker is being started to run the task.
  • processing: the run() method of the model is currently executing the task.
  • succeeded: the task completed successfully.
  • failed: the task encountered an error during processing.
  • canceled: the task was canceled by its creator.