A valid request URL is required to generate request examples{
"id": "<string>",
"created": 123,
"model": "<string>",
"data": [
{
"id": "<string>",
"url": "<string>",
"b64_json": "<string>",
"revised_prompt": "<string>",
"index": 123,
"detections": [
{
"x_min": 123,
"y_min": 123,
"x_max": 123,
"y_max": 123
}
]
}
],
"background": "<string>",
"output_format": "png",
"quality": "<string>",
"size": "256x256",
"usage": {
"input_tokens": 123,
"input_tokens_details": {
"image_tokens": 123,
"text_tokens": 123
},
"total_tokens": 123,
"output_tokens": 123,
"output_tokens_details": {
"image_tokens": 123,
"text_tokens": 123
}
},
"extra_fields": {
"request_type": "<string>",
"pricing_request_type": "<string>",
"routing_info": {
"provider": "anthropic",
"model": "<string>",
"key": "<string>",
"resolved_key_alias": {
"model_id": "<string>",
"model_name": "<string>",
"model_family": "<string>"
},
"is_fallback": true,
"primary_provider": "anthropic",
"primary_model": "<string>",
"requested_provider": "anthropic",
"requested_model": "<string>",
"server_side_fallback_model": "<string>"
},
"provider": "anthropic",
"original_model_requested": "<string>",
"resolved_model_used": "<string>",
"latency": 123,
"upstream_latency": 123,
"chunk_index": 123,
"raw_request": "<unknown>",
"raw_response": "<unknown>",
"cache_debug": {
"cache_hit": true,
"cache_id": "<string>",
"hit_type": "<string>",
"requested_provider": "<string>",
"requested_model": "<string>",
"provider_used": "<string>",
"model_used": "<string>",
"input_tokens": 123,
"threshold": 123,
"similarity": 123,
"cache_hit_latency": 123
},
"routing_metadata": {
"calls": [
{
"request_type": "<string>",
"provider_used": "<string>",
"model_used": "<string>",
"input_tokens": 123,
"output_tokens": 123,
"count_toward_budgets": true
}
]
},
"guardrail_debug": {
"judge_calls": [
{
"phase": "<string>",
"rule_id": 123,
"rule_name": "<string>",
"guardrail_name": "<string>",
"guardrail_provider": "<string>",
"action": "<string>",
"reason": "<string>",
"judge_provider": "<string>",
"judge_model": "<string>",
"judge_request_type": "<string>",
"prompt_tokens": 123,
"prompt_tokens_details": {},
"completion_tokens": 123,
"completion_tokens_details": {},
"total_tokens": 123
}
],
"detections": [
{
"phase": "<string>",
"rule_id": 123,
"rule_name": "<string>",
"guardrail_name": "<string>",
"guardrail_provider": "<string>",
"reason": "<string>",
"assessments": [
"<string>"
],
"action": "detect",
"enforced": true
}
]
},
"parse_errors": [
{
"code": "<string>",
"message": "<string>",
"param": "<string>",
"line": 123
}
],
"converted_request_type": "<string>",
"dropped_compat_plugin_params": [
"<string>"
],
"dropped_unsupported_tools": [
"<string>"
],
"provider_response_headers": {},
"passthrough_path": "<string>"
}
}{
"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": {
"routing_info": {
"provider": "anthropic",
"model": "<string>",
"key": "<string>",
"resolved_key_alias": {
"model_id": "<string>",
"model_name": "<string>",
"model_family": "<string>"
},
"is_fallback": true,
"primary_provider": "anthropic",
"primary_model": "<string>",
"requested_provider": "anthropic",
"requested_model": "<string>",
"server_side_fallback_model": "<string>"
},
"provider": "anthropic",
"original_model_requested": "<string>",
"resolved_model_used": "<string>",
"request_type": "<string>",
"mcp_request_type": "<string>",
"a2a_request_type": "<string>",
"a2a_agent_name": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500,
"raw_request": "<unknown>",
"raw_response": "<unknown>",
"converted_request_type": "<string>",
"dropped_compat_plugin_params": [
"<string>"
],
"latency": 123,
"key_statuses": [
{
"key_id": "<string>",
"status": "success",
"provider": "anthropic",
"error": "<unknown>"
}
],
"fallback_attempts": [
{
"provider": "anthropic",
"model": "<string>",
"status_code": 123,
"type": "<string>",
"message": "<string>",
"skipped": true
}
],
"mcp_auth_required": {
"kind": "<string>",
"mcp_client_id": "<string>",
"mcp_client_name": "<string>",
"message": "<string>",
"authorize_url": "<string>",
"session_id": "<string>",
"subject_token_missing": true,
"exchange_error": "<string>"
},
"billed_usage": {
"prompt_tokens": 123,
"prompt_tokens_details": {
"text_tokens": 123,
"audio_tokens": 123,
"image_tokens": 123,
"cached_read_tokens": 123,
"cached_write_tokens": 123
},
"completion_tokens": 123,
"completion_tokens_details": {
"text_tokens": 123,
"accepted_prediction_tokens": 123,
"audio_tokens": 123,
"citation_tokens": 123,
"num_search_queries": 123,
"reasoning_tokens": 123,
"image_tokens": 123,
"rejected_prediction_tokens": 123
},
"total_tokens": 123,
"tool_usage": {
"web_search": {
"num_requests": 123
}
},
"cost": {
"input_tokens_cost": 123,
"output_tokens_cost": 123,
"reasoning_tokens_cost": 123,
"citation_tokens_cost": 123,
"search_queries_cost": 123,
"request_cost": 123,
"total_cost": 123
}
}
}
}{
"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": {
"routing_info": {
"provider": "anthropic",
"model": "<string>",
"key": "<string>",
"resolved_key_alias": {
"model_id": "<string>",
"model_name": "<string>",
"model_family": "<string>"
},
"is_fallback": true,
"primary_provider": "anthropic",
"primary_model": "<string>",
"requested_provider": "anthropic",
"requested_model": "<string>",
"server_side_fallback_model": "<string>"
},
"provider": "anthropic",
"original_model_requested": "<string>",
"resolved_model_used": "<string>",
"request_type": "<string>",
"mcp_request_type": "<string>",
"a2a_request_type": "<string>",
"a2a_agent_name": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500,
"raw_request": "<unknown>",
"raw_response": "<unknown>",
"converted_request_type": "<string>",
"dropped_compat_plugin_params": [
"<string>"
],
"latency": 123,
"key_statuses": [
{
"key_id": "<string>",
"status": "success",
"provider": "anthropic",
"error": "<unknown>"
}
],
"fallback_attempts": [
{
"provider": "anthropic",
"model": "<string>",
"status_code": 123,
"type": "<string>",
"message": "<string>",
"skipped": true
}
],
"mcp_auth_required": {
"kind": "<string>",
"mcp_client_id": "<string>",
"mcp_client_name": "<string>",
"message": "<string>",
"authorize_url": "<string>",
"session_id": "<string>",
"subject_token_missing": true,
"exchange_error": "<string>"
},
"billed_usage": {
"prompt_tokens": 123,
"prompt_tokens_details": {
"text_tokens": 123,
"audio_tokens": 123,
"image_tokens": 123,
"cached_read_tokens": 123,
"cached_write_tokens": 123
},
"completion_tokens": 123,
"completion_tokens_details": {
"text_tokens": 123,
"accepted_prediction_tokens": 123,
"audio_tokens": 123,
"citation_tokens": 123,
"num_search_queries": 123,
"reasoning_tokens": 123,
"image_tokens": 123,
"rejected_prediction_tokens": 123
},
"total_tokens": 123,
"tool_usage": {
"web_search": {
"num_requests": 123
}
},
"cost": {
"input_tokens_cost": 123,
"output_tokens_cost": 123,
"reasoning_tokens_cost": 123,
"citation_tokens_cost": 123,
"search_queries_cost": 123,
"request_cost": 123,
"total_cost": 123
}
}
}
}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.
A valid request URL is required to generate request examples{
"id": "<string>",
"created": 123,
"model": "<string>",
"data": [
{
"id": "<string>",
"url": "<string>",
"b64_json": "<string>",
"revised_prompt": "<string>",
"index": 123,
"detections": [
{
"x_min": 123,
"y_min": 123,
"x_max": 123,
"y_max": 123
}
]
}
],
"background": "<string>",
"output_format": "png",
"quality": "<string>",
"size": "256x256",
"usage": {
"input_tokens": 123,
"input_tokens_details": {
"image_tokens": 123,
"text_tokens": 123
},
"total_tokens": 123,
"output_tokens": 123,
"output_tokens_details": {
"image_tokens": 123,
"text_tokens": 123
}
},
"extra_fields": {
"request_type": "<string>",
"pricing_request_type": "<string>",
"routing_info": {
"provider": "anthropic",
"model": "<string>",
"key": "<string>",
"resolved_key_alias": {
"model_id": "<string>",
"model_name": "<string>",
"model_family": "<string>"
},
"is_fallback": true,
"primary_provider": "anthropic",
"primary_model": "<string>",
"requested_provider": "anthropic",
"requested_model": "<string>",
"server_side_fallback_model": "<string>"
},
"provider": "anthropic",
"original_model_requested": "<string>",
"resolved_model_used": "<string>",
"latency": 123,
"upstream_latency": 123,
"chunk_index": 123,
"raw_request": "<unknown>",
"raw_response": "<unknown>",
"cache_debug": {
"cache_hit": true,
"cache_id": "<string>",
"hit_type": "<string>",
"requested_provider": "<string>",
"requested_model": "<string>",
"provider_used": "<string>",
"model_used": "<string>",
"input_tokens": 123,
"threshold": 123,
"similarity": 123,
"cache_hit_latency": 123
},
"routing_metadata": {
"calls": [
{
"request_type": "<string>",
"provider_used": "<string>",
"model_used": "<string>",
"input_tokens": 123,
"output_tokens": 123,
"count_toward_budgets": true
}
]
},
"guardrail_debug": {
"judge_calls": [
{
"phase": "<string>",
"rule_id": 123,
"rule_name": "<string>",
"guardrail_name": "<string>",
"guardrail_provider": "<string>",
"action": "<string>",
"reason": "<string>",
"judge_provider": "<string>",
"judge_model": "<string>",
"judge_request_type": "<string>",
"prompt_tokens": 123,
"prompt_tokens_details": {},
"completion_tokens": 123,
"completion_tokens_details": {},
"total_tokens": 123
}
],
"detections": [
{
"phase": "<string>",
"rule_id": 123,
"rule_name": "<string>",
"guardrail_name": "<string>",
"guardrail_provider": "<string>",
"reason": "<string>",
"assessments": [
"<string>"
],
"action": "detect",
"enforced": true
}
]
},
"parse_errors": [
{
"code": "<string>",
"message": "<string>",
"param": "<string>",
"line": 123
}
],
"converted_request_type": "<string>",
"dropped_compat_plugin_params": [
"<string>"
],
"dropped_unsupported_tools": [
"<string>"
],
"provider_response_headers": {},
"passthrough_path": "<string>"
}
}{
"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": {
"routing_info": {
"provider": "anthropic",
"model": "<string>",
"key": "<string>",
"resolved_key_alias": {
"model_id": "<string>",
"model_name": "<string>",
"model_family": "<string>"
},
"is_fallback": true,
"primary_provider": "anthropic",
"primary_model": "<string>",
"requested_provider": "anthropic",
"requested_model": "<string>",
"server_side_fallback_model": "<string>"
},
"provider": "anthropic",
"original_model_requested": "<string>",
"resolved_model_used": "<string>",
"request_type": "<string>",
"mcp_request_type": "<string>",
"a2a_request_type": "<string>",
"a2a_agent_name": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500,
"raw_request": "<unknown>",
"raw_response": "<unknown>",
"converted_request_type": "<string>",
"dropped_compat_plugin_params": [
"<string>"
],
"latency": 123,
"key_statuses": [
{
"key_id": "<string>",
"status": "success",
"provider": "anthropic",
"error": "<unknown>"
}
],
"fallback_attempts": [
{
"provider": "anthropic",
"model": "<string>",
"status_code": 123,
"type": "<string>",
"message": "<string>",
"skipped": true
}
],
"mcp_auth_required": {
"kind": "<string>",
"mcp_client_id": "<string>",
"mcp_client_name": "<string>",
"message": "<string>",
"authorize_url": "<string>",
"session_id": "<string>",
"subject_token_missing": true,
"exchange_error": "<string>"
},
"billed_usage": {
"prompt_tokens": 123,
"prompt_tokens_details": {
"text_tokens": 123,
"audio_tokens": 123,
"image_tokens": 123,
"cached_read_tokens": 123,
"cached_write_tokens": 123
},
"completion_tokens": 123,
"completion_tokens_details": {
"text_tokens": 123,
"accepted_prediction_tokens": 123,
"audio_tokens": 123,
"citation_tokens": 123,
"num_search_queries": 123,
"reasoning_tokens": 123,
"image_tokens": 123,
"rejected_prediction_tokens": 123
},
"total_tokens": 123,
"tool_usage": {
"web_search": {
"num_requests": 123
}
},
"cost": {
"input_tokens_cost": 123,
"output_tokens_cost": 123,
"reasoning_tokens_cost": 123,
"citation_tokens_cost": 123,
"search_queries_cost": 123,
"request_cost": 123,
"total_cost": 123
}
}
}
}{
"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": {
"routing_info": {
"provider": "anthropic",
"model": "<string>",
"key": "<string>",
"resolved_key_alias": {
"model_id": "<string>",
"model_name": "<string>",
"model_family": "<string>"
},
"is_fallback": true,
"primary_provider": "anthropic",
"primary_model": "<string>",
"requested_provider": "anthropic",
"requested_model": "<string>",
"server_side_fallback_model": "<string>"
},
"provider": "anthropic",
"original_model_requested": "<string>",
"resolved_model_used": "<string>",
"request_type": "<string>",
"mcp_request_type": "<string>",
"a2a_request_type": "<string>",
"a2a_agent_name": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500,
"raw_request": "<unknown>",
"raw_response": "<unknown>",
"converted_request_type": "<string>",
"dropped_compat_plugin_params": [
"<string>"
],
"latency": 123,
"key_statuses": [
{
"key_id": "<string>",
"status": "success",
"provider": "anthropic",
"error": "<unknown>"
}
],
"fallback_attempts": [
{
"provider": "anthropic",
"model": "<string>",
"status_code": 123,
"type": "<string>",
"message": "<string>",
"skipped": true
}
],
"mcp_auth_required": {
"kind": "<string>",
"mcp_client_id": "<string>",
"mcp_client_name": "<string>",
"message": "<string>",
"authorize_url": "<string>",
"session_id": "<string>",
"subject_token_missing": true,
"exchange_error": "<string>"
},
"billed_usage": {
"prompt_tokens": 123,
"prompt_tokens_details": {
"text_tokens": 123,
"audio_tokens": 123,
"image_tokens": 123,
"cached_read_tokens": 123,
"cached_write_tokens": 123
},
"completion_tokens": 123,
"completion_tokens_details": {
"text_tokens": 123,
"accepted_prediction_tokens": 123,
"audio_tokens": 123,
"citation_tokens": 123,
"num_search_queries": 123,
"reasoning_tokens": 123,
"image_tokens": 123,
"rejected_prediction_tokens": 123
},
"total_tokens": 123,
"tool_usage": {
"web_search": {
"num_requests": 123
}
},
"cost": {
"input_tokens_cost": 123,
"output_tokens_cost": 123,
"reasoning_tokens_cost": 123,
"citation_tokens_cost": 123,
"search_queries_cost": 123,
"request_cost": 123,
"total_cost": 123
}
}
}
}Authorizations
Body
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.
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.
Type of edit operation. Support varies by provider; unsupported values are dropped and the request runs as a standard edit.
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 Response
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 dataimage_edit.completed: Final event for each image with usage informationerror: Error events with error details
Was this page helpful?

