---
title: "Generate or edit images using AI"
method: POST
path: "/api/ai/{project_id}/image"
tags: ["AI"]
---

# Generate or edit images using AI

`POST /api/ai/{project_id}/image`

## Request

- Base URL: `https://core.blink.new`
- URL: `https://core.blink.new/api/ai/{project_id}/image`
- Auth: HTTP bearer

**🎨 Advanced AI Image Generation & Editing**

Generate stunning images from text prompts or edit existing images via
the **Vercel AI Gateway**. Supports multimodal LLMs (Gemini 2.5/3 Pro image)
and image-only models (OpenAI gpt-image-1, BFL flux-pro, Recraft v3, etc.).
Legacy `fal-ai/*` and bare gemini model IDs are transparently rewritten to
Gateway canonical IDs, so existing SDK callers work unchanged.

**Capabilities**
- Text-to-image and image-to-image editing
- Up to 16 input images (multipart) or 50 URLs for multimodal models
- Multiple output formats

**📱 File Upload Support**
- Direct file uploads via multipart/form-data
- URL references
- Base64 encoded images
- Automatic format conversion

**💾 Output**
- Public GCS URLs (`https://storage.googleapis.com/blink-core-storage/...`)
- Multiple formats: PNG, JPEG, WebP

## Path parameters

- `project_id` string, required

## Request body

- ImageGenerationRequest
  - `model` 'openai/gpt-image-2' | 'google/gemini-2.5-flash-image' | 'google/gemini-3-pro-image' | 'openai/gpt-image-1' | 'bfl/flux-pro-1.1' | 'bytedance/seedream-4.5' | 'recraft/recraft-v3' | 'fal-ai/nano-banana' | 'fal-ai/nano-banana-pro' | 'fal-ai/nano-banana/edit' | 'fal-ai/nano-banana-pro/edit' | 'fal-ai/gemini-25-flash-image' | 'fal-ai/gemini-25-flash-image/edit' | 'fal-ai/gemini-3-pro-image-preview' | 'fal-ai/gemini-3-pro-image-preview/edit' | 'gemini-2.5-flash-image' | 'gemini-3-pro-image-preview': Image generation model routed through the Vercel AI Gateway. Omit it to use the current default; requests carrying reference images default to a multimodal editing model instead, since image-only models cannot edit. Supports Gateway canonical IDs (openai/gpt-image-2, google/gemini-2.5-flash-image, google/gemini-3-pro-image, bfl/flux-pro-1.1, bytedance/seedream-4.5, recraft/recraft-v3, …). Legacy fal-ai/* and bare gemini IDs are transparently rewritten for backwards compatibility.
  - `prompt` string, required: Text description of the desired image. Supports up to 100,000 characters for detailed descriptions.
  - `images` string[]: Input images for editing (optional). Supports up to 50 images with automatic format conversion for compatibility.
  - `mask` string: 🚫 NOT SUPPORTED: Mask editing has been deprecated. This API exclusively uses Gemini 2.5 Flash Image which provides superior editing without requiring masks.
  - `size` 'auto': 📝 INFORMATIONAL ONLY: Gemini automatically optimizes image dimensions. This parameter is accepted but ignored.
  - `quality` 'auto' | 'high' | 'medium' | 'low': 📝 INFORMATIONAL ONLY: Gemini automatically optimizes quality. This parameter is accepted but ignored.
  - `background` 'auto' | 'transparent' | 'opaque': 📝 INFORMATIONAL ONLY: Gemini handles backgrounds automatically. This parameter is accepted but ignored.
  - `style` 'vivid' | 'natural': 📝 INFORMATIONAL ONLY: Gemini uses its own style optimization. This parameter is accepted but ignored.
  - `n` integer: Number of images to generate
  - `response_format` 'url': 📝 INFORMATIONAL ONLY: Always returns cloud storage URLs. This parameter is ignored for consistency.
  - `output_format` 'png' | 'jpeg' | 'webp': ✅ FUNCTIONAL: Controls final cloud storage format. WebP recommended for best compression.
  - `output_compression` integer: ✅ FUNCTIONAL: Controls compression level during cloud storage conversion (0-100%). Higher = better quality, larger files.
  - `moderation` 'auto': 📝 INFORMATIONAL ONLY: Gemini has built-in safety filters. This parameter is accepted but ignored.

## Response `200`

Image generation successful

- ImageGenerationResponse
  - `result` object: The response data
    - `data` object[]: Array of generated images
      - `url` string, uri: Public URL of the generated image (when response_format=url)
      - `b64_json` string: Base64 encoded image data (when response_format=b64_json)
      - `revised_prompt` string: Revised prompt used for generation (if modified by the model)
    - `created` integer: Unix timestamp when the images were created
    - `background` 'transparent' | 'opaque' | 'auto': Background setting used for generation
    - `output_format` 'png' | 'jpeg' | 'webp': Output format of the generated images
    - `size` string: Size of the generated images
    - `quality` string: Quality level used for generation
    - `usage` object: Token usage information (OpenAI models only, Gemini provides limited usage data)
      - `total_tokens` integer: Total tokens used for generation
      - `input_tokens` integer: Input tokens (text and images)
      - `output_tokens` integer: Output tokens (generated images)
      - `input_tokens_details` object: Detailed breakdown of input tokens
        - `text_tokens` integer: Tokens from text input
        - `image_tokens` integer: Tokens from image input
  - `metadata` object
    - `projectId` string: Project identifier
    - `timestamp` string, date-time: Response timestamp
    - `provider` 'google-gemini' | 'openai': AI provider used for generation

## Other responses

- `400`: Invalid request or unsupported feature
- `401`: Authentication required or invalid API key
- `413`: Payload too large
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/blink/apis/blink-apis.md) - [All operations](https://skmtc.dev/blink/apis/blink-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/blink/apis/blink-apis/revisions/4c59c706078e?raw)