Callbacks

Using Callbacks

If you want the system to proactively notify you of the result once a task completes, pass a callback_url when creating the task. If no callback_url is provided, please retrieve the task status proactively 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 via `POST`
Content-Type	`application/json`
Success response	Any `2xx` status code returned by your service is treated as successful delivery

Video Task Success Callback

When video generation succeeds, the system sends the following JSON to your 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

When a task fails, the system sends the following JSON to your 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	Time the callback was sent, Unix timestamp in milliseconds

Callback Notes

If your service returns a 2xx status code, the system treats the callback as successfully delivered.
If your service does not return a 2xx status code, the system records the callback as failed; a failed callback does not affect the status of the task itself.
For more complete task status and timing information, call the corresponding query endpoint to retrieve the details.

Capabillty Map

Error Codes

On this page