---
title: "Generate or edit an image"
method: POST
path: "/v1/ai/image"
tags: ["Images"]
---

# Generate or edit an image

`POST /v1/ai/image`

## Request

- Base URL: `https://apihub.co.il`
- URL: `https://apihub.co.il/v1/ai/image`
- Auth: HTTP bearer

Text-to-image, or edit / combine your reference images, with the model you pick (Nano Banana 2.1 by default, Pro for the strongest, Lite for the cheapest). Any aspect ratio, 512px–4K (512px runs on Nano Banana 2). The image is hosted for you.

**Billing:** By the image tokens the model reports (≈ list price per image) · **Rate limit:** 30/min

## Headers

- `Idempotency-Key` string
- `X-Tag` string

## Request body

- object
  - `model` 'auto' | 'gemini-3.1-flash-image' | 'gemini-nano-banana-2.1' | 'gemini-3.1-flash-lite-image' | 'gemini-3-pro-image': A model id (GET /v1/ai/models) or "auto" — then `quality` decides: fast=gemini-3.1-flash-lite-image, balanced=gemini-nano-banana-2.1, best=gemini-3-pro-image
  - `ultra` boolean: ULTRA: true = the image is made with Nano Banana Pro (gemini-3-pro-image) at 2K or larger, whatever model, quality and resolution are sent, at 3× the credits of the same request without ULTRA (the estimate's `ultra` block shows both prices — POST …/estimate before you run it). Only for accounts that have bought credits at least once (402 ultra_paid_only, with the account's top-up page in details.top_up) and where ULTRA is switched on (else 403 ultra_unavailable). Nothing is charged when it is refused.
  - `prompt` string, required
  - `quality` 'fast' | 'balanced' | 'best': Which model auto picks: fast (cheapest) · balanced (default) · best (strongest, costs more)
  - `resolution` '512px' | '1K' | '2K' | '4K'
  - `aspect_ratio` '1:1' | '4:5' | '3:4' | '2:3' | '9:16' | '16:9' | '4:3' | '3:2' | '21:9'
  - `reference_images` string[]: Images to edit or to take style/characters from

## Response `200`

Completed

- object
  - `id` string: Execution id — stable across internal retries; use it with GET /v1/executions/{id}
  - `status` 'pending' | 'processing' | 'completed' | 'partial' | 'failed' | 'cancelled' | 'timeout'
  - `operation` string
  - `tag` string, nullable: Your X-Tag, if sent
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `output` object: Operation result (see each operation). While a Studio render is processing: `stage` (queued · transcribing · downloading · preparing · cleaning_voice · mixing_audio · rendering · finishing), `phase` (the engine's: download · prepare · voice · audio · encode · qa · upload, or null), `progress` (a percent, 0–100) and `progress_fraction` (0–1), `eta_seconds` (seconds left, never below 0) and `estimate_seconds`
  - `error` string, nullable
  - `usage` object
    - `credits_charged` number, nullable
    - `credits_reserved` number
    - `estimated_credits` number
    - `cost_source` 'provider_reported' | 'calculated' | 'estimated' | 'null', nullable
    - `provider_usage` object, nullable: Normalised consumption, e.g. { VIDEO_SECOND: 22.4 }
  - `balance` object
    - `available` number
    - `reserved` number

## Other responses

- `400`: Invalid input
- `402`: Insufficient credits / project budget
- `404`: Resource not found (or not yours)
- `429`: Rate limited
- `503`: Service temporarily paused

---

[API](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai.md) · [All operations](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/llms.txt) · [OpenAPI document](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/revisions/a8caa42835ce?raw)