> ## Documentation Index > Fetch the complete documentation index at: https://docs.getbifrost.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi/openapi.json post /v1/async/images/edits openapi: 3.1.0 info: title: Bifrost API description: > Bifrost HTTP Transport API for AI model inference and gateway management. This API provides a unified interface for interacting with multiple AI providers including OpenAI, Anthropic, Bedrock, Gemini, and more through a single API, along with comprehensive management APIs for configuring and monitoring the gateway. ## API Structure ### Unified Inference API (`/v1/*`) The primary API using Bifrost's unified format. Model parameters use the format `provider/model` (e.g., `openai/gpt-4`, `anthropic/claude-3-opus`). ### Async Inference API (`/v1/async/*`) Submit inference requests for asynchronous execution. Returns a job ID immediately and allows polling for results. Supports all inference types except batches, files, and containers. ### Provider Integration APIs Native provider-format APIs for drop-in compatibility: - `/openai/*` - OpenAI-compatible API - `/anthropic/*` - Anthropic-compatible API - `/genai/*` - Google GenAI (Gemini) compatible API - `/bedrock/*` - AWS Bedrock compatible API - `/cohere/*` - Cohere compatible API ### Framework Integration APIs Multi-provider proxy endpoints for AI frameworks: - `/litellm/*` - LiteLLM proxy with all provider formats - `/langchain/*` - LangChain compatible endpoints - `/pydanticai/*` - PydanticAI compatible endpoints ### Management APIs (`/api/*`) APIs for managing and monitoring the Bifrost gateway: - `/api/config` - Configuration management - `/api/providers` - Provider and API key management - `/api/plugins` - Plugin management - `/api/governance/*` - Virtual keys, teams, customers, budgets, rate limits, routing rules, and pricing overrides - `/api/logs` - Log search and analytics - `/api/mcp/*` - MCP (Model Context Protocol) client management - `/api/session/*` - Authentication and session management - `/api/cache/*` - Cache management - `/health` - Health check endpoint ## Fallbacks Requests can include fallback models that will be tried if the primary model fails. version: 1.0.0 contact: name: Contact Us url: https://getmaxim.ai/bifrost license: name: Apache 2.0 url: https://opensource.org/licenses/Apache-2.0 servers: - url: '{baseUrl}' description: Your Bifrost instance variables: baseUrl: default: http://localhost:8080 description: >- Base URL of your Bifrost instance (e.g. https://bifrost.mycompany.com, or https://mycompany.com/bifrost when served under server.base_path) security: - BearerAuth: [] - BasicAuth: [] - ApiKeyAuth: [] tags: - name: Agent Gateway description: >- Agent registrations, A2A protocol calls, push callbacks, and operation history - name: Models description: Model listing and information - name: Chat Completions description: Chat-based text generation - name: Text Completions description: Text completion generation - name: Responses description: OpenAI Responses API compatible endpoints - name: OCR description: Optical character recognition for documents and images - name: Rerank description: Document reranking by relevance to a query - name: Decisions description: Structured decisions evaluated against annotated function-tool definitions - name: Embeddings description: Text embedding generation - name: Images description: Image generations, editing, and variations - name: Videos description: Video generation and management - name: Audio description: Speech synthesis and transcription - name: Count Tokens description: Token counting utilities - name: Batch description: Batch processing operations - name: Files description: File management operations - name: Containers description: Container management operations - name: Async Jobs description: Asynchronous job submission and retrieval endpoints - name: Realtime description: Realtime WebSocket and WebRTC endpoints - name: OpenAI Integration description: OpenAI-compatible API endpoints (/openai/*) - name: Azure Integration description: Azure OpenAI integration endpoints - name: Anthropic Integration description: Anthropic-compatible API endpoints (/anthropic/*) - name: GenAI Integration description: Google GenAI (Gemini) compatible API endpoints (/genai/*) - name: Bedrock Integration description: AWS Bedrock compatible API endpoints (/bedrock/*) - name: Cohere Integration description: Cohere compatible API endpoints (/cohere/*) - name: Typesafe Integration description: Typesafe compatible API endpoints (/typesafe/*) - name: LiteLLM Integration description: LiteLLM proxy endpoints with multi-provider support (/litellm/*) - name: LangChain Integration description: LangChain compatible endpoints with multi-provider support (/langchain/*) - name: PydanticAI Integration description: >- PydanticAI compatible endpoints with multi-provider support (/pydanticai/*) - name: Health description: Health check endpoints - name: Configuration description: Configuration management endpoints - name: Session description: Session and authentication endpoints - name: Providers description: Provider management endpoints - name: Plugins description: Plugin management endpoints - name: MCP description: Model Context Protocol endpoints - name: Governance description: Virtual keys, teams, and customers management - name: Routing description: Routing rules and complexity analyzer configuration - name: Logging description: Log search and management endpoints - name: Cache description: Cache management endpoints - name: Vault description: Vault secret management endpoints - name: Skills description: Skills Repository management, marketplace, and download endpoints - name: Audit Logs description: >- CADF-compliant audit log search, export, and signature verification endpoints - name: Webhooks description: Webhook endpoint management and signed async-job delivery history - name: Notifications description: >- Role-targeted dashboard notifications, delivered over the dashboard WebSocket - name: News Feeds description: >- RSS and Atom news sources shown in the News tab of the dashboard notification tray - name: Background Jobs description: >- Status, progress and cancellation of durable background jobs (cost recalculation, Warp log indexing, and others) - name: Warp description: >- Configuration for Warp, the dashboard agent that answers questions about the deployment's own telemetry - name: Relays description: >- Relays to non-LLM HTTP APIs - endpoint management, usage preview, Relay Logs and the /relay data plane paths: /v1/async/images/edits: post: tags: - Async Jobs summary: Create async image edit description: > 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. operationId: createAsyncImageEdit parameters: - $ref: '#/components/parameters/AsyncResultTTL' - $ref: '#/components/parameters/AsyncWebhookEndpoint' requestBody: required: true content: application/json: schema: type: object description: > 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`. required: - model - images properties: model: type: string description: Model identifier in format `provider/model` images: type: array items: description: > 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. oneOf: - type: string description: > Public URL, data URI, base64 payload, or provider-side asset ID. Equivalent to the object form's `url`. - type: object description: Exactly one of the two properties is expected. properties: url: type: string description: > Public URL, data URI, or provider-side asset ID, for providers whose upstream fetches the asset itself (e.g. Runware). Avoids round-tripping the asset through the gateway as base64. image: type: string format: byte description: Base64-encoded image bytes description: > 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. prompt: type: string description: > 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: type: string format: byte description: > Optional base64-encoded mask image for inpainting (transparent areas indicate regions to edit). Dropped for models that declare no mask input. type: type: string enum: - 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 description: > Type of edit operation. Support varies by provider; unsupported values are dropped and the request runs as a standard edit. upscale_factor: type: integer description: > Multiply each dimension by this factor. `type: "upscale"` only; mutually exclusive with `target_megapixels`. target_megapixels: type: integer description: > Target output size in megapixels. `type: "upscale"` only; mutually exclusive with `upscale_factor`. 'n': type: integer minimum: 1 maximum: 10 description: Number of images to generate size: type: string enum: - 256x256 - 512x512 - 1024x1024 - 1536x1024 - 1024x1536 - auto description: Size of the output image response_format: type: string enum: - url - b64_json - data_uri default: url description: > Format of the response. `data_uri` is supported by providers that return an inline data URI (e.g. Runware). stream: type: boolean default: false description: When true, stream the response via Server-Sent Events background: type: string enum: - transparent - opaque - auto description: Background type for the image input_fidelity: type: string enum: - low - high description: How closely to follow the original image partial_images: type: integer minimum: 0 maximum: 3 description: Number of partial images to generate when streaming quality: type: string enum: - auto - high - medium - low - standard description: Quality of the output image output_format: type: string enum: - png - webp - jpeg - tiff - svg description: Output image format. `svg` applies to vectorize operations num_inference_steps: type: integer description: Number of inference steps seed: type: integer description: Seed for reproducible editing output_compression: type: integer minimum: 0 maximum: 100 description: Compression level (0-100%) negative_prompt: type: string description: What to avoid in the edit user: type: string description: User identifier for tracking fallbacks: type: array items: $ref: '#/components/schemas/Fallback' description: Fallback models to try if primary model fails multipart/form-data: schema: type: object description: > Multipart encoding of an image edit, and the only encoding that can upload the image as a file. This is what the official OpenAI SDKs send unconditionally. Every value crosses the wire as a string, so provider-native extra params arrive as strings; post `application/json` instead when a provider expects them as numbers, booleans or nested objects - see `ImageEditRequest`. required: - model properties: model: type: string description: Model identifier in format `provider/model` prompt: type: string description: > 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`. image: type: string format: binary description: > Image file to edit. Use field name `image` for a single file or `image[]` for multiple files. Either `image` or `image_url` is required. image_url: type: string description: > Input image as a public URL or provider-side asset ID, for providers whose upstream fetches the asset itself (e.g. Runware). Use `image_url` for one or `image_url[]` for several; this avoids round-tripping the asset through the gateway as base64. Uploads keep their leading position, and providers treat the first image as the primary one. mask: type: string format: binary description: > Optional mask image for inpainting (transparent areas indicate regions to edit). Dropped for models that declare no mask input. type: type: string enum: - 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 description: > Type of edit operation. Support varies by provider; unsupported values are dropped and the request runs as a standard edit. upscale_factor: type: integer description: > Multiply each dimension by this factor. `type: "upscale"` only; mutually exclusive with `target_megapixels`. target_megapixels: type: integer description: > Target output size in megapixels. `type: "upscale"` only; mutually exclusive with `upscale_factor`. 'n': type: integer minimum: 1 maximum: 10 description: Number of images to generate size: type: string enum: - 256x256 - 512x512 - 1024x1024 - 1536x1024 - 1024x1536 - auto description: Size of the output image response_format: type: string enum: - url - b64_json - data_uri default: url description: > Format of the response. `data_uri` is supported by providers that return an inline data URI (e.g. Runware). stream: type: boolean default: false description: When true, stream the response via Server-Sent Events background: type: string enum: - transparent - opaque - auto description: Background type for the image input_fidelity: type: string enum: - low - high description: How closely to follow the original image partial_images: type: integer minimum: 0 maximum: 3 description: Number of partial images to generate when streaming quality: type: string enum: - auto - high - medium - low - standard description: Quality of the output image output_format: type: string enum: - png - webp - jpeg - tiff - svg description: Output image format. `svg` applies to vectorize operations num_inference_steps: type: integer description: Number of inference steps seed: type: integer description: Seed for reproducible editing output_compression: type: integer minimum: 0 maximum: 100 description: Compression level (0-100%) negative_prompt: type: string description: What to avoid in the edit user: type: string description: User identifier for tracking fallbacks: type: array items: $ref: '#/components/schemas/Fallback' description: Fallback models to try if primary model fails responses: '202': description: Job accepted for processing content: application/json: schema: $ref: '#/components/schemas/AsyncJobResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BifrostError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/BifrostError' security: - BearerAuth: [] - VirtualKeyAuth: [] - ApiKeyAuth: [] components: parameters: AsyncResultTTL: name: x-bf-async-job-result-ttl in: header required: false description: > 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. schema: type: integer default: 3600 AsyncWebhookEndpoint: name: x-bf-async-webhook in: header required: false description: > 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. schema: type: string schemas: Fallback: type: object description: Fallback model configuration required: - provider - model properties: provider: $ref: '#/components/schemas/ModelProvider' model: type: string description: Model name AsyncJobResponse: type: object description: Response returned when creating or polling an async job required: - id - status - created_at properties: id: type: string description: Unique identifier for the async job status: $ref: '#/components/schemas/AsyncJobStatus' expires_at: type: string format: date-time description: When the job result expires and will be cleaned up created_at: type: string format: date-time description: When the job was created completed_at: type: string format: date-time description: When the job completed (successfully or with failure) status_code: type: integer description: HTTP status code of the completed operation result: description: >- The result of the completed operation (shape depends on the request type) error: $ref: '#/components/schemas/BifrostError' BifrostError: type: object description: Error response from Bifrost properties: event_id: type: string type: type: string is_bifrost_error: type: boolean status_code: type: integer error: $ref: '#/components/schemas/ErrorField' extra_fields: $ref: '#/components/schemas/BifrostErrorExtraFields' ModelProvider: type: string description: AI model provider identifier enum: - anthropic - azure - bedrock - bedrock_mantle - sagemaker - cerebras - cohere - deepseek - gemini - groq - mistral - ollama - opencode-go - opencode-zen - openai - parasail - perplexity - sgl - vertex - openrouter - elevenlabs - huggingface - nebius - xai - replicate - vllm - runway - runware - fireworks - sarvam - wafer - databricks - cloudflare - typesafe - minimax - byteplus AsyncJobStatus: type: string description: The status of an async job enum: - pending - processing - completed - failed ErrorField: type: object properties: type: type: string code: type: string message: type: string param: type: string event_id: type: string BifrostErrorExtraFields: type: object properties: routing_info: $ref: '#/components/schemas/RoutingInfo' provider: $ref: '#/components/schemas/ModelProvider' deprecated: true description: 'Deprecated: use routing_info.provider.' original_model_requested: type: string deprecated: true description: >- Deprecated: use routing_info.primary_model when routing_info.is_fallback is true, otherwise routing_info.model. For the model the caller asked for, read routing_info.requested_model. resolved_model_used: type: string deprecated: true description: >- Deprecated: use routing_info.resolved_key_alias.model_id when an alias matched, otherwise routing_info.model. request_type: type: string mcp_request_type: type: string a2a_request_type: type: string description: Agent Gateway operation, for A2A errors a2a_agent_name: type: string error_type: type: string description: >- Normalized, low-cardinality classification of why the request failed, declared by whichever component refused it. Prefixed by fault domain (caller_, policy_, provider_, bifrost_). Absent on failures that were not classified at source. retry_after_ms: type: integer format: int64 minimum: 1000 maximum: 300000 description: >- The provider's hint for how long to wait before retrying, in milliseconds, read from its retry-after-ms or Retry-After header or its google.rpc.RetryInfo error detail, and clamped to between 1000 and 300000. Absent when the provider gave no explicit hint. raw_request: description: Raw provider request, when raw request capture is enabled raw_response: description: Raw provider response, when raw response capture is enabled converted_request_type: type: string dropped_compat_plugin_params: type: array items: type: string latency: type: integer format: int64 description: Latency in milliseconds key_statuses: type: array description: >- Per-key results, for requests that ran on every key such as listing models items: type: object properties: key_id: type: string status: type: string enum: - success - list_models_failed provider: $ref: '#/components/schemas/ModelProvider' error: $ref: '#/components/schemas/BifrostError' mcp_auth_required: type: object description: >- Set when a per-user MCP tool needs the caller to complete an inline auth flow properties: kind: type: string mcp_client_id: type: string mcp_client_name: type: string message: type: string authorize_url: type: string session_id: type: string subject_token_missing: type: boolean description: >- token_exchange only. True when there was nothing to exchange, including when the caller's Bifrost sign-in has expired; message says which exchange_error: type: string description: >- token_exchange only. The identity provider's error code and description when it refused the exchange billed_usage: $ref: '#/components/schemas/BifrostLLMUsage' description: >- Usage the provider reported and billed even though the request failed RoutingInfo: type: object description: >- Which provider, model and key handled the attempt that produced this response or error, and what the caller asked for. Also sent as x-bifrost-routing-info-* response headers. properties: provider: $ref: '#/components/schemas/ModelProvider' description: Provider that ran the attempt model: type: string description: Model sent to that provider key: type: string description: Name of the stored key used, never its ID or secret resolved_key_alias: $ref: '#/components/schemas/ResolvedKeyAlias' is_fallback: type: boolean description: >- True when a fallback served the request or returned the error. Omitted when false. primary_provider: $ref: '#/components/schemas/ModelProvider' description: The primary attempt's provider. Set only when a fallback ran. primary_model: type: string description: The primary attempt's model. Set only when a fallback ran. requested_provider: $ref: '#/components/schemas/ModelProvider' description: >- Provider the caller asked for, before routing rules, load balancing or session affinity changed it. Omitted when the caller sent a bare model. requested_model: type: string description: Model the caller asked for, before anything changed it server_side_fallback_model: type: string description: Model that answered when Anthropic switched models inside one call BifrostLLMUsage: type: object description: Token usage information properties: prompt_tokens: type: integer description: > Total input tokens including any prompt-cache tokens (read + write). Subtract prompt_tokens_details.cached_read_tokens and prompt_tokens_details.cached_write_tokens to get the non-cached portion. prompt_tokens_details: $ref: '#/components/schemas/ChatPromptTokensDetails' completion_tokens: type: integer description: Number of output/completion tokens generated. completion_tokens_details: $ref: '#/components/schemas/ChatCompletionTokensDetails' total_tokens: type: integer tool_usage: type: object description: | Counts of provider-hosted (server-side) tool calls billed per call. properties: web_search: type: object properties: num_requests: type: integer description: Number of billable web search calls. cost: $ref: '#/components/schemas/BifrostCost' ResolvedKeyAlias: type: object description: Set only when the requested model matched a model alias on the key required: - model_id properties: model_id: type: string description: Model ID sent to the provider model_name: type: string description: Canonical model name, used for pricing and logs model_family: type: string description: Resolved model family ChatPromptTokensDetails: type: object properties: text_tokens: type: integer audio_tokens: type: integer image_tokens: type: integer cached_read_tokens: type: integer description: > Tokens served from the prompt cache (cache hit). These tokens are already included in prompt_tokens and are billed at the reduced cache-read rate. Populated for all providers that support prompt caching (Anthropic, Bedrock, OpenAI, Gemini, xAI, etc.). cached_write_tokens: type: integer description: > Tokens written to the prompt cache on this request (cache creation / write). These tokens are already included in prompt_tokens and are billed at the cache-creation rate. Populated for providers that separately report cache write tokens (Anthropic, Bedrock). ChatCompletionTokensDetails: type: object properties: text_tokens: type: integer accepted_prediction_tokens: type: integer audio_tokens: type: integer citation_tokens: type: integer num_search_queries: type: integer deprecated: true description: >- Deprecated, use tool_usage.web_search.num_requests. Will be removed in 3.0.0. reasoning_tokens: type: integer image_tokens: type: integer rejected_prediction_tokens: type: integer BifrostCost: type: object description: Cost breakdown for the request properties: input_tokens_cost: type: number output_tokens_cost: type: number reasoning_tokens_cost: type: number description: Cost for reasoning/thinking tokens (reasoning models) citation_tokens_cost: type: number description: Cost for citation tokens search_queries_cost: type: number description: Cost for web search queries request_cost: type: number total_cost: type: number securitySchemes: BearerAuth: type: http scheme: bearer description: > Bearer token authentication. Use your provider API key or Bifrost authentication token. Virtual keys (prefixed with `sk-bf-`) can also be passed here. BasicAuth: type: http scheme: basic description: > Basic authentication using the Bifrost admin username and password (`auth_config.admin_username` / `auth_config.admin_password`). Accepted on management APIs (`/api/*`, `/metrics`, `/ws`) only - the inference middleware never validates Basic credentials. ApiKeyAuth: type: apiKey in: header name: x-api-key description: | API key authentication via the `x-api-key` header. Virtual keys (prefixed with `sk-bf-`) can also be passed here. VirtualKeyAuth: type: apiKey in: header name: x-bf-vk description: > Bifrost Virtual Key for governance, routing, and access control. Supported on all inference endpoints (`/v1/*`, `/openai/*`, `/anthropic/*`, `/bedrock/*`, `/cohere/*`, `/genai/*`, `/langchain/*`, `/litellm/*`, `/pydanticai/*`, `/mcp`), not on management APIs (`/api/*`) - with the single exception of the self-service `GET /api/governance/virtual-keys/quota`, where the virtual key is the credential. Example: `sk-bf-*` prefixed keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.