# Nano Banana Flash

Create an image task with this model, then query its result using the returned task ID.

Model ID `gemini-2.5-flash`

## Quickstart

Create an [API key](/me?section=api-keys) and set `I2V_API_KEY`. Set `IDEMPOTENCY_KEY` once for each new task. Reuse the key and identical payload when retrying that submission.

### Submit a task

`POST https://api.i2v.ai/api/v1/jobs/createTask`

```bash
curl "https://api.i2v.ai/api/v1/jobs/createTask" \
  -H "Authorization: Bearer $I2V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
  "model": "gemini-2.5-flash",
  "inputs": {
    "prompt": "A calm lake at sunrise"
  }
}'
```

HTTP 200 means the task was accepted. Save the returned `taskId`.

```json
{"taskId":"YOUR_TASK_ID"}
```

### Query the result

```bash
curl "https://api.i2v.ai/api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID" \
  -H "Authorization: Bearer $I2V_API_KEY"
```

Replace `YOUR_TASK_ID` with the returned ID. Poll with backoff while the status is `waiting` or `generating`. Read `output[].url` on `success`, or inspect `error` on `fail`.

## Parameters

Send model inputs inside `inputs`. Media URLs must be publicly accessible. Required media and supported combinations depend on the selected generation mode.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `inputs.prompt` | string | Yes | — | Text describing the result or requested edit. Maximum 5000 characters. |
| `inputs.aspectRatio` | string | No | — | Output aspect ratio. Allowed `1:1`, `9:16`, `16:9`, `3:4`, `4:3`, `3:2`, `2:3`, `auto`. |
| `inputs.imageUrls` | string[] | No | — | Reference images for image editing. Maximum 10 URLs. |

### Top-level request fields

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model` | string | Yes | `gemini-2.5-flash` | Public model ID. Use the exact value shown above. |
| `maxCostUsd` | string | No | — | Optional USD ceiling as a decimal string with up to eight fractional digits. A higher quote returns HTTP 409 before generation. |
| `callBackUrl` | string | No | — | Optional public HTTPS callback URL. Configure signing in [Webhooks](/docs/webhooks). |
| `expectedRevision` | number | No | — | Optional published model revision for optimistic concurrency checks. |

## Response

Illustrative successful response. Output URLs are placeholders. Actual USD charges depend on the submitted inputs. Pending tasks may contain null values.

```json
{
  "taskId": "YOUR_TASK_ID",
  "model": "gemini-2.5-flash",
  "status": "success",
  "billing": null,
  "output": [
    {
      "url": "https://example.com/result.png"
    }
  ],
  "error": null,
  "createTime": 1760000000000,
  "completeTime": 1760000060000
}
```

| Status | Meaning |
| --- | --- |
| `waiting` | Queued |
| `generating` | Generating |
| `success` | Completed. Read output[].url. |
| `fail` | Failed. Inspect error.code and error.message. |

## Code examples

### Node.js

```javascript
const baseUrl = "https://api.i2v.ai";
if (!process.env.I2V_API_KEY || !process.env.IDEMPOTENCY_KEY) {
  throw new Error('Set I2V_API_KEY and a stable IDEMPOTENCY_KEY before submitting.');
}
const headers = {
  Authorization: `Bearer ${process.env.I2V_API_KEY}`,
  'Content-Type': 'application/json',
  'Idempotency-Key': process.env.IDEMPOTENCY_KEY,
};
const response = await fetch(baseUrl + '/api/v1/jobs/createTask', {
  method: 'POST', headers,
  body: JSON.stringify({
  "model": "gemini-2.5-flash",
  "inputs": {
    "prompt": "A calm lake at sunrise"
  }
}),
});
const created = await response.json();
if (!response.ok) throw new Error(JSON.stringify(created));

const deadline = Date.now() + 30 * 60_000;
let delayMs = 2_000;
let output;
while (Date.now() < deadline) {
  const result = await fetch(baseUrl + '/api/v1/jobs/recordInfo?taskId=' + encodeURIComponent(created.taskId), { headers });
  const task = await result.json();
  if (!result.ok || task.status === 'fail') throw new Error(JSON.stringify(task));
  if (task.status === 'success') {
    output = task.output;
    break;
  }
  await new Promise(resolve => setTimeout(resolve, delayMs));
  delayMs = Math.min(delayMs * 1.5, 30_000);
}
if (!output) throw new Error('Polling timed out. Resume with taskId ' + created.taskId);
console.log(output.map(item => item.url));
```

### Python

```python
import json
import os
import time
import urllib.parse
import urllib.request

base_url = "https://api.i2v.ai"
headers = {
    'Authorization': 'Bearer ' + os.environ['I2V_API_KEY'],
    'Content-Type': 'application/json',
    'Idempotency-Key': os.environ['IDEMPOTENCY_KEY'],
}
payload = json.loads("{\"model\":\"gemini-2.5-flash\",\"inputs\":{\"prompt\":\"A calm lake at sunrise\"}}")
request = urllib.request.Request(
    base_url + '/api/v1/jobs/createTask',
    data=json.dumps(payload).encode(), headers=headers, method='POST',
)
with urllib.request.urlopen(request, timeout=60) as response:
    created = json.load(response)

deadline = time.monotonic() + 30 * 60
delay = 2
while time.monotonic() < deadline:
    query = urllib.parse.urlencode({'taskId': created['taskId']})
    request = urllib.request.Request(base_url + '/api/v1/jobs/recordInfo?' + query, headers=headers)
    with urllib.request.urlopen(request, timeout=60) as response:
        task = json.load(response)
    if task['status'] == 'fail':
        raise RuntimeError(task['error'])
    if task['status'] == 'success':
        print([item['url'] for item in task['output']])
        break
    time.sleep(delay)
    delay = min(delay * 1.5, 30)
else:
    raise TimeoutError('Polling timed out. Resume with taskId ' + created['taskId'])
```

### Reference image request

```json
{
  "model": "gemini-2.5-flash",
  "inputs": {
    "prompt": "A calm lake at sunrise",
    "imageUrls": [
      "https://example.com/reference.png"
    ]
  }
}
```

## Pricing

Published USD prices for each configuration and billing unit.

| Mode | Resolution | Duration | USD | Unit |
| --- | --- | --- | --- | --- |
| text-to-image | — | — | 0.01282051 USD | request |
| image-to-image | — | — | 0.01282051 USD | request |

## Errors and retries

Common submission errors include `400 invalid_params`, `401 unauthorized`, `402 insufficient_balance`, `409 conflict`, and `429 concurrency_limit` / `rate_limit`. See [errors and retries](/docs/errors) for recovery and [Webhooks](/docs/webhooks) for signed completion events.