> ## Documentation Index > Fetch the complete documentation index at: https://bifrost-dev.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Edit an image > Edits an image using a text prompt and optional mask. Accepts either `application/json` (sources as URLs or base64 under `images`) or `multipart/form-data` (to upload the image as `image` or `image[]`). Requires at least `model`, one image, and `prompt` - the latter except for the operation types driven purely by the input image, e.g. `background_removal`. Only the JSON body preserves the types of provider-native extra params; multipart carries every value as a string. ## OpenAPI ````yaml /openapi/openapi.json post /v1/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) security: - BearerAuth: [] - BasicAuth: [] - ApiKeyAuth: [] tags: - 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: 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: 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 paths: /v1/images/edits: post: tags: - Images summary: Edit an image description: > Edits an image using a text prompt and optional mask. Accepts either `application/json` (sources as URLs or base64 under `images`) or `multipart/form-data` (to upload the image as `image` or `image[]`). Requires at least `model`, one image, and `prompt` - the latter except for the operation types driven purely by the input image, e.g. `background_removal`. Only the JSON body preserves the types of provider-native extra params; multipart carries every value as a string. operationId: imageEdit 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: '200': description: > Successful response. Returns JSON for non-streaming requests, or Server-Sent Events (SSE) stream when `stream=true`. When streaming, events are sent with the following event types: - `image_edit.partial_image`: Intermediate image chunks with base64-encoded image data - `image_edit.completed`: Final event for each image with usage information - `error`: Error events with error details content: application/json: schema: type: object properties: id: type: string description: Unique identifier for the generation request created: type: integer format: int64 description: Unix timestamp when the image was created model: type: string description: Model used for generation data: type: array items: type: object properties: id: type: string description: > Provider-side asset identifier, when one is assigned. Providers that accept their own asset IDs as inputs (e.g. Runware) allow this to be fed straight into a follow-up task. url: type: string format: uri description: URL of the generated image b64_json: type: string description: Base64-encoded image data revised_prompt: type: string description: Revised prompt used for generation index: type: integer description: Index of this image detections: type: array items: type: object description: >- A region located by a masking model, in absolute input-image pixels properties: x_min: type: integer y_min: type: integer x_max: type: integer y_max: type: integer description: >- Regions located by a masking or segmentation operation description: Array of generated images background: type: string description: Background type for the image output_format: type: string enum: - png - webp - jpeg description: Output image format quality: type: string description: Quality of the generated image size: type: string enum: - 256x256 - 512x512 - 1024x1024 - 1792x1024 - 1024x1792 - 1536x1024 - 1024x1536 - auto description: Size of the generated image usage: type: object properties: input_tokens: type: integer description: Number of input tokens input_tokens_details: type: object properties: image_tokens: type: integer description: Tokens used for images text_tokens: type: integer description: Tokens used for text total_tokens: type: integer description: Total tokens used output_tokens: type: integer description: Number of output tokens output_tokens_details: type: object properties: image_tokens: type: integer description: Tokens used for images text_tokens: type: integer description: Tokens used for text extra_fields: $ref: '#/components/schemas/BifrostResponseExtraFields' text/event-stream: schema: type: object description: | Streaming response chunk for image edit. Sent via Server-Sent Events (SSE) when `stream=true`. properties: id: type: string description: Request identifier type: type: string enum: - image_edit.partial_image - image_edit.completed - error description: Type of stream event partial_image_index: type: integer description: Index of the partial image chunk sequence_number: type: integer description: Sequence number for event ordering within the stream b64_json: type: string description: Base64-encoded chunk of image data; optional url: type: string format: uri description: Optional public URL to the image chunk created_at: type: integer format: int64 description: Timestamp when chunk was created size: type: string description: Size of the image quality: type: string description: Quality setting used background: type: string description: Background type used output_format: type: string enum: - png - webp - jpeg description: Output format used revised_prompt: type: string description: Revised prompt usage: type: object properties: input_tokens: type: integer description: Number of input tokens input_tokens_details: type: object properties: image_tokens: type: integer description: Tokens used for images text_tokens: type: integer description: Tokens used for text total_tokens: type: integer description: Total tokens used output_tokens: type: integer description: Number of output tokens output_tokens_details: type: object properties: image_tokens: type: integer description: Tokens used for images text_tokens: type: integer description: Tokens used for text description: Token usage error: $ref: '#/components/schemas/BifrostError' description: Error information if edit failed extra_fields: $ref: '#/components/schemas/BifrostResponseExtraFields' '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: [] - BasicAuth: [] - VirtualKeyAuth: [] - ApiKeyAuth: [] components: schemas: Fallback: type: object description: Fallback model configuration required: - provider - model properties: provider: $ref: '#/components/schemas/ModelProvider' model: type: string description: Model name BifrostResponseExtraFields: type: object description: Additional fields included in responses properties: request_type: type: string description: Type of request that was made provider: $ref: '#/components/schemas/ModelProvider' model_requested: type: string description: The model that was requested model_deployment: type: string description: The actual model deployment used latency: type: integer format: int64 description: Request latency in milliseconds chunk_index: type: integer description: Index of the chunk for streaming responses raw_request: type: object description: Raw request if enabled raw_response: type: object description: Raw response if enabled cache_debug: $ref: '#/components/schemas/BifrostCacheDebug' 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: - openai - azure - anthropic - bedrock - cohere - vertex - vllm - mistral - ollama - groq - sgl - parasail - perplexity - replicate - cerebras - deepseek - gemini - openrouter - elevenlabs - huggingface - nebius - xai - runway - fireworks BifrostCacheDebug: type: object properties: cache_hit: type: boolean cache_id: type: string hit_type: type: string requested_provider: type: string requested_model: type: string provider_used: type: string model_used: type: string input_tokens: type: integer threshold: type: number similarity: type: number ErrorField: type: object properties: type: type: string code: type: string message: type: string param: type: string event_id: type: string BifrostErrorExtraFields: type: object properties: provider: $ref: '#/components/schemas/ModelProvider' model_requested: type: string request_type: type: string 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 username and password. 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/*`). Example: `sk-bf-*` prefixed keys. ````