---
name: nanobananapro-api
description: Generate images and videos with the Nano Banana Pro API (Nano Banana Pro, GPT Image 2.5, Seedance and more). Use when the user asks to create or edit an image or a video through Nano Banana Pro, check their credit balance, or look up a task.
---

# Nano Banana Pro API skill

How to work:

1. Read the API key from the NANOBANANA_API_KEY environment variable. Never print it.
2. Check the balance first with GET /api/v1/balance when the cost matters.
3. Submit with POST and a fresh Idempotency-Key, then poll the task every 5 seconds until its status is completed or failed.
4. Report the result URLs from the task. A failed task is refunded automatically; say so instead of retrying blindly.
5. To retry after a refused submission, send a new Idempotency-Key.

# Nano Banana Pro API

Base URL: https://www.bananapro.site/api/v1

## Authentication

```http
Authorization: Bearer sk-your-api-key
Content-Type: application/json
Idempotency-Key: a-unique-id-per-request
```

Create an API key in the dashboard: https://www.bananapro.site/api-keys

## Rules

- Calls spend credits from the key owner's account. The site and the API share one balance.
- Send an Idempotency-Key with every POST so a retry never creates a second paid task.
- Submitting returns a task_id. Poll GET /api/v1/images/{task_id} or GET /api/v1/videos/{task_id} every few seconds until status is completed or failed. Failed tasks are refunded automatically.
- Media URLs must be public https URLs.
- Every model is listed by GET /api/v1/models.

## GPT Image 2.5 — POST /api/v1/images/generate

GPT Image 2.5 for sharper detail, cleaner typography and up to 4K output, in two looks

Docs: https://www.bananapro.site/api-docs/gpt-image-2-5

- Text-to-image and image-to-image (up to 16 reference images)
- 1K, 2K and 4K output with 13 aspect ratios, or auto
- Two looks: flare (default) and sunburst
- Standard mode for every account; economy at a lower price once the account has a purchase; stable for a fixed per-image price

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Must be "gpt-image-2.5" |
| type | string | No | "text-to-image" or "image-to-image" (default: text-to-image) |
| prompt | string | Yes | Text description (3–20000 chars) |
| image_urls | string[] | No | Required for image-to-image. 1–16 public https image URLs |
| image_size | string | No | Aspect ratio: "auto" (default), "1:1", "3:2", "2:3", "4:3", "3:4", "16:9", "9:16", "21:9", "27:16", "16:27", "9:8" or "8:9" |
| resolution | string | No | "1K" (default), "2K" or "4K" |
| variant | string | No | Look of the image: "flare" (default) or "sunburst" |
| generation_mode | string | No | "standard" (default), "economy" (needs an account with a purchase) or "stable" (same price for every account; needs a fixed image_size, "auto" is refused before charging) |
| num_images | number | No | Must be 1 |

### Credits

| Mode | 1K | 2K | 4K |
|---|---|---|---|
| standard, account with a purchase | 8 | 14 | 20 |
| standard, account without a purchase | 16 | 28 | 40 |
| stable (needs a fixed image_size) | 15 | 20 | 25 |
| economy (needs a purchase) | 5 | 8 | 12 |

Credits per image. Without a purchase, economy returns 403 purchase_required before anything is charged.

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs-gpt25-text-001" \
  -d '{
    "model": "gpt-image-2.5",
    "resolution": "2K",
    "image_size": "3:2",
    "prompt": "A product shot of a glass perfume bottle on wet black stone, soft rim light"
  }'
```

### Example: image input

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs-gpt25-edit-001" \
  -d '{
    "model": "gpt-image-2.5",
    "type": "image-to-image",
    "resolution": "1K",
    "prompt": "Move the cup onto a white marble counter, keep the cup and the morning light unchanged",
    "image_urls": [
      "https://cdn.gempix2.site/gempix2/img/tasks/gptimage25-g25-89eb5727b74db3d74b84ab07045757123470ab2b6bc0ae72-0.webp"
    ]
  }'
```

## GPT Image 2 — POST /api/v1/images/generate

GPT Image 2 for photoreal quality, precise text rendering, and pixel-level editing

Docs: https://www.bananapro.site/api-docs/gpt-image-2

- Text-to-image generation
- Image-to-image editing (up to 4 reference images)
- Photoreal quality and precise typography
- Single-image output (n=1)

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Must be "gpt-image-2" |
| type | string | No | "text-to-image" or "image-to-image" (default: text-to-image) |
| prompt | string | Yes | Text description (3–20000 chars) |
| image_urls | string[] | No | Required for image-to-image. Up to 4 reference image URLs |
| input_image | string | No | Deprecated. Alias for image_urls[0] |
| image_size | string | No | Optional aspect ratio: "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "5:4", "4:5", "2:1", "1:2", "21:9", or "9:21". Required for 4k; auto/default is not allowed with 4k. |
| resolution | string | No | Optional output resolution: "1k", "2k", or "4k" (default: "1k") |
| num_images | number | No | Must be 1 (gpt-image-2 always returns a single image) |

### Credits

| Resolution | Credits |
|---|---|
| 1k | 3 |
| 2k | 4 |
| 4k | 5 |

Per image for accounts with a purchase; accounts without one are charged 8 / 10 / 12. 4k requires image_size = 16:9, 9:16, 2:1, 1:2, 21:9, or 9:21.

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "resolution": "2k",
    "prompt": "A hand-drawn illustrated greeting card with the text \"Hello, world!\" in serif letters"
  }'
```

### Example: image input

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "type": "image-to-image",
    "resolution": "2k",
    "prompt": "Place the subject on a beach at golden hour, keep facial features identical",
    "image_urls": ["https://cdn.gempix2.site/gempix2/img/tasks/gptimage25-g25-89eb5727b74db3d74b84ab07045757123470ab2b6bc0ae72-0.webp"]
  }'
```

## Nano Banana Pro — POST /api/v1/images/generate

High-quality image generation with multi-image editing and resolution options up to 4K

Docs: https://www.bananapro.site/api-docs/nano-banana-pro

- Text-to-image generation
- Image-to-image transformation
- Up to 8 or 14 reference images, depending on the active generation channel
- Multiple resolutions (1K/2K/4K)
- Higher quality output

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Must be "nano-banana-pro" |
| type | string | No | "text-to-image" or "image-to-image" (default: text-to-image) |
| prompt | string | Yes | Text description of the image to generate |
| resolution | string | No | "1K", "2K", or "4K" |
| aspect_ratio | string | No | "1:1", "16:9", "9:16", "4:3", "3:4" |
| image_urls | string[] | No | Input image URLs or base64 for image-to-image. The active generation channel accepts up to 8 or 14 images. |
| input_image | string | No | Deprecated. Alias for image_urls[0] |
| num_images | number | No | Must be 1 |

### Credits

| Resolution | Credits |
|---|---|
| 1K | 8 |
| 2K | 12 |
| 4K | 16 |

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "resolution": "2K",
    "prompt": "A majestic dragon flying over a medieval castle",
    "aspect_ratio": "16:9"
  }'
```

### Example: image input

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "type": "image-to-image",
    "resolution": "2K",
    "prompt": "Transform this photo into a Studio Ghibli anime style",
    "image_urls": ["https://cdn.gempix2.site/gempix2/img/tasks/gptimage25-g25-89eb5727b74db3d74b84ab07045757123470ab2b6bc0ae72-0.webp"],
    "aspect_ratio": "16:9"
  }'
```

## Nano Banana 2 — POST /api/v1/images/generate

Next-generation image generation and editing with Google Search grounding, up to 14 reference images, and 4K output

Docs: https://www.bananapro.site/api-docs/nano-banana-2

- Text-to-image generation
- Image-to-image transformation
- Google Search grounding
- Up to 14 reference images
- Extreme aspect ratios and up to 4K resolution

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Must be "nano-banana-2" |
| type | string | No | "text-to-image" or "image-to-image" (default: text-to-image) |
| prompt | string | Yes | Text description of the image to generate. Supports up to 20,000 characters. |
| resolution | string | No | "1K", "2K", or "4K" (default: 1K) |
| aspect_ratio | string | No | "auto", "1:1", "16:9", "9:16", "4:3", "3:4", "1:4", "1:8", "4:1", "8:1", "21:9" |
| image_urls | string[] | No | Input image URLs or base64 for image-to-image. Supports up to 14 images. |
| input_image | string | No | Deprecated. Alias for image_urls[0] |
| google_search | boolean | No | Enable Google Search grounding for real-time information |
| google_image_search | boolean | No | Enable image search grounding. Requires google_search=true. |
| output_format | string | No | "jpg" or "png" (default: jpg) |
| num_images | number | No | Must be 1 |

### Credits

| Resolution | Credits |
|---|---|
| 1K | 7 |
| 2K | 11 |
| 4K | 15 |

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A cinematic product photo of a transparent smart speaker on a glass table",
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }'
```

### Example: image input

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "type": "image-to-image",
    "prompt": "Turn this product photo into a premium studio campaign image while preserving the product shape",
    "image_urls": ["https://cdn.gempix2.site/gempix2/img/tasks/gptimage25-g25-89eb5727b74db3d74b84ab07045757123470ab2b6bc0ae72-0.webp"],
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }'
```

## Nano Banana 2 Lite — POST /api/v1/images/generate

Fast image generation and editing with long prompts, automatic aspect ratio, and up to 10 reference images

Docs: https://www.bananapro.site/api-docs/nano-banana-2-lite

- Text-to-image generation
- Image-to-image editing
- Up to 10 reference images
- Prompts up to 20,000 characters
- Automatic and extreme aspect ratios

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Must be "nano-banana-2-lite" |
| type | string | No | "text-to-image" or "image-to-image" (default: text-to-image) |
| prompt | string | Yes | Text description of the image to generate. Supports 3 to 20,000 characters. |
| aspect_ratio | string | No | "auto", "1:1", "1:4", "1:8", "2:3", "3:2", "3:4", "4:1", "4:3", "4:5", "5:4", "8:1", "9:16", "16:9", or "21:9" (default: auto) |
| image_urls | string[] | No | Input image URLs for image-to-image. Supports up to 10 JPEG, PNG, or WebP images, 30MB each. |
| input_image | string | No | Deprecated. Alias for image_urls[0] |
| num_images | number | No | Must be 1 |

### Credits

| Mode | Credits |
|---|---|
| Fixed 1K output | 6 |

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-lite",
    "prompt": "A clean product photo of a translucent wireless speaker on a marble table, soft daylight, crisp details",
    "aspect_ratio": "auto"
  }'
```

### Example: image input

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-lite",
    "type": "image-to-image",
    "prompt": "Keep the product shape and materials, change the scene into a bright minimalist studio campaign image",
    "image_urls": ["https://cdn.gempix2.site/gempix2/img/tasks/gptimage25-g25-89eb5727b74db3d74b84ab07045757123470ab2b6bc0ae72-0.webp"],
    "aspect_ratio": "16:9"
  }'
```

## Nano Banana — POST /api/v1/images/generate

Fast image generation with text-to-image and image-to-image support

Docs: https://www.bananapro.site/api-docs/nano-banana

- Text-to-image generation
- Image-to-image transformation
- Multiple aspect ratios
- Fast generation (~5s)

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Must be "nano-banana" |
| type | string | No | "text-to-image" or "image-to-image" (default: text-to-image) |
| prompt | string | Yes | Text description of the image to generate |
| aspect_ratio | string | No | "1:1", "16:9", "9:16", "4:3", "3:4" |
| image_urls | string[] | No | Input image URLs or base64 for image-to-image |
| input_image | string | No | Deprecated. Alias for image_urls[0] |
| num_images | number | No | Must be 1 |

### Credits

4 credits

Per image

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana",
    "prompt": "A futuristic city at night with neon lights",
    "aspect_ratio": "16:9"
  }'
```

### Example: image input

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana",
    "type": "image-to-image",
    "prompt": "Add a cyberpunk neon glow effect to this image",
    "image_urls": ["https://cdn.gempix2.site/gempix2/img/tasks/gptimage25-g25-89eb5727b74db3d74b84ab07045757123470ab2b6bc0ae72-0.webp"],
    "aspect_ratio": "16:9"
  }'
```

## Seedream 5 Pro — POST /api/v1/images/generate

Professional image generation and editing with up to 10 reference images, 1K/2K output, and precise instruction following

Docs: https://www.bananapro.site/api-docs/seedream-5-pro

- Text-to-image generation
- Image-to-image editing
- Multi-image fusion with up to 10 reference images
- 1K and 2K output
- Economy and Standard generation modes
- Single-image output per request

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Must be "seedream-5-pro" |
| type | string | No | "text-to-image" or "image-to-image" (default: text-to-image) |
| prompt | string | Yes | Text prompt for image generation. Supports English and Chinese. Recommended: no more than 600 English words. Too much information can scatter details and cause missing elements. |
| generation_mode | string | No | "economy" or "standard". Existing API clients that omit this field keep the Standard-mode default. |
| resolution | string | No | "1K" or "2K" (default: 1K) |
| aspect_ratio | string | No | "1:1", "4:3", "3:4", "16:9", "9:16", "2:3", or "3:2". Standard mode also supports "21:9" (default: 1:1) |
| image_urls | string[] | No | Input image URLs for image-to-image. Supports up to 10 JPEG, PNG, or WebP images. Economy mode supports up to 10MB per image; Standard mode supports up to 30MB. Each image adds 1 credit. |
| input_image | string | No | Deprecated. Alias for image_urls[0] |
| num_images | number | No | Must be 1 |

### Credits

| Mode | 1K | 2K |
|---|---|---|
| Economy | 10 | 20 |
| Standard | 13 | 25 |

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-pro",
    "prompt": "A premium ecommerce product photo of a translucent smart speaker on a glass table, soft daylight, crisp details",
    "generation_mode": "economy",
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }'
```

### Example: image input

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-pro",
    "type": "image-to-image",
    "prompt": "Turn these references into one coherent luxury campaign image while preserving the product shape and brand colors",
    "image_urls": ["https://cdn.gempix2.site/gempix2/img/tasks/gptimage25-g25-89eb5727b74db3d74b84ab07045757123470ab2b6bc0ae72-0.webp"],
    "generation_mode": "economy",
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }'
```

## GPT Image — POST /api/v1/images/generate

GPT Image 1.5 for high-quality image generation and editing

Docs: https://www.bananapro.site/api-docs/gpt-image

- Text-to-image generation
- Image editing with prompts
- Multiple quality levels
- Flexible image sizes

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Must be "gpt-image-1.5" |
| type | string | No | "text-to-image" or "image-to-image" (default: text-to-image) |
| prompt | string | Yes | Text description of the image |
| quality | string | No | "low", "medium", or "high" (default: medium) |
| image_size | string | No | "1024x1024", "1536x1024", or "1024x1536" |
| num_images | number | No | Number of images (1-4) |
| image_urls | string[] | No | Input image URLs or base64 for image editing |
| input_image | string | No | Deprecated. Alias for image_urls[0] |

### Credits

| Quality | 1024×1024 | 1536×1024 |
|---|---|---|
| low | 2 | 3 |
| medium | 8 | 10 |
| high | 30 | 40 |

Total credits = base_credits × num_images

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1.5",
    "prompt": "A serene Japanese garden with cherry blossoms",
    "quality": "high",
    "image_size": "1024x1024"
  }'
```

### Example: image input

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1.5",
    "type": "image-to-image",
    "prompt": "Remove the background and replace it with a sunset beach",
    "image_urls": ["https://cdn.gempix2.site/gempix2/img/tasks/gptimage25-g25-89eb5727b74db3d74b84ab07045757123470ab2b6bc0ae72-0.webp"],
    "quality": "high"
  }'
```

## Upscaler — POST /api/v1/images/generate

Upscale an image to 1K, 2K or 4K, keeping its composition, colours and aspect ratio

Docs: https://www.bananapro.site/api-docs/upscaler

- 1K, 2K and 4K output
- Keeps the original composition, colours and aspect ratio
- Same engine and prices as the upscaler on the site
- Failed tasks are refunded automatically

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Must be "upscaler" |
| type | string | No | "upscale" |
| image_urls | string[] | Yes | Public URL of the image to upscale (first item is used) |
| resolution | string | No | "1k", "2k" (default) or "4k" output |
| scale | number | No | Deprecated. Used only when resolution is omitted: 3 or 4 means "4k", otherwise "2k" |

### Credits

| Resolution | Credits |
|---|---|
| 1k | 3 |
| 2k | 4 |
| 4k | 6 |

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/images/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "upscaler",
    "type": "upscale",
    "image_urls": ["https://cdn.gempix2.site/gempix2/img/tasks/gptimage25-g25-89eb5727b74db3d74b84ab07045757123470ab2b6bc0ae72-0.webp"],
    "resolution": "2k"
  }'
```

## Seedance 2.5 — POST /api/v1/videos/generate

Seedance 2.5 video with synchronized audio: text, image or mixed image / video / audio references, 4 to 30 seconds or auto length, up to 2K

Docs: https://www.bananapro.site/api-docs/seedance25

- Text-to-video, image-to-video (first frame, or first and last frame) and media-to-video
- Up to 30 images, 10 videos and 10 audio clips as references (50 files, 30 s of video or audio in total)
- 4–30 second clips, or duration "auto" to let the model choose
- 720p, 1080p and 1080p-plus (2K) output with generated audio
- standard, real (for references with real people) and wild channels

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Must be "seedance25" |
| type | string | No | "text-to-video", "image-to-video" or "media-to-video" (detected from media_urls when omitted). video-to-video is not supported |
| prompt | string | Yes | Text prompt, up to 10000 characters |
| media_urls | string[] | No | Public https URLs of reference images, videos and audio. Required for image-to-video and media-to-video |
| image_urls | string[] | No | Image-only references; media_urls takes precedence |
| aspect_ratio | string | No | "16:9" (default), "9:16", "1:1", "4:3", "3:4", "21:9" or "adaptive". Image-to-video follows the first frame; editing or extending a video requires "adaptive" |
| duration | string | No | "auto" (default) or "4" to "30" seconds. With "auto", credits for 30 seconds are reserved and the difference is refunded once the clip is ready. Editing or extending a video requires "auto" |
| resolution | string | No | "720p", "1080p" (default) or "1080p-plus" (2K) |
| channel | string | No | "standard" (default), "real" or "wild". Use real when references show real people |
| generate_audio | boolean | No | Generate synchronized audio (default: true) |

### Credits

| Resolution | Without video input | With video input |
|---|---|---|
| 720p | 15 | 10 |
| 1080p | 35 | 21 |
| 1080p-plus (2K) | 85 | 51 |

Credits per billable second, rounded to the nearest 5. Without video input, billable seconds are the output seconds; with a reference video they are max(4, input video seconds) + output seconds. The real channel costs 1.2x. duration "auto" reserves 30 seconds when submitted and refunds the difference once the clip is ready; credits_refunded shows it.

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/videos/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs-seedance25-text-001" \
  -d '{
    "model": "seedance25",
    "type": "text-to-video",
    "prompt": "A paper boat drifting down a rain-soaked street at dusk, reflections shimmering",
    "aspect_ratio": "16:9",
    "duration": "4",
    "resolution": "720p"
  }'
```

### Example: image input

```bash
curl -X POST https://www.bananapro.site/api/v1/videos/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs-seedance25-image-001" \
  -d '{
    "model": "seedance25",
    "type": "image-to-video",
    "prompt": "Steam rises slowly from the cup while morning light moves across the table",
    "media_urls": [
      "https://cdn.gempix2.site/gempix2/img/tasks/gptimage25-g25-89eb5727b74db3d74b84ab07045757123470ab2b6bc0ae72-0.webp"
    ],
    "aspect_ratio": "adaptive",
    "duration": "4",
    "resolution": "720p"
  }'
```

### Example: reference media

```bash
curl -X POST https://www.bananapro.site/api/v1/videos/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs-seedance25-media-001" \
  -d '{
    "model": "seedance25",
    "type": "media-to-video",
    "prompt": "Use the supplied cup as the product and match the turning camera move from the supplied video: the ceramic cup sits on a wooden table while the camera circles it in warm morning light",
    "media_urls": [
      "https://cdn.gempix2.site/gempix2/img/tasks/gptimage25-g25-89eb5727b74db3d74b84ab07045757123470ab2b6bc0ae72-0.webp",
      "https://cdn.gempix2.site/showcase/kling26/sample2.mp4"
    ],
    "aspect_ratio": "1:1",
    "duration": "5",
    "resolution": "720p"
  }'
```

### Example: edit a video

```bash
curl -X POST https://www.bananapro.site/api/v1/videos/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs-seedance25-edit-001" \
  -d '{
    "model": "seedance25",
    "type": "media-to-video",
    "prompt": "Strictly edit the supplied source video; change the dark backdrop to a bright white studio while keeping every burger layer, its motion and the camera move",
    "media_urls": [
      "https://cdn.gempix2.site/showcase/kling26/sample2.mp4"
    ],
    "aspect_ratio": "adaptive",
    "duration": "auto",
    "resolution": "720p"
  }'
```

### Seedance prompt guide

Seedance prompts work best as concrete director instructions. Describe the subject, action, scene, camera motion, visual style and constraints, then say what each reference file is for.

- For image-to-video, the first image is the opening frame and an optional second image is the closing frame. For reference media, pass images, videos and audio in media_urls.
- Describe each reference's role in the prompt in plain words ("the supplied cup", "the camera move from the supplied video"); do not refer to files by number or id.
- For edits say "strictly edit the supplied source video"; to continue a clip say "continue from the supplied previous clip".
- For complex scenes, list the shots in order, then a style and constraint package: stable faces, natural motion, no deformation, no watermark, no logo and no subtitles unless intended.

## Seedance 2 — POST /api/v1/videos/generate

Seedance 2 video generation with text-to-video, image-to-video, and multimodal reference support

Docs: https://www.bananapro.site/api-docs/seedance2

- Text-to-video generation
- Image-to-video generation
- Image, video, and audio reference inputs
- Fast and Pro model options
- Standard, real-person, and wild rendering modes
- 4-15 second outputs

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | "seedance2" for Pro quality or "seedance2-fast" for Fast quality |
| mode | string | No | "standard", "real", or "wild" rendering mode. channel is accepted as an alias. |
| type | string | No | "text-to-video", "image-to-video", or "media-to-video" (auto-detected from media_urls/image_urls when omitted) |
| prompt | string | Yes | Text prompt (3-2500 chars) |
| media_urls | string[] | No | Reference media URLs. Supports images, videos (MP4/MOV) and audio (MP3/WAV); detected by file extension. Video and audio are billed per second by their length, which is measured when you submit. |
| image_urls | string[] | No | Image-only reference URLs. media_urls takes precedence when both are provided. |
| input_image | string | No | Deprecated. Alias for image_urls[0] |
| aspect_ratio | string | No | "1:1", "21:9", "4:3", "3:4", "16:9", or "9:16" (default: 16:9) |
| duration | string | No | "4" through "15" seconds (default: 4) |
| resolution | string | No | "720p" or "1080p" (default: 720p). "480p" is additionally available only when mode is omitted. Resolution values select quality presets; actual encoding profiles are tuned per mode. |
| fallback | boolean | No | Allow automatic service fallback when available (default behavior) |
| seed | integer | No | -1 to 4294967295. Fixes the generation seed for reproducibility. Supported by explicit "standard", "real", and "wild" modes, including real-mode asset:// inputs. When mode is omitted, the parameter is accepted but ignored. |

### Credits

| Model / Resolution | 4s | 8s | 12s | 15s |
|---|---|---|---|---|
| seedance2-fast / 720p | 30 | 65 | 95 | 120 |
| seedance2 / 720p | 40 | 80 | 120 | 150 |
| seedance2 / 1080p | 90 | 175 | 265 | 330 |

Prices are for the standard and wild modes with text/image inputs. The real mode costs 1.2x before final credit rounding. Omitting mode uses a separate fixed price table with slightly different totals. Video or audio references add per-second media-reference pricing.

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/videos/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2",
    "mode": "standard",
    "type": "text-to-video",
    "prompt": "A cinematic drone shot over a futuristic coastal city at sunrise",
    "aspect_ratio": "16:9",
    "duration": "8",
    "resolution": "1080p",
    "seed": 12345
  }'
```

### Example: image input

```bash
curl -X POST https://www.bananapro.site/api/v1/videos/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2-fast",
    "mode": "real",
    "prompt": "A product spins slowly on a clean studio turntable with soft reflections",
    "media_urls": ["https://cdn.gempix2.site/gempix2/img/tasks/gptimage25-g25-89eb5727b74db3d74b84ab07045757123470ab2b6bc0ae72-0.webp"],
    "aspect_ratio": "16:9",
    "duration": "6",
    "resolution": "720p"
  }'
```

### Example: reference media

```bash
curl -X POST https://www.bananapro.site/api/v1/videos/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs-seedance2-media-001" \
  -d '{
    "model": "seedance2-fast",
    "mode": "standard",
    "type": "media-to-video",
    "prompt": "Use the supplied cup as the product and match the turning camera move from the supplied video: the ceramic cup sits on a wooden table while the camera circles it",
    "media_urls": [
      "https://cdn.gempix2.site/gempix2/img/tasks/gptimage25-g25-89eb5727b74db3d74b84ab07045757123470ab2b6bc0ae72-0.webp",
      "https://cdn.gempix2.site/showcase/kling26/sample2.mp4"
    ],
    "aspect_ratio": "1:1",
    "duration": "5",
    "resolution": "720p"
  }'
```

### Seedance prompt guide

Seedance prompts work best as concrete director instructions. Describe the subject, action, scene, camera motion, visual style and constraints, then say what each reference file is for.

- For image-to-video, the first image is the opening frame and an optional second image is the closing frame. For reference media, pass images, videos and audio in media_urls.
- Describe each reference's role in the prompt in plain words ("the supplied cup", "the camera move from the supplied video"); do not refer to files by number or id.
- For edits say "strictly edit the supplied source video"; to continue a clip say "continue from the supplied previous clip".
- For complex scenes, list the shots in order, then a style and constraint package: stable faces, natural motion, no deformation, no watermark, no logo and no subtitles unless intended.

## Seedance 2 Mini — POST /api/v1/videos/generate

Seedance 2 Mini video generation — cost-efficient tier with native audio, 4-15s, native 480p/720p output (API resolution values remain 720p/1080p), standard / real / wild modes

Docs: https://www.bananapro.site/api-docs/seedance2mini

- Text-to-video, image-to-video, and media-to-video generation
- Native audio generation
- Standard, real-person, and wild rendering modes
- Reproducible results via seed (explicit standard / real / wild modes)

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Must be "seedance2mini" |
| mode | string | No | "standard", "real", or "wild" rendering mode. channel is accepted as an alias. Defaults to the real mode when omitted. |
| type | string | No | "text-to-video", "image-to-video", or "media-to-video" (auto-detected from media_urls/image_urls when omitted) |
| prompt | string | Yes | Text prompt (3-2500 chars) |
| media_urls | string[] | No | Reference media URLs. Supports images, videos (MP4/MOV) and audio (MP3/WAV); detected by file extension. Video and audio are billed per second by their length, which is measured when you submit. |
| image_urls | string[] | No | Image-only reference URLs. media_urls takes precedence when both are provided. |
| input_image | string | No | Deprecated. Alias for image_urls[0] |
| aspect_ratio | string | No | "1:1", "21:9", "4:3", "3:4", "16:9", or "9:16" (default: 16:9) |
| duration | string | No | "4" through "15" seconds (default: 4) |
| resolution | string | No | "720p" or "1080p" (default: 720p). These API values produce native 480p and 720p output respectively; billing is unchanged. Mini does not support 4k. |
| generate_audio | boolean | No | Generate synchronized audio (default: true). Set to false for silent video. |
| seed | integer | No | -1 to 4294967295. Fixes the generation seed for reproducibility. Supported by explicit "standard", "real", and "wild" modes, including real-mode asset:// inputs. When mode is omitted, the parameter is accepted but ignored. Set "mode" explicitly for reproducible results. |

### Credits

| Mode / Resolution | 4s | 8s | 12s | 15s |
|---|---|---|---|---|
| Standard · Wild / 720p | 20 | 40 | 60 | 75 |
| Standard · Wild / 1080p | 45 | 90 | 130 | 165 |
| Real / 720p | 30 | 55 | 85 | 105 |
| Real / 1080p | 60 | 120 | 180 | 225 |

Example pricing for text/image inputs. Resolution rows use the API values: 720p produces native 480p output and 1080p produces native 720p output. Standard and wild modes share the same rate; the real mode is billed slightly higher. Video or audio reference inputs incur additional per-second billing.

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/videos/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2mini",
    "mode": "standard",
    "type": "text-to-video",
    "prompt": "A lone astronaut drifting toward a ringed planet, sunlight glinting off the visor",
    "aspect_ratio": "16:9",
    "duration": "4",
    "resolution": "720p",
    "seed": 12345
  }'
```

### Example: image input

```bash
curl -X POST https://www.bananapro.site/api/v1/videos/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2mini",
    "mode": "standard",
    "type": "image-to-video",
    "prompt": "A product spins slowly on a clean studio turntable with soft reflections",
    "image_urls": ["https://cdn.gempix2.site/gempix2/img/tasks/gptimage25-g25-89eb5727b74db3d74b84ab07045757123470ab2b6bc0ae72-0.webp"],
    "aspect_ratio": "16:9",
    "duration": "4",
    "resolution": "720p",
    "seed": 12345
  }'
```

### Example: reference media

```bash
curl -X POST https://www.bananapro.site/api/v1/videos/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs-seedance2mini-media-001" \
  -d '{
    "model": "seedance2mini",
    "mode": "standard",
    "type": "media-to-video",
    "prompt": "Use the supplied cup as the product and match the turning camera move from the supplied video: the ceramic cup sits on a wooden table while the camera circles it",
    "media_urls": [
      "https://cdn.gempix2.site/gempix2/img/tasks/gptimage25-g25-89eb5727b74db3d74b84ab07045757123470ab2b6bc0ae72-0.webp",
      "https://cdn.gempix2.site/showcase/kling26/sample2.mp4"
    ],
    "aspect_ratio": "1:1",
    "duration": "5",
    "resolution": "720p"
  }'
```

### Seedance prompt guide

Seedance prompts work best as concrete director instructions. Describe the subject, action, scene, camera motion, visual style and constraints, then say what each reference file is for.

- For image-to-video, the first image is the opening frame and an optional second image is the closing frame. For reference media, pass images, videos and audio in media_urls.
- Describe each reference's role in the prompt in plain words ("the supplied cup", "the camera move from the supplied video"); do not refer to files by number or id.
- For edits say "strictly edit the supplied source video"; to continue a clip say "continue from the supplied previous clip".
- For complex scenes, list the shots in order, then a style and constraint package: stable faces, natural motion, no deformation, no watermark, no logo and no subtitles unless intended.

## Seedance — POST /api/v1/videos/generate

ByteDance Seedance video generation with optional audio generation

Docs: https://www.bananapro.site/api-docs/seedance

- Text-to-video generation
- Image-to-video generation
- Optional audio generation
- Seedance 2 supports 4K output

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | "seedance", "seedance2", or "seedance2-fast" |
| type | string | No | "text-to-video" or "image-to-video" (default: text-to-video) |
| prompt | string | Yes | Text prompt (3-2500 chars) |
| image_urls | string[] | No | Required for image-to-video; supports 1-2 images |
| media_urls | string[] | No | Seedance2 media references. Supports images, videos, and audio; audio must be paired with at least one image or video. Video and audio are billed per second by their length, which is measured when you submit. |
| input_image | string | No | Deprecated. Alias for image_urls[0] |
| aspect_ratio | string | No | "1:1", "21:9", "4:3", "3:4", "16:9", or "9:16" |
| duration | string | No | "4", "8", or "12" for seedance; seedance2 supports 4-15 seconds |
| resolution | string | No | "480p" or "720p" for seedance; seedance2 also supports "1080p". "4k" requires model "seedance2" (other models reject "4k"). |
| fixed_lens | boolean | No | Use fixed camera/lens behavior (default: false) |
| generate_audio | boolean | No | Generate synchronized audio (default: true). Set to false for silent video. |

### Credits

| Duration | 480p No Audio | 480p Audio | 720p No Audio | 720p Audio |
|---|---|---|---|---|
| 4 sec | 8 | 16 | 16 | 32 |
| 8 sec | 16 | 32 | 32 | 64 |
| 12 sec | 24 | 48 | 48 | 96 |

Seedance 2 4K (resolution "4k") requires model "seedance2", durations 4-15s, billed per second at ~117 credits/sec (e.g. 5s ≈ 585 credits).

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/videos/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance",
    "type": "text-to-video",
    "prompt": "A cinematic pan across a rainy neon street",
    "aspect_ratio": "16:9",
    "duration": "8",
    "resolution": "720p",
    "generate_audio": true
  }'
```

### Seedance prompt guide

Seedance prompts work best as concrete director instructions. Describe the subject, action, scene, camera motion, visual style and constraints, then say what each reference file is for.

- For image-to-video, the first image is the opening frame and an optional second image is the closing frame. For reference media, pass images, videos and audio in media_urls.
- Describe each reference's role in the prompt in plain words ("the supplied cup", "the camera move from the supplied video"); do not refer to files by number or id.
- For edits say "strictly edit the supplied source video"; to continue a clip say "continue from the supplied previous clip".
- For complex scenes, list the shots in order, then a style and constraint package: stable faces, natural motion, no deformation, no watermark, no logo and no subtitles unless intended.

## Veo3 — POST /api/v1/videos/generate

Google's Veo 3 for high-quality video generation

Docs: https://www.bananapro.site/api-docs/veo3

- Text-to-video generation
- High quality output
- Multiple aspect ratios
- Optional watermark removal

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | "veo3" or "veo3_fast" |
| type | string | No | "text-to-video" or "image-to-video" (default: text-to-video) |
| prompt | string | Yes | Text description of the video |
| image_urls | string[] | No | Input image URLs for image-to-video |
| input_image | string | No | Deprecated. Alias for image_urls[0] |
| aspect_ratio | string | No | "16:9", "9:16", or "Auto" (aliases: "landscape", "portrait", "square") |
| watermark | boolean | No | Include watermark (default: true) |
| seeds | number | No | Random seed for reproducibility |
| enable_fallback | boolean | No | Retry on a backup generation channel if the first attempt fails |
| enable_translation | boolean | No | Auto-translate non-English prompts |

### Credits

| Model | Credits |
|---|---|
| veo3 (high quality) | 130 |
| veo3_fast (faster) | 30 |

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/videos/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3",
    "prompt": "A drone shot flying over a tropical beach at sunset",
    "aspect_ratio": "16:9"
  }'
```

## Kling26 — POST /api/v1/videos/generate

Kling 2.6 video generation with optional audio

Docs: https://www.bananapro.site/api-docs/kling26

- Text-to-video generation
- Optional audio generation
- Multiple durations
- High quality output

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Must be "kling26" |
| type | string | No | "text-to-video" or "image-to-video" (default: text-to-video) |
| prompt | string | Yes | Text description of the video |
| image_urls | string[] | No | Input image URLs for image-to-video |
| input_image | string | No | Deprecated. Alias for image_urls[0] |
| duration | string | No | "5" or "10" |
| sound | boolean | No | Generate with audio (default: false) |
| aspect_ratio | string | No | Output aspect ratio |

### Credits

| Duration | No Sound | With Sound |
|---|---|---|
| 5 sec | 60 | 120 |
| 10 sec | 120 | 240 |

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/videos/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling26",
    "prompt": "A fireworks display over a city skyline",
    "duration": "10",
    "sound": true
  }'
```

## Wan25/26 — POST /api/v1/videos/generate

Wan video generation models for high-quality output

Docs: https://www.bananapro.site/api-docs/wan

- Text-to-video generation
- Multiple durations
- 720p and 1080p support
- Optional prompt expansion

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | "wan25" or "wan26" |
| type | string | No | "text-to-video", "image-to-video", or "video-to-video" (wan26 only; default: text-to-video) |
| prompt | string | Yes | Text description of the video |
| image_urls | string[] | No | Input image URLs for image-to-video |
| image_url | string | No | Legacy single image URL for image-to-video |
| video_url | string | No | Input video URL for wan26 video-to-video |
| input_image | string | No | Deprecated. Alias for image_urls[0] |
| duration | string | No | "5" or "10" (wan25); "5", "10", or "15" (wan26) |
| resolution | string | No | "720p" or "1080p" |
| negative_prompt | string | No | What to avoid |
| enable_prompt_expansion | boolean | No | Auto-expand prompt |
| seed | number | No | Random seed for reproducibility |

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/videos/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan25",
    "prompt": "A butterfly landing on a flower in slow motion",
    "duration": "5",
    "resolution": "1080p"
  }'
```

## Hailuo — POST /api/v1/videos/generate

MiniMax Hailuo video generation with Pro/Standard variants

Docs: https://www.bananapro.site/api-docs/hailuo

- Text-to-video generation
- Image-to-video generation
- Standard and Pro variants
- Optional duration/resolution controls

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Must be "hailuo" |
| type | string | No | "text-to-video" or "image-to-video" (default: text-to-video) |
| prompt | string | Yes | Text prompt (3-5000 chars) |
| hailuo_model | string | No | "hailuo/02-text-to-video-pro", "hailuo/02-image-to-video-pro", "hailuo/02-text-to-video-standard", or "hailuo/02-image-to-video-standard" |
| image_urls | string[] | No | Required for image-to-video |
| input_image | string | No | Deprecated. Alias for image_urls[0] |
| duration | string | No | "6" or "10" (Standard variants only) |
| resolution | string | No | "512P" or "768P" (image-to-video-standard only) |

### Credits

| Variant | Credits |
|---|---|
| text-to-video-pro | 65 |
| image-to-video-pro | 65 |
| text-to-video-standard (6s) | 35 |
| text-to-video-standard (10s) | 55 |
| image-to-video-standard (6s, 512P) | 15 |
| image-to-video-standard (6s, 768P) | 35 |
| image-to-video-standard (10s, 512P) | 25 |
| image-to-video-standard (10s, 768P) | 55 |

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/videos/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo",
    "type": "image-to-video",
    "prompt": "A close-up of waves rolling onto a rocky beach",
    "hailuo_model": "hailuo/02-image-to-video-standard",
    "image_urls": ["https://cdn.gempix2.site/gempix2/img/tasks/gptimage25-g25-89eb5727b74db3d74b84ab07045757123470ab2b6bc0ae72-0.webp"],
    "duration": "6",
    "resolution": "768P"
  }'
```

## Grok Video — POST /api/v1/videos/generate

xAI Grok video model with normal/fun/spicy styles

Docs: https://www.bananapro.site/api-docs/grok-video

- Text-to-video generation
- Image-to-video generation
- Style modes (normal/fun/spicy)
- Fast generation

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Must be "grok-video" |
| type | string | No | "text-to-video" or "image-to-video" (default: text-to-video) |
| prompt | string | Yes | Text prompt (3-5000 chars) |
| mode_option | string | No | "normal", "fun", or "spicy" (default: normal) |
| aspect_ratio | string | No | "16:9", "9:16", "1:1", "2:3", or "3:2" (text-to-video only) |
| image_urls | string[] | No | Required for image-to-video; one public http/https URL only |
| input_image | string | No | Deprecated. Alias for image_urls[0] |

### Credits

| Mode | Credits |
|---|---|
| text-to-video | 30 |
| image-to-video | 30 |

### Example

```bash
curl -X POST https://www.bananapro.site/api/v1/videos/generate \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-video",
    "type": "text-to-video",
    "prompt": "A handheld shot of a bustling ramen alley at night",
    "mode_option": "fun",
    "aspect_ratio": "16:9"
  }'
```

## Tasks and balance

Read endpoints for polling a task, listing recent tasks, checking the balance and discovering models. They have their own read budget, so polling does not use up the submit budget.

### GET /api/v1/images/{task_id}

Status of one image task. Poll every few seconds until status is completed or failed; output.images lists the results.

```bash
curl https://www.bananapro.site/api/v1/images/task_abc123 \
  -H "Authorization: Bearer sk-your-api-key"
```

```json
{
  "success": true,
  "data": {
    "task_id": "task_abc123",
    "model": "nano-banana-pro",
    "status": "completed",
    "output": { "images": [{ "url": "https://cdn.example.com/result.png" }] },
    "image_url": "https://cdn.example.com/result.png",
    "error_message": null,
    "credits_used": 8,
    "credits_refunded": 0
  }
}
```

### GET /api/v1/videos/{task_id}

Status of one video task, with the same status values and video_url once it is ready.

```bash
curl https://www.bananapro.site/api/v1/videos/task_abc123 \
  -H "Authorization: Bearer sk-your-api-key"
```

### GET /api/v1/tasks

Your API tasks from the last 30 days, image and video together, newest first. Query: limit (1–50, default 20) and before (the next_cursor of the previous page). Every task carries type and a flat result_urls array.

```bash
curl "https://www.bananapro.site/api/v1/tasks?limit=20" \
  -H "Authorization: Bearer sk-your-api-key"
```

```json
{
  "success": true,
  "data": {
    "tasks": [
      {
        "task_id": "task_abc123",
        "type": "image",
        "model": "nano-banana-pro",
        "status": "completed",
        "result_urls": ["https://cdn.example.com/result.png"],
        "credits_used": 8,
        "credits_refunded": 0,
        "error_message": null,
        "created_at": "2026-10-03T08:12:45.000Z",
        "completed_at": "2026-10-03T08:13:20.000Z"
      }
    ],
    "has_more": false,
    "next_cursor": null
  }
}
```

### GET /api/v1/balance

Credits available to your account. The site and the API share one balance. /api/v1/account/balances returns the same data.

```bash
curl https://www.bananapro.site/api/v1/balance \
  -H "Authorization: Bearer sk-your-api-key"
```

```json
{
  "success": true,
  "data": { "credits": 500, "web_credits": 500, "api_credits": 500 }
}
```

### GET /api/v1/models

Every model the API serves, with the endpoint to call and the type values it accepts.

```bash
curl https://www.bananapro.site/api/v1/models \
  -H "Authorization: Bearer sk-your-api-key"
```

```json
{
  "success": true,
  "data": {
    "models": [
      {
        "id": "gpt-image-2.5",
        "name": "GPT Image 2.5",
        "type": "image",
        "method": "POST",
        "endpoint": "/api/v1/images/generate",
        "types": ["text-to-image", "image-to-image"]
      }
    ]
  }
}
```

### Task status values

- `pending`: Accepted and queued.
- `processing`: Generating.
- `completed`: Finished; results are in output / result_urls.
- `failed`: Did not finish; the credits are refunded automatically and credits_refunded shows the amount.

## Rate limits

Limits apply per API key and per minute. Reads (status, task list, balance, models) and submits are counted separately.

- Read requests per minute, per key: 6,000
- Submit requests per minute, per key: 600
- Tasks running at the same time, per account: 100

429 responses carry Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Running tasks include the ones you start on the site. Send an Idempotency-Key with every POST so a retry after a timeout never creates a second paid task.

## Errors

Errors return `{ "success": false, "error": { "code", "message" } }`.

| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The request parameters are invalid or malformed. |
| 401 | unauthorized | Invalid or missing API key. |
| 402 | insufficient_credits | Not enough credits in your account. |
| 403 | forbidden | API access not approved or your account is suspended. |
| 403 | purchase_required | The requested mode is only available to accounts with a purchase (for example GPT Image 2.5 economy). |
| 404 | not_found | The requested resource (task, webhook, etc.) was not found. |
| 429 | rate_limited | Too many requests in a short period. |
| 503 | service_busy | The generation mode is temporarily unavailable, or pricing changed while the request was in flight (409). |
| 500 | internal_error | Something went wrong on our end. |