Callbacks

Using Callbacks

If you want the system to proactively notify you of the result once a task completes, pass callback_url when creating the task. If callback_url is not provided, please actively fetch the task status via the query endpoint.

Callback URL Requirements

Item	Requirement
Protocol	Must use HTTP or HTTPS
Length	Up to 500 characters
Accessibility	Must be reachable by the Bach server
Request Method	Bach sends callbacks using `POST`
Content-Type	`application/json`
Success Response	Any `2xx` status code returned by your service is treated as successfully received

Video Task Success Callback

After a video is generated successfully, the system sends the following JSON to callback_url:

json

Copy

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "TASK_SUCCEEDED",
  "video_url": "https://example.com/result.mp4"
}

Field	Type	Description
`task_id`	string	Task ID
`status`	string	Task status
`video_url`	string	Video result URL

Failure Callback

After a task fails, the system sends the following JSON to callback_url:

json

Copy

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "TASK_FAILED",
  "error": {
    "code": 1001,
    "message": "Contains sensitive information."
  },
  "timestamp": 1778313600000
}

Field	Type	Description
`task_id`	string	Task ID
`status`	string	Task status
`error.code`	string	Error code
`error.message`	string	Error description
`timestamp`	number	Callback send time, Unix timestamp in milliseconds

Callback Notes

If your service returns a 2xx status code, the system treats this callback as successfully received.
If your service does not return a 2xx status code, the system records this callback as failed; a failed callback does not affect the task's own status.
To see more complete task status and timing information, call the corresponding query endpoint for details.

General

Error Codes

On this page