Create async image edit

Submits an image edit 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/edits

Error

A valid request URL is required to generate request examples

202

{
  "id": "<string>",
  "status": "pending",
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "status_code": 123,
  "result": "<unknown>",
  "error": {
    "event_id": "<string>",
    "type": "<string>",
    "is_bifrost_error": true,
    "status_code": 123,
    "error": {
      "type": "<string>",
      "code": "<string>",
      "message": "<string>",
      "param": "<string>",
      "event_id": "<string>"
    },
    "extra_fields": {
      "provider": "openai",
      "model_requested": "<string>",
      "request_type": "<string>"
    }
  }
}

Authorizations

BearerAuthBasicAuthVirtualKeyAuthApiKeyAuth

Authorization · string · header · required

Bearer token authentication. Use your provider API key or Bifrost authentication token. Virtual keys (prefixed with sk-bf-) can also be passed here.

Headers

x-bf-async-job-result-ttl · integer · default: 3600

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-webhook · string

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.

Body

application/jsonmultipart/form-data

JSON encoding of an image edit. Sources are supplied as an images array, the same nested form /v1/videos/edits uses for its source video. Unrecognised top-level fields are forwarded to the provider as extra params with their JSON types intact, which is what a model's nested tuning object needs (e.g. Runware's settings and providerSettings). To upload the image as a file, post multipart/form-data instead - see ImageEditMultipartRequest.

model · string · required

Model identifier in format provider/model

images · (string | object)[] · required

Source images. Entries carrying neither a URL nor bytes are dropped; a request left with no usable image is rejected. Providers treat the first image as the primary one (Runware's seed image, Bedrock's style-transfer base), so the order is part of the contract. Only the reference-image models accept more than one; elsewhere images after the first are dropped.

One source image, either as a bare string - the form input_images takes on /v1/images/generations - or as an object naming which arm it fills. Providers that cannot accept a given form reject it.

prompt · string

Text prompt describing the edit. Required except for the operation types that are driven purely by the input image: background_removal, erase_object, upscale, upscale_fast, mask, segmentation, vectorize and controlnet_preprocess.

mask · string<byte>

Optional base64-encoded mask image for inpainting (transparent areas indicate regions to edit). Dropped for models that declare no mask input.

type · enum<string>

Type of edit operation. Support varies by provider; unsupported values are dropped and the request runs as a standard edit.

Available options: inpainting, outpainting, background_removal, remove_background, remove_bg, erase_object, recolor, search_replace, control_sketch, control_structure, style_guide, style_transfer, upscale, upscale_fast, upscale_creative, upscale_conservative, mask, segmentation, vectorize, controlnet_preprocess, controlnet, preprocess

upscale_factor · integer

Multiply each dimension by this factor. type: "upscale" only; mutually exclusive with target_megapixels.

target_megapixels · integer

Target output size in megapixels. type: "upscale" only; mutually exclusive with upscale_factor.

n · integer

Number of images to generate

Required range: 1 <= x <= 10

size · enum<string>

Size of the output image

Available options: 256x256, 512x512, 1024x1024, 1536x1024, 1024x1536, auto

response_format · enum<string> · default: url

Format of the response. data_uri is supported by providers that return an inline data URI (e.g. Runware).

Available options: url, b64_json, data_uri

stream · boolean · default: false

When true, stream the response via Server-Sent Events

background · enum<string>

Background type for the image

Available options: transparent, opaque, auto

input_fidelity · enum<string>

How closely to follow the original image

Available options: low, high

partial_images · integer

Number of partial images to generate when streaming

Required range: 0 <= x <= 3

quality · enum<string>

Quality of the output image

Available options: auto, high, medium, low, standard

output_format · enum<string>

Output image format. svg applies to vectorize operations

Available options: png, webp, jpeg, tiff, svg

num_inference_steps · integer

Number of inference steps

seed · integer

Seed for reproducible editing

output_compression · integer

Compression level (0-100%)

Required range: 0 <= x <= 100

negative_prompt · string

What to avoid in the edit

user · string

User identifier for tracking

fallbacks · object[]

Fallback models to try if primary model fails

Show child attributes

Response

202

application/json

Job accepted for processing

Response returned when creating or polling an async job

id · string · required

Unique identifier for the async job

status · enum<string> · required

The status of an async job

Available options: pending, processing, completed, failed

created_at · string<date-time> · required

When the job was created

expires_at · string<date-time>

When the job result expires and will be cleaned up

completed_at · string<date-time>

When the job completed (successfully or with failure)

status_code · integer

HTTP status code of the completed operation

result · any

The result of the completed operation (shape depends on the request type)

error · object

Error response from Bifrost

Show child attributes