Edit Image (OpenRouter)
pixara_edit_imageEdit or transform an image using a text prompt and reference images. Supports local files, URLs, or base64 inputs, and saves the edited image to disk.
Instructions
Edit or transform an existing image using a text prompt and one or more reference images, via any image-to-image-capable model on OpenRouter.
This calls OpenRouter's Image API with input_references and saves the resulting image(s) to disk. Reference images can be a local file path, a remote URL, or raw base64 — this tool handles reading/encoding local files itself, so you never need to pre-encode anything.
Args:
model (string): Must support image-to-image, e.g. 'openai/gpt-image-1' or 'bytedance-seed/seedream-4.5'. Check with pixara_get_model_details first if unsure.
prompt (string): Instruction describing the desired edit/transformation.
input_references (array, required, 1+): Each entry is one of: { source: "file", path: "/abs/or/relative/path.png" } { source: "url", url: "https://example.com/photo.jpg" } { source: "base64", data: "", media_type: "image/png" }
n, resolution, aspect_ratio, size, quality, output_format, background, output_compression, seed, provider_options, output_dir, filename_prefix: same meaning as in pixara_generate_image.
Returns: Markdown summary listing each saved file's path, media type, size in bytes, and the total cost charged by OpenRouter for the request.
Examples:
Use when: "Make this photo look like a watercolor painting" with a local file path
Use when: "Remove the background from this product photo" with a URL reference
Don't use when: there's no reference image at all (use pixara_generate_image)
Error Handling:
"Could not read reference image" -> check the file path is correct and readable
"Bad request" -> the chosen model may not support img2img; verify with pixara_get_model_details
"Insufficient OpenRouter credits" -> add credits at https://openrouter.ai/credits
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | Number of images to generate (1-10). Not all models support n > 1. | |
| seed | No | Seed for deterministic generation, where supported. | |
| size | No | Convenience shorthand for either a tier ('2K') or explicit dimensions ('2048x2048'). Don't combine with 'resolution' or 'aspect_ratio'. | |
| model | Yes | OpenRouter model slug, e.g. 'black-forest-labs/flux-1.1-pro' or 'openai/gpt-image-1'. Use pixara_list_image_models to discover available models. | |
| prompt | Yes | Text description of the desired image. | |
| quality | No | Quality tier: 'auto', 'low', 'medium', or 'high'. | |
| background | No | Background handling: 'auto', 'transparent', or 'opaque'. 'transparent' requires output_format 'png' or 'webp'. | |
| output_dir | No | Directory to save generated images into. Defaults to OPENROUTER_IMAGE_OUTPUT_DIR. | |
| resolution | No | Resolution tier: '512', '1K', '2K', or '4K'. Don't combine with 'size'. | |
| aspect_ratio | No | Aspect ratio, e.g. '16:9' or '1:1'. Don't combine with 'size'. | |
| output_format | No | Output image format: 'png', 'jpeg', or 'webp'. | png |
| filename_prefix | No | Prefix for saved image filenames (default: 'openrouter-image'). | |
| input_references | Yes | Reference image(s) to edit/transform. Each entry is a local file path, a remote URL, or raw base64 data — the tool handles reading/encoding for you. | |
| provider_options | No | Provider-specific passthrough params, keyed by provider slug, e.g. { 'black-forest-labs': { steps: 40, guidance: 3 } }. Check pixara_get_model_details for each provider's allowed_passthrough_parameters before using this. | |
| output_compression | No | Compression level 0-100, only applies to 'webp'/'jpeg' output_format. |