Poll job status or download the completed video

POST

/video/retrieve

curl --request POST \
  --url https://api.bayle.ai/video/retrieve \
  --header 'Accept-Language: pt-BR' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "model": "seedance-2-0-mini-text-to-video-basic", "queue_id": "01a07f13-21eb-712a-92bf-b437f83c5b47" }'

• Bayle production API

Reports a queued job’s progress and, once it has finished, returns the video. Send the model and the queue_id returned when the job was queued.

Poll roughly every 10 seconds. Video generation takes meaningfully longer than Bayle’s synchronous endpoints, so do not expect a job to be ready on the first call.

Authorizations

• BearerAuth

Parameters

Header Parameters

Accept-Language

string

Example

pt-BR

Chooses the language of any error message in this request’s response. A tag beginning with the two letters pt, in any case, selects Brazilian Portuguese; anything else, including an absent header, selects English. The tag may appear anywhere in a multi-tag header, for example fr-FR;q=0.9,pt;q=0.5,en;q=0.3. Quality values are accepted but ignored, since this is a presence check rather than weighted negotiation.

Request Body^required

Media typeapplication/json

The retrieve request. Any field not listed here is forwarded as sent.

object

model

required

The model the job was queued with.

string

queue_id

required

The identifier returned by POST /video/queue.

string

key

additional properties

any

Example

{
  "model": "seedance-2-0-mini-text-to-video-basic",
  "queue_id": "01a07f13-21eb-712a-92bf-b437f83c5b47"
}

Responses

200

One of two shapes under this single status, depending on whether the job has finished. Branch on the response’s Content-Type, not on a body field.

While the job is still running, the response is a JSON status document carrying status, average_execution_time, and execution_duration. Once the job has finished, the response is instead the raw video/mp4 bytes.

Bayle sends no retry-delay header, and enforces no polling cadence. The 10 second interval above is guidance for a client author rather than a signal to parse.

Some models return a download_url in the status document instead of delivering the bytes here. That is a pre-signed URL your own client fetches directly; it needs no credential and does not pass back through Bayle.

object

status

Where the job has got to.

string

average_execution_time

Typical run time for this model, in seconds.

number

execution_duration

How long this job has been running, in seconds.

number

download_url

Present for some models once the job has finished. A pre-signed URL your own client fetches directly.

string

key

additional properties

any

Examples

Still running

{
  "status": "PROCESSING",
  "average_execution_time": 102.3,
  "execution_duration": 45.1
}

Finished, for a model that returns a download URL

{
  "status": "COMPLETED",
  "average_execution_time": 102.3,
  "execution_duration": 98.7,
  "download_url": "https://example.com/downloads/01a07f13-21eb-712a-92bf-b437f83c5b47"
}

string format: binary

Headers

Content-Language

string

Allowed values: en pt-BR

Confirms which of the two supported locales, en or pt-BR, this response was rendered in, so a caller can detect it without reading the message text. Present on every response, success and error alike. On a chat completions stream it is committed together with the initial 200, so it appears whichever way the stream ends.

401

No credential was supplied, or the credential supplied is not valid. The request is rejected before any generation work begins. The body uses the shared error envelope, rendered in the negotiated locale.

Media typeapplication/json

Bayle’s OpenAI-shaped error envelope, shared by every error response this API returns.

object

error

required

object

message

required

A human-readable description of the failure, in the negotiated locale. See the Accept-Language request parameter for how that locale is chosen, and the Content-Language response header for which one was served.

string

type

required

OpenAI’s error type vocabulary, for example api_error, authentication_error, invalid_request_error, or rate_limit_error, matching the class of failure so an OpenAI SDK’s exception mapping keeps working.

string

param

required

The request field the failure names, when it names one. Null when the failure is not field-specific, as with authentication or rate limiting.

string

nullable

code

required

Bayle’s semantic error code, reusing OpenAI’s vocabulary where an equivalent exists, for example invalid_api_key or rate_limit_exceeded. Null when Bayle could not identify the specific failure; the envelope is still valid and carries a generic message. The full list lives in Bayle’s error reference rather than being enumerated here.

string

nullable

Examples

English (default)

{
  "error": {
    "message": "Your Bayle API key is missing or could not be verified.",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Brazilian Portuguese (`Accept-Language: pt-BR`)

{
  "error": {
    "message": "Sua chave de API da Bayle está ausente ou não pôde ser verificada.",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Headers

Content-Language

string

Allowed values: en pt-BR

Confirms which of the two supported locales, en or pt-BR, this response was rendered in, so a caller can detect it without reading the message text. Present on every response, success and error alike. On a chat completions stream it is committed together with the initial 200, so it appears whichever way the stream ends.

default

The request failed. The body uses the shared error envelope, rendered in the locale negotiated through Accept-Language. type and code identify the specific failure when Bayle recognizes it, and fall back to type: api_error with a null code when it does not. Where a failure carries a meaningful status code, Bayle preserves it; a transport failure, such as a timeout or a refused connection, is reported as 502. The exception is an operation that documents its own time limit, which reports running past it as 504 with the request_timeout code.

Media typeapplication/json

Bayle’s OpenAI-shaped error envelope, shared by every error response this API returns.

object

error

required

object

message

required

A human-readable description of the failure, in the negotiated locale. See the Accept-Language request parameter for how that locale is chosen, and the Content-Language response header for which one was served.

string

type

required

OpenAI’s error type vocabulary, for example api_error, authentication_error, invalid_request_error, or rate_limit_error, matching the class of failure so an OpenAI SDK’s exception mapping keeps working.

string

param

required

The request field the failure names, when it names one. Null when the failure is not field-specific, as with authentication or rate limiting.

string

nullable

code

required

Bayle’s semantic error code, reusing OpenAI’s vocabulary where an equivalent exists, for example invalid_api_key or rate_limit_exceeded. Null when Bayle could not identify the specific failure; the envelope is still valid and carries a generic message. The full list lives in Bayle’s error reference rather than being enumerated here.

string

nullable

Examples

400: a missing or invalid parameter, for example an unknown `type` on `GET /models`, no `input` on `POST /embeddings`, `n` above 1 or an unlisted `size` on `POST /images/generations`, a numeric or unlisted `duration` on the video endpoints, or no `queue_id`

{
  "error": {
    "message": "Bayle could not process this request because one or more parameters are invalid.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request"
  }
}

404: a `model` that does not exist

{
  "error": {
    "message": "The upstream model provider could not complete this request. Please try again.",
    "type": "api_error",
    "param": null,
    "code": null
  }
}

400: `POST /video/retrieve` or `POST /video/complete` with a `queue_id` that matches no job

{
  "error": {
    "message": "Bayle could not find a request matching the given request ID.",
    "type": "invalid_request_error",
    "param": "request_id",
    "code": "request_id_not_found"
  }
}

402: the key's balance is exhausted

{
  "error": {
    "message": "Your Bayle account does not have enough balance to complete this request.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_quota"
  }
}

422: a prompt the content policy does not permit

{
  "error": {
    "message": "Bayle's content policy does not permit this prompt.",
    "type": "invalid_request_error",
    "param": null,
    "code": "content_policy_violation"
  }
}

429: too many requests

{
  "error": {
    "message": "You have exceeded the rate limit for Bayle's API.",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

500: the model could not complete the request, for example an embedding `dimensions` the model cannot produce

{
  "error": {
    "message": "Bayle could not complete inference for this request.",
    "type": "api_error",
    "param": null,
    "code": "inference_failed"
  }
}

504: an image generation still running after four minutes

{
  "error": {
    "message": "This request took too long to complete on Bayle and was timed out. For long-running requests, use streaming.",
    "type": "api_error",
    "param": null,
    "code": "request_timeout"
  }
}

Headers

Content-Language

string

Allowed values: en pt-BR

Confirms which of the two supported locales, en or pt-BR, this response was rendered in, so a caller can detect it without reading the message text. Present on every response, success and error alike. On a chat completions stream it is committed together with the initial 200, so it appears whichever way the stream ends.