v1

latestOpenAPI 3.1.0Apache 2.02026-07-264001921002.3 KB

Async Jobs

Create async image generation

Submits an image generation request for asynchronous execution. Returns a job ID immediately with HTTP 202. Poll the corresponding GET endpoint with the job ID to retrieve the result. Streaming is not supported for async requests.

post/v1/async/images/generations

Headers

x-bf-async-job-result-ttlinteger

Time-to-live in seconds for the job result after completion. Defaults to 3600 (1 hour). After expiry, the job result is automatically cleaned up.

x-bf-async-webhookstring

Name of a registered webhook endpoint to notify when this job reaches a terminal state (completed or failed). The endpoint must already exist and be enabled; otherwise the submission is rejected with HTTP 400. If the endpoint is not subscribed to the resulting event, the job still completes normally but no delivery is enqueued. When omitted, no webhook is sent for the job and results are retrieved by polling. See the Webhooks management API to register endpoints.

Request body

modelstring required

Model identifier in format provider/model

promptstring required

Text prompt to generate image

ninteger

Number of images to generate

size'256x256' | '512x512' | '1024x1024' | '1792x1024' | '1024x1792' | '1536x1024' | '1024x1536' | 'auto'

Size of the generated image

Quality of the generated image

style'natural' | 'vivid'

Style of the generated image

response_format'url' | 'b64_json'

Format of the response.

background'transparent' | 'opaque' | 'auto'

Background type for the image

moderation'low' | 'auto'

Content moderation level

partial_imagesinteger

Number of partial images to generate

output_compressioninteger

Compression level (0-100%)

output_format'png' | 'webp' | 'jpeg'

Output image format

userstring

User identifier for tracking

seedinteger

Seed for reproducible image generation

negative_promptstring

Negative prompt to guide what to avoid in generation

num_inference_stepsinteger

Number of inference steps for generation

streamboolean

Whether to stream the response. When true, images are sent as SSE. When streaming, providers may return base64 chunks (b64_json) and/or URLs (url) depending on provider and configuration.

Response

Job accepted for processing

idstring required

Unique identifier for the async job

status'pending' | 'processing' | 'completed' | 'failed' required

The status of an async job

expires_atstring date-time

When the job result expires and will be cleaned up

created_atstring date-time required

When the job was created

completed_atstring date-time

When the job completed (successfully or with failure)

status_codeinteger

HTTP status code of the completed operation

{"stackTrail":"components:schemas:AsyncJobResponse:properties:result","oasType":"schema","type":"unknown","description":"The result of the completed operation (shape depends on the request type)"}