Vmodel API Docs

Webhook ​

Upon task completion or failure, we will send an HTTP POST request to your configured Webhook URL.

You can set the webhook_url when creating a task, and we will send a post request to your url.

Tip: Webhooks are convenient, but you can still use other methods to get task generation results. You can also poll the Check Task API to check the task status.

Set up webhooks ​

To get a webhook notification when your task completes, specify the webhook_url in the body of your task creation request, as shown in the HTTP example below:

http
curl -X POST https://api.vmodel.ai/api/tasks/v1/create
    -H "Authorization: Bearer $VModel_API_TOKEN"
    -H "Content-Type: application/json"
    -d '{
    "version": "a3c8d261fd14126eececf9812b52b40811e9ed557ccc5706452888cdeeebc0b6",
    "webhook_url": "https://example.com/vmodel-webhook",
    "input": {
        "swap_image": "https://data.vmodel.ai/data/model-example/vmodel/photo-face-swap-pro/swap_image.png",
        "target_image": "https://vmodel.ai/data/model/vmodel/photo-face-swap-pro/target_image.png",
        "disable_safety_checker": false
    }
}'

Receive webhooks ​

The webhook request body is a JSON object. Its structure is identical to the response from the Check Task API. Below is an example of a successful task payload:

json
{
  "task_id": "d9opjevn1bd48r5czq",
  "user_id": 1,
  "version": "85e248d268bcc04f5302cf9645663c2c12acd03c953ec1a4bbfdc252a65bddc0",
  "error": "",
  "total_time": 3.0,
  "predict_time": 3.0,
  "logs": "",
  "output": ["https://vmodel.ai/data/model/vmodel/photo-face-swap-pro/target_image.png"],
  "status": "succeeded",
  "create_at": 1746497063,
  "completed_at": null
}

Refer to Task status for the list of possible status values.

  • succeeded: the Task completed successfully.
  • failed: the Task encountered an error during processing.

Here’s an example of a webhook handler(python fastapi):

python
class VmodelWebhookDTO(BaseModel):
    task_id: Union[str, None] = None
    user_id: Union[int, None] = None
    version: Union[str, None] = None
    error: Union[Any, None] = None
    total_time: Union[Any, None] = None
    predict_time: Union[Any, None] = None
    logs: Union[str, None] = None
    output: Union[Any, None] = None
    status: Union[str, None] = None
    create_at: Union[int, None] = None
    completed_at: Union[int, None] = None
    
@router.post(path="/webhook/vmodel")
def vmodel_webhook(request: Request, webhook_data: VmodelWebhookDTO):
    return demohandler.vmodel_webhook(request=request, webhook_data=webhook_data)

Retries ​

To ensure reliable notification delivery, we have designed an automatic retry mechanism. When Vmodel sends a webhook to your endpoint, we will automatically trigger a retry if the request fails due to a network issue or if we receive a 4xx/5xx HTTP response code.

Retries are performed multiple times using an exponential backoff algorithm, and the entire retry cycle will conclude approximately 1 minute after the task has completed.

Idempotency ​

Please design your webhook handlers to be idempotent. As the same event may be sent more than once, your handler must be able to correctly identify and manage duplicate requests to avoid unintended consequences.