Generate Image (OpenRouter)
pixara_generate_imageGenerate images from text prompts using any OpenRouter image model. Saves files and returns paths, model, and cost.
Instructions
Generate an image from a text prompt using any image model available on OpenRouter.
This calls OpenRouter's dedicated Image API (not chat completions) and saves the resulting image(s) to disk, returning the file path(s), model used, and cost. It does NOT edit or use reference images — for image-to-image/editing, use pixara_edit_image instead.
Args:
model (string): OpenRouter model slug, e.g. 'black-forest-labs/flux-1.1-pro' or 'openai/gpt-image-1'. Use pixara_list_image_models to discover options.
prompt (string): Text description of the desired image.
n (number, 1-10, default 1): Number of images to generate. Not all models support n > 1.
resolution ('512'|'1K'|'2K'|'4K', optional): Resolution tier.
aspect_ratio (string, optional): e.g. '16:9', '1:1'. Don't combine with 'size'.
size (string, optional): Convenience tier or explicit dimensions. Don't combine with resolution/aspect_ratio.
quality ('auto'|'low'|'medium'|'high', optional)
output_format ('png'|'jpeg'|'webp', default 'png')
background ('auto'|'transparent'|'opaque', optional): 'transparent' requires png/webp.
output_compression (0-100, optional): webp/jpeg only.
seed (number, optional): For deterministic generation where supported.
provider_options (object, optional): Provider-specific passthrough params. Check pixara_get_model_details first for allowed keys.
output_dir (string, optional): Where to save images (default: OPENROUTER_IMAGE_OUTPUT_DIR).
filename_prefix (string, optional): Prefix for saved filenames.
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: "Generate a picture of a red panda astronaut" -> model + prompt only
Use when: "Make a transparent-background product shot" -> background='transparent', output_format='png'
Don't use when: you have a reference image to transform (use pixara_edit_image)
Error Handling:
"Insufficient OpenRouter credits" -> add credits at https://openrouter.ai/credits
"Bad request" / conflicting params -> re-check with pixara_get_model_details
"Rate limited" -> wait and retry
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'). | |
| 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. |