Queue a video generation job

POST

/video/queue

const url = 'https://api.bayle.ai/video/queue';
const options = {
  method: 'POST',
  headers: {
    'Accept-Language': 'pt-BR',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"model":"seedance-2-0-mini-text-to-video-basic","prompt":"A paper boat drifts down a rain-soaked city street at dusk, neon reflections rippling in the water","negative_prompt":"blurry, low quality, watermark, text","duration":"5s","aspect_ratio":"16:9","resolution":"720p","audio":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.bayle.ai/video/queue \
  --header 'Accept-Language: pt-BR' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "model": "seedance-2-0-mini-text-to-video-basic", "prompt": "A paper boat drifts down a rain-soaked city street at dusk, neon reflections rippling in the water", "negative_prompt": "blurry, low quality, watermark, text", "duration": "5s", "aspect_ratio": "16:9", "resolution": "720p", "audio": true }'

Starts a video generation job and returns a queue_id to poll. Video generation is asynchronous: this call queues the work, POST /video/retrieve reports progress and ultimately returns the video, and POST /video/complete releases the stored media.

model and prompt are required. Supply image_url for image-to-video generation. Some models require a consent attestation before a face-bearing generation can be queued; see the 409 response below. Fields Bayle does not name below are forwarded as sent.

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

application/json

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

object

model

required

The video model to use, as returned by GET /models.

string

prompt

required

What to generate.

string

image_url

A starting image for image-to-video generation, as a data: URI or a public https URL.

string

end_image_url

The final frame for an image-to-video generation, supplied the same way as image_url — a data: URI or a public https URL. Optional.

string

negative_prompt

Content to steer the generation away from.

string

duration

Requested clip length, as a string of whole seconds followed by s, for example "5s". A bare number such as 5 is rejected. The accepted values differ by model: each video model lists them under model_spec.constraints.durations in GET /models?type=video, and a value that model does not list is rejected.

string

aspect_ratio

For example "16:9". Each video model lists the values it takes under model_spec.constraints.aspect_ratios; an image-to-video model may list none, taking the shape of its starting image instead.

string

resolution

For example "720p". Each video model lists the values it takes under model_spec.constraints.resolutions.

string

audio

Whether the generation includes audio.

boolean

consents

The consent attestation, added when resubmitting after a 409. Keyed by model family.

object

seedance

All three fields must be literally true.

object

confirmed_terms_and_privacy

boolean

confirmed_legal_right

boolean

confirmed_screening_acknowledged

boolean

key

additional properties

any

key

additional properties

any

key

additional properties

any

Examples

Text-to-video

{
  "model": "seedance-2-0-mini-text-to-video-basic",
  "prompt": "A paper boat drifts down a rain-soaked city street at dusk, neon reflections rippling in the water",
  "negative_prompt": "blurry, low quality, watermark, text",
  "duration": "5s",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "audio": true
}

Image-to-video, with a start and an end frame

{
  "model": "seedance-2-0-mini-image-to-video-basic",
  "prompt": "The person in the photo waves at the camera and smiles",
  "image_url": "https://example.com/portrait.jpg",
  "end_image_url": "https://example.com/portrait-smiling.jpg",
  "negative_prompt": "distorted face, extra fingers",
  "duration": "5s",
  "resolution": "480p",
  "audio": true
}

Resubmitting after a 409, with the consent attestation

{
  "model": "seedance-2-0-mini-image-to-video-basic",
  "prompt": "The person in the photo waves at the camera and smiles",
  "image_url": "https://example.com/portrait.jpg",
  "duration": "5s",
  "resolution": "480p",
  "audio": true,
  "consents": {
    "seedance": {
      "confirmed_terms_and_privacy": true,
      "confirmed_legal_right": true,
      "confirmed_screening_acknowledged": true
    }
  }
}

Responses

200

The job was queued. Poll POST /video/retrieve with the returned queue_id to follow it.

application/json

object

queue_id

Identifies the job. Pass it to POST /video/retrieve and POST /video/complete.

string

download_url

Present for some models. A pre-signed URL your own client fetches directly. It needs no credential and does not pass back through Bayle.

string

key

additional properties

any

Examples

Queued

{
  "queue_id": "01a07f13-21eb-712a-92bf-b437f83c5b47"
}

Queued, for a model that returns a download URL

{
  "queue_id": "01a07f13-21eb-712a-92bf-b437f83c5b47",
  "download_url": "https://example.com/downloads/01a07f13-21eb-712a-92bf-b437f83c5b47"
}

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.

application/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

409

This model requires a consent attestation before a face-bearing generation can be queued. Nothing is charged for this response.

To proceed, resend the identical request body to this same endpoint with a consents object added, whose three boolean fields must each be literally true. There is no consent token to carry, no version for you to supply, and no separate endpoint for the retry: it is the same POST /video/queue call with one more field.

The response body names the flow, the media roles requiring confirmation, and the policy text to show the person whose likeness appears in the media.

application/json

The body of POST /video/queue’s 409 consent rejection.

object

error

required

object

code

required

The discriminator identifying this as a consent rejection.

string

Allowed values: needs_consent

message

required

A human-readable description of what is required, in the negotiated locale.

string

consent_flow

required

Identifies which consent flow this model requires.

string

face_media_roles

required

Which media roles in the request require confirmation.

Array<string>

consent

required

object

consent_version

required

The version of the policy being attested to.

string

policy_text

required

The policy text to present to the person whose likeness appears in the media, in the negotiated locale.

string

docs_url

required

Where to read more about this flow. A fixed Bayle documentation address (https://docs.bayle.ai) that does not vary by model or error code.

string

Example

{
  "error": {
    "code": "needs_consent",
    "message": "This model requires consent confirmation before generating a face-bearing video."
  },
  "consent_flow": "seedance",
  "face_media_roles": [
    "image"
  ],
  "consent": {
    "consent_version": "2026-01-01",
    "policy_text": "By proceeding you confirm you have the right to use this likeness in the generated video."
  },
  "docs_url": "https://docs.bayle.ai"
}

Headers

Content-Language

string

Allowed values: en pt-BR

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.

application/json

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

object

error

required

object

message

required

string

type

required

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

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

Queue a video generation job

Authorizations

Parameters

Header Parameters

Example

Request Bodyrequired

Examples

Responses

200

Examples

Headers

401

Examples

Headers

409

Example

Headers

default

Examples

Headers

Request Body^required