# MixMedia API — full documentation

> Generated from https://docs.aimixmedia.site/en/

<!-- source: https://docs.aimixmedia.site/en/ -->

# Quick start

> Your first image through the API in 3 steps: key → task → result.

Base URL: `https://ai.aimixmedia.site/api/v1`

## 1. Get a key

Sign in at [ai.aimixmedia.site](https://ai.aimixmedia.site/login) and open [Dashboard → API keys](https://ai.aimixmedia.site/cabinet/keys). Press "Create key" and copy it. New users get $5 of credit.

```bash
export API_KEY="sk-aim-..."
```

## 2. Create a task

```bash
curl -X POST https://ai.aimixmedia.site/api/v1/jobs/createTask \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana-2","input":{"prompt":"A cat astronaut in a neon city"}}'
```

```python
import os, requests

r = requests.post(
    "https://ai.aimixmedia.site/api/v1/jobs/createTask",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
      "model": "nano-banana-2",
      "input": {
        "prompt": "A cat astronaut in a neon city"
      }
    },
)
print(r.json())  # {"code": 200, "data": {"taskId": "..."}}
```

```javascript
const r = await fetch("https://ai.aimixmedia.site/api/v1/jobs/createTask", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "model": "nano-banana-2",
    "input": {
      "prompt": "A cat astronaut in a neon city"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

The response is the task ID:

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_nano-banana-2_1790621023886ca4e4d"
  }
}
```

## 3. Get the result

Ask for the status every 3–5 seconds until `state` becomes `success` or `fail`. It usually takes 1–2 minutes.

```bash
curl "https://ai.aimixmedia.site/api/v1/jobs/recordInfo?taskId=task_nano-banana-2_1790621023886ca4e4d" \
  -H "Authorization: Bearer $API_KEY"
```

Done when `state` = `success`. Image links are in `resultJson`:

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_nano-banana-2_1790621023886ca4e4d",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://ai.aimixmedia.site/files/7496aef5292507f51b84cb2cb258d001.png\"]}",
    "creditsConsumed": 0.02
  }
}
```

If the task fails (`fail`), the money is refunded automatically.

## All together: a ready script

```python
import os, time, json, requests

API = "https://ai.aimixmedia.site/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

# 1. create a task
task = requests.post(f"{API}/jobs/createTask", headers=HEADERS, json={
    "model": "nano-banana-2",
    "input": {"prompt": "A cat astronaut in a neon city"},
}).json()
task_id = task["data"]["taskId"]

# 2. wait for the result
while True:
    info = requests.get(f"{API}/jobs/recordInfo", headers=HEADERS,
                        params={"taskId": task_id}).json()["data"]
    if info["state"] in ("success", "fail"):
        break
    time.sleep(4)

# 3. image links
if info["state"] == "success":
    print(json.loads(info["resultJson"])["resultUrls"])
else:
    print("failed:", info["failMsg"])
```

```javascript
const API = "https://ai.aimixmedia.site/api/v1";
const headers = { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" };

// 1. create a task
const task = await fetch(`${API}/jobs/createTask`, {
  method: "POST", headers,
  body: JSON.stringify({ model: "nano-banana-2", input: { prompt: "A cat astronaut in a neon city" } }),
}).then((r) => r.json());

// 2. wait for the result
let info;
do {
  await new Promise((r) => setTimeout(r, 4000));
  info = (await fetch(`${API}/jobs/recordInfo?taskId=${task.data.taskId}`, { headers }).then((r) => r.json())).data;
} while (!["success", "fail"].includes(info.state));

// 3. image links
console.log(info.state === "success" ? JSON.parse(info.resultJson).resultUrls : info.failMsg);
```

## Next

- [Models](https://docs.aimixmedia.site/en/models) — parameters and examples for every model
- [Callback](https://docs.aimixmedia.site/en/callbacks) — we POST the result to your server, no polling
- [Errors & limits](https://docs.aimixmedia.site/en/errors)

---

<!-- source: https://docs.aimixmedia.site/en/models -->

# All models

> Available models, their API IDs and prices.

Pass the model ID in the `model` field of `createTask`. One model can have several modes, each with its own ID.

| Model | Mode | ID | Price |
|---|---|---|---|
| [Nano Banana 2](https://docs.aimixmedia.site/en/models/nano-banana-2) | Image to Image | `nano-banana-2` | $0.02 |
|  | Text to Image | `nano-banana-2` | $0.02 |
| [Nano Banana Pro](https://docs.aimixmedia.site/en/models/nano-banana-pro) | Image to Image | `nano-banana-pro` | $0.02 |
|  | Text to Image | `nano-banana-pro` | $0.02 |
| [Nano Banana](https://docs.aimixmedia.site/en/models/nano-banana) | Image to Image | `google/nano-banana-edit` | $0.02 |
|  | Text to Image | `google/nano-banana` | $0.02 |
| [GPT Image 2.5](https://docs.aimixmedia.site/en/models/gpt-image-2.5) | Image to Image | `gpt-image-2.5-image-to-image` | $0.02 |
|  | Text to Image | `gpt-image-2.5-text-to-image` | $0.02 |

The price is per image. Failed tasks are free.

---

<!-- source: https://docs.aimixmedia.site/en/models/nano-banana-2 -->

# Nano Banana 2

> Gemini 3.1 Flash Image: fast generation and editing, accurate text in images, up to 14 references.

Nano Banana 2 (Gemini 3.1 Flash Image) is Google's main image model. It keeps characters consistent, renders legible text inside images, understands long prompts (up to 20,000 characters) and accepts up to 14 reference images for editing, compositing and style transfer.

| Mode | ID | Price |
|---|---|---|
| [Image to Image](#image-to-image) | `nano-banana-2` | $0.02 |
| [Text to Image](#text-to-image) | `nano-banana-2` | $0.02 |

Both modes are one model, `nano-banana-2`: pass photos and it edits them or uses them as references.

## Image to Image

Upload a photo and describe what to change. ID: `nano-banana-2` · $0.02 per image · ~1.5 min

**Parameters** (field `input`)

| Parameter | Required | Description | Values (default in bold) |
|---|---|---|---|
| `prompt` | yes | What to draw or what to change | text, up to 20000 chars |
| `image_input` | yes | Links to your photos (https), up to 14 | `["https://…"]` |
| `aspect_ratio` | no | Image shape | **`auto`** `1:1` `2:3` `3:2` `1:4` `4:1` `3:4` `4:3` `4:5` `5:4` `1:8` `8:1` `9:16` `16:9` `21:9` |
| `resolution` | no | Quality: 1K is faster, 2K has more detail | **`1K`** `2K` `4K` |
| `output_format` | no | File format | **`jpg`** `png` |

**Example**

```bash
curl -X POST https://ai.aimixmedia.site/api/v1/jobs/createTask \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana-2","input":{"prompt":"Make the background a neon city at night","image_input":["https://ai.aimixmedia.site/static/img/previews/gpt-t2i.jpg"],"aspect_ratio":"auto","resolution":"1K"}}'
```

```python
import os, requests

r = requests.post(
    "https://ai.aimixmedia.site/api/v1/jobs/createTask",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
      "model": "nano-banana-2",
      "input": {
        "prompt": "Make the background a neon city at night",
        "image_input": [
          "https://ai.aimixmedia.site/static/img/previews/gpt-t2i.jpg"
        ],
        "aspect_ratio": "auto",
        "resolution": "1K"
      }
    },
)
print(r.json())  # {"code": 200, "data": {"taskId": "..."}}
```

```javascript
const r = await fetch("https://ai.aimixmedia.site/api/v1/jobs/createTask", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "model": "nano-banana-2",
    "input": {
      "prompt": "Make the background a neon city at night",
      "image_input": [
        "https://ai.aimixmedia.site/static/img/previews/gpt-t2i.jpg"
      ],
      "aspect_ratio": "auto",
      "resolution": "1K"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

## Text to Image

Describe the picture and the model creates it from scratch. ID: `nano-banana-2` · $0.02 per image · ~1.5 min

**Parameters** (field `input`)

| Parameter | Required | Description | Values (default in bold) |
|---|---|---|---|
| `prompt` | yes | What to draw or what to change | text, up to 20000 chars |
| `aspect_ratio` | no | Image shape | **`auto`** `1:1` `2:3` `3:2` `1:4` `4:1` `3:4` `4:3` `4:5` `5:4` `1:8` `8:1` `9:16` `16:9` `21:9` |
| `resolution` | no | Quality: 1K is faster, 2K has more detail | **`1K`** `2K` `4K` |
| `output_format` | no | File format | **`jpg`** `png` |

**Example**

```bash
curl -X POST https://ai.aimixmedia.site/api/v1/jobs/createTask \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana-2","input":{"prompt":"A cat astronaut in a neon city, cinematic light","aspect_ratio":"auto","resolution":"1K"}}'
```

```python
import os, requests

r = requests.post(
    "https://ai.aimixmedia.site/api/v1/jobs/createTask",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
      "model": "nano-banana-2",
      "input": {
        "prompt": "A cat astronaut in a neon city, cinematic light",
        "aspect_ratio": "auto",
        "resolution": "1K"
      }
    },
)
print(r.json())  # {"code": 200, "data": {"taskId": "..."}}
```

```javascript
const r = await fetch("https://ai.aimixmedia.site/api/v1/jobs/createTask", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "model": "nano-banana-2",
    "input": {
      "prompt": "A cat astronaut in a neon city, cinematic light",
      "aspect_ratio": "auto",
      "resolution": "1K"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

## Result

Same as any task: call [recordInfo](https://docs.aimixmedia.site/en/endpoints/record-info) or receive a [callback](https://docs.aimixmedia.site/en/callbacks). Image links are in `resultJson` (kept for 30 days).

Upload your photos via [files/upload](https://docs.aimixmedia.site/en/endpoints/upload) or pass any public https links.

---

<!-- source: https://docs.aimixmedia.site/en/models/nano-banana-pro -->

# Nano Banana Pro

> Gemini 3 Pro Image: top quality, complex compositions and infographics.

Nano Banana Pro (Gemini 3 Pro Image) is Google's flagship image model for complex scenes, infographics, posters and photorealism. Accepts up to 8 reference images.

| Mode | ID | Price |
|---|---|---|
| [Image to Image](#image-to-image) | `nano-banana-pro` | $0.02 |
| [Text to Image](#text-to-image) | `nano-banana-pro` | $0.02 |

Both modes are one model, `nano-banana-pro`: pass photos and it edits them or uses them as references.

## Image to Image

Upload a photo and describe what to change. ID: `nano-banana-pro` · $0.02 per image · ~2.5 min

**Parameters** (field `input`)

| Parameter | Required | Description | Values (default in bold) |
|---|---|---|---|
| `prompt` | yes | What to draw or what to change | text, up to 10000 chars |
| `image_input` | yes | Links to your photos (https), up to 8 | `["https://…"]` |
| `aspect_ratio` | no | Image shape | **`1:1`** `2:3` `3:2` `3:4` `4:3` `4:5` `5:4` `9:16` `16:9` `21:9` `auto` |
| `resolution` | no | Quality: 1K is faster, 2K has more detail | **`1K`** `2K` `4K` |
| `output_format` | no | File format | **`png`** `jpg` |

**Example**

```bash
curl -X POST https://ai.aimixmedia.site/api/v1/jobs/createTask \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana-pro","input":{"prompt":"Make the background a neon city at night","image_input":["https://ai.aimixmedia.site/static/img/previews/gpt-t2i.jpg"],"aspect_ratio":"1:1","resolution":"1K"}}'
```

```python
import os, requests

r = requests.post(
    "https://ai.aimixmedia.site/api/v1/jobs/createTask",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
      "model": "nano-banana-pro",
      "input": {
        "prompt": "Make the background a neon city at night",
        "image_input": [
          "https://ai.aimixmedia.site/static/img/previews/gpt-t2i.jpg"
        ],
        "aspect_ratio": "1:1",
        "resolution": "1K"
      }
    },
)
print(r.json())  # {"code": 200, "data": {"taskId": "..."}}
```

```javascript
const r = await fetch("https://ai.aimixmedia.site/api/v1/jobs/createTask", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "model": "nano-banana-pro",
    "input": {
      "prompt": "Make the background a neon city at night",
      "image_input": [
        "https://ai.aimixmedia.site/static/img/previews/gpt-t2i.jpg"
      ],
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

## Text to Image

Describe the picture and the model creates it from scratch. ID: `nano-banana-pro` · $0.02 per image · ~2.5 min

**Parameters** (field `input`)

| Parameter | Required | Description | Values (default in bold) |
|---|---|---|---|
| `prompt` | yes | What to draw or what to change | text, up to 10000 chars |
| `aspect_ratio` | no | Image shape | **`1:1`** `2:3` `3:2` `3:4` `4:3` `4:5` `5:4` `9:16` `16:9` `21:9` `auto` |
| `resolution` | no | Quality: 1K is faster, 2K has more detail | **`1K`** `2K` `4K` |
| `output_format` | no | File format | **`png`** `jpg` |

**Example**

```bash
curl -X POST https://ai.aimixmedia.site/api/v1/jobs/createTask \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana-pro","input":{"prompt":"A cat astronaut in a neon city, cinematic light","aspect_ratio":"1:1","resolution":"1K"}}'
```

```python
import os, requests

r = requests.post(
    "https://ai.aimixmedia.site/api/v1/jobs/createTask",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
      "model": "nano-banana-pro",
      "input": {
        "prompt": "A cat astronaut in a neon city, cinematic light",
        "aspect_ratio": "1:1",
        "resolution": "1K"
      }
    },
)
print(r.json())  # {"code": 200, "data": {"taskId": "..."}}
```

```javascript
const r = await fetch("https://ai.aimixmedia.site/api/v1/jobs/createTask", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "model": "nano-banana-pro",
    "input": {
      "prompt": "A cat astronaut in a neon city, cinematic light",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

## Result

Same as any task: call [recordInfo](https://docs.aimixmedia.site/en/endpoints/record-info) or receive a [callback](https://docs.aimixmedia.site/en/callbacks). Image links are in `resultJson` (kept for 30 days).

Upload your photos via [files/upload](https://docs.aimixmedia.site/en/endpoints/upload) or pass any public https links.

---

<!-- source: https://docs.aimixmedia.site/en/models/nano-banana -->

# Nano Banana

> Google's lightweight, fast model: text-to-image generation and instruction-based photo editing.

| Mode | ID | Price |
|---|---|---|
| [Image to Image](#image-to-image) | `google/nano-banana-edit` | $0.02 |
| [Text to Image](#text-to-image) | `google/nano-banana` | $0.02 |

## Image to Image

Upload a photo and describe what to change. ID: `google/nano-banana-edit` · $0.02 per image · ~1.5 min

**Parameters** (field `input`)

| Parameter | Required | Description | Values (default in bold) |
|---|---|---|---|
| `prompt` | yes | What to draw or what to change | text, up to 5000 chars |
| `image_urls` | yes | Links to your photos (https), up to 10 | `["https://…"]` |
| `aspect_ratio` | no | Image shape | **`1:1`** `9:16` `16:9` `3:4` `4:3` `3:2` `2:3` `5:4` `4:5` `21:9` `auto` |
| `output_format` | no | File format | **`png`** `jpeg` |

**Example**

```bash
curl -X POST https://ai.aimixmedia.site/api/v1/jobs/createTask \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/nano-banana-edit","input":{"prompt":"Make the background a neon city at night","image_urls":["https://ai.aimixmedia.site/static/img/previews/gpt-t2i.jpg"],"aspect_ratio":"1:1"}}'
```

```python
import os, requests

r = requests.post(
    "https://ai.aimixmedia.site/api/v1/jobs/createTask",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
      "model": "google/nano-banana-edit",
      "input": {
        "prompt": "Make the background a neon city at night",
        "image_urls": [
          "https://ai.aimixmedia.site/static/img/previews/gpt-t2i.jpg"
        ],
        "aspect_ratio": "1:1"
      }
    },
)
print(r.json())  # {"code": 200, "data": {"taskId": "..."}}
```

```javascript
const r = await fetch("https://ai.aimixmedia.site/api/v1/jobs/createTask", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "model": "google/nano-banana-edit",
    "input": {
      "prompt": "Make the background a neon city at night",
      "image_urls": [
        "https://ai.aimixmedia.site/static/img/previews/gpt-t2i.jpg"
      ],
      "aspect_ratio": "1:1"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

## Text to Image

Describe the picture and the model creates it from scratch. ID: `google/nano-banana` · $0.02 per image · ~1 min

**Parameters** (field `input`)

| Parameter | Required | Description | Values (default in bold) |
|---|---|---|---|
| `prompt` | yes | What to draw or what to change | text, up to 5000 chars |
| `aspect_ratio` | no | Image shape | **`1:1`** `9:16` `16:9` `3:4` `4:3` `3:2` `2:3` `5:4` `4:5` `21:9` `auto` |
| `output_format` | no | File format | **`png`** `jpeg` |

**Example**

```bash
curl -X POST https://ai.aimixmedia.site/api/v1/jobs/createTask \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/nano-banana","input":{"prompt":"A cat astronaut in a neon city, cinematic light","aspect_ratio":"1:1"}}'
```

```python
import os, requests

r = requests.post(
    "https://ai.aimixmedia.site/api/v1/jobs/createTask",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
      "model": "google/nano-banana",
      "input": {
        "prompt": "A cat astronaut in a neon city, cinematic light",
        "aspect_ratio": "1:1"
      }
    },
)
print(r.json())  # {"code": 200, "data": {"taskId": "..."}}
```

```javascript
const r = await fetch("https://ai.aimixmedia.site/api/v1/jobs/createTask", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "model": "google/nano-banana",
    "input": {
      "prompt": "A cat astronaut in a neon city, cinematic light",
      "aspect_ratio": "1:1"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

## Result

Same as any task: call [recordInfo](https://docs.aimixmedia.site/en/endpoints/record-info) or receive a [callback](https://docs.aimixmedia.site/en/callbacks). Image links are in `resultJson` (kept for 30 days).

Upload your photos via [files/upload](https://docs.aimixmedia.site/en/endpoints/upload) or pass any public https links.

---

<!-- source: https://docs.aimixmedia.site/en/models/gpt-image-2.5 -->

# GPT Image 2.5

> OpenAI GPT Image 2.5: photorealism, clean text, product shots and precise photo editing.

| Mode | ID | Price |
|---|---|---|
| [Image to Image](#image-to-image) | `gpt-image-2.5-image-to-image` | $0.02 |
| [Text to Image](#text-to-image) | `gpt-image-2.5-text-to-image` | $0.02 |

## Image to Image

Upload a photo and describe what to change. ID: `gpt-image-2.5-image-to-image` · $0.02 per image · ~2 min

**Parameters** (field `input`)

| Parameter | Required | Description | Values (default in bold) |
|---|---|---|---|
| `prompt` | yes | What to draw or what to change | text, up to 20000 chars |
| `input_urls` | yes | Links to your photos (https), up to 16 | `["https://…"]` |
| `aspect_ratio` | no | Image shape | **`auto`** `1:1` `16:9` `9:16` `4:3` `3:4` `5:4` `4:5` `2:1` `1:2` `3:1` `1:3` `21:9` `9:21` `3:2` `2:3` |
| `resolution` | no | Quality: 1K is faster, 2K has more detail | **`1K`** |
| `background` | no | Background: `transparent` for no background | **`auto`** `opaque` `transparent` |

**Example**

```bash
curl -X POST https://ai.aimixmedia.site/api/v1/jobs/createTask \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2.5-image-to-image","input":{"prompt":"Make the background a neon city at night","input_urls":["https://ai.aimixmedia.site/static/img/previews/gpt-t2i.jpg"],"aspect_ratio":"auto","resolution":"1K"}}'
```

```python
import os, requests

r = requests.post(
    "https://ai.aimixmedia.site/api/v1/jobs/createTask",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
      "model": "gpt-image-2.5-image-to-image",
      "input": {
        "prompt": "Make the background a neon city at night",
        "input_urls": [
          "https://ai.aimixmedia.site/static/img/previews/gpt-t2i.jpg"
        ],
        "aspect_ratio": "auto",
        "resolution": "1K"
      }
    },
)
print(r.json())  # {"code": 200, "data": {"taskId": "..."}}
```

```javascript
const r = await fetch("https://ai.aimixmedia.site/api/v1/jobs/createTask", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "model": "gpt-image-2.5-image-to-image",
    "input": {
      "prompt": "Make the background a neon city at night",
      "input_urls": [
        "https://ai.aimixmedia.site/static/img/previews/gpt-t2i.jpg"
      ],
      "aspect_ratio": "auto",
      "resolution": "1K"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

## Text to Image

Describe the picture and the model creates it from scratch. ID: `gpt-image-2.5-text-to-image` · $0.02 per image · ~1.5 min

**Parameters** (field `input`)

| Parameter | Required | Description | Values (default in bold) |
|---|---|---|---|
| `prompt` | yes | What to draw or what to change | text, up to 20000 chars |
| `aspect_ratio` | no | Image shape | **`auto`** `1:1` `16:9` `9:16` `4:3` `3:4` `5:4` `4:5` `2:1` `1:2` `3:1` `1:3` `21:9` `9:21` `3:2` `2:3` |
| `resolution` | no | Quality: 1K is faster, 2K has more detail | **`1K`** |
| `background` | no | Background: `transparent` for no background | **`auto`** `opaque` `transparent` |

**Example**

```bash
curl -X POST https://ai.aimixmedia.site/api/v1/jobs/createTask \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2.5-text-to-image","input":{"prompt":"A cat astronaut in a neon city, cinematic light","aspect_ratio":"auto","resolution":"1K"}}'
```

```python
import os, requests

r = requests.post(
    "https://ai.aimixmedia.site/api/v1/jobs/createTask",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
      "model": "gpt-image-2.5-text-to-image",
      "input": {
        "prompt": "A cat astronaut in a neon city, cinematic light",
        "aspect_ratio": "auto",
        "resolution": "1K"
      }
    },
)
print(r.json())  # {"code": 200, "data": {"taskId": "..."}}
```

```javascript
const r = await fetch("https://ai.aimixmedia.site/api/v1/jobs/createTask", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "model": "gpt-image-2.5-text-to-image",
    "input": {
      "prompt": "A cat astronaut in a neon city, cinematic light",
      "aspect_ratio": "auto",
      "resolution": "1K"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

## Result

Same as any task: call [recordInfo](https://docs.aimixmedia.site/en/endpoints/record-info) or receive a [callback](https://docs.aimixmedia.site/en/callbacks). Image links are in `resultJson` (kept for 30 days).

Upload your photos via [files/upload](https://docs.aimixmedia.site/en/endpoints/upload) or pass any public https links.

---

<!-- source: https://docs.aimixmedia.site/en/endpoints/create-task -->

# POST /api/v1/jobs/createTask

> Creates a generation task and returns its ID (taskId) right away. The price is charged now and refunded on failure.

## Request

```http
POST https://ai.aimixmedia.site/api/v1/jobs/createTask
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

## Parameters

| Field | Required | Description |
|---|---|---|
| `model` | yes | Model ID, e.g. `nano-banana-2` — [list](https://docs.aimixmedia.site/en/models) |
| `input` | yes | Model parameters: `prompt`, photos, etc. — see the model page |
| `callBackUrl` | no | Where to POST the result when the task finishes — [callback](https://docs.aimixmedia.site/en/callbacks) |

The optional `Idempotency-Key` header protects against duplicates on retries — [details](https://docs.aimixmedia.site/en/idempotency).

## Response

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_nano-banana-2_1790621023886ca4e4d"
  }
}
```

## Examples

```bash
curl -X POST https://ai.aimixmedia.site/api/v1/jobs/createTask \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana-2","callBackUrl":"https://your-app.example/callback","input":{"prompt":"Poster \"Summer in Moscow\"","aspect_ratio":"3:4"}}'
```

```python
import os, requests

r = requests.post(
    "https://ai.aimixmedia.site/api/v1/jobs/createTask",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
      "model": "nano-banana-2",
      "callBackUrl": "https://your-app.example/callback",
      "input": {
        "prompt": "Poster \"Summer in Moscow\"",
        "aspect_ratio": "3:4"
      }
    },
)
print(r.json())  # {"code": 200, "data": {"taskId": "..."}}
```

```javascript
const r = await fetch("https://ai.aimixmedia.site/api/v1/jobs/createTask", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "model": "nano-banana-2",
    "callBackUrl": "https://your-app.example/callback",
    "input": {
      "prompt": "Poster \"Summer in Moscow\"",
      "aspect_ratio": "3:4"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

## Errors

| code | error | When |
|---|---|---|
| 401 | `unauthorized` | Missing or invalid key |
| 402 | `insufficient_balance` | Not enough balance |
| 422 | `validation_error` | Invalid parameter (see `msg`) |
| 422 | `unsupported_model` | Unknown model |
| 429 | `rate_limited` | Too many requests |

All codes are in [Errors & limits](https://docs.aimixmedia.site/en/errors).

---

<!-- source: https://docs.aimixmedia.site/en/endpoints/record-info -->

# GET /api/v1/jobs/recordInfo

> Task status and result. Ask every 3–5 seconds until state becomes success or fail.

## Request

```http
GET https://ai.aimixmedia.site/api/v1/jobs/recordInfo?taskId=<taskId>
Authorization: Bearer <API_KEY>
```

## Parameters

| Parameter | Required | Description |
|---|---|---|
| `taskId` | yes | Task ID from createTask |

## Response

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_nano-banana-2_1790621023886ca4e4d",
    "model": "nano-banana-2",
    "state": "success",
    "param": "{\"model\":\"nano-banana-2\",\"callBackUrl\":\"\",\"input\":{\"prompt\":\"...\"}}",
    "resultJson": "{\"resultUrls\":[\"https://ai.aimixmedia.site/files/7496aef5292507f51b84cb2cb258d001.png\"]}",
    "failCode": "",
    "failMsg": "",
    "costTime": 104016,
    "completeTime": 1790621127902,
    "createTime": 1790621023886,
    "updateTime": 1790621127902,
    "progress": 100,
    "creditsConsumed": 0.02,
    "costUsd": "0.0200",
    "refunded": false,
    "filesExpired": false,
    "callback": null
  }
}
```

| Field | Meaning |
|---|---|
| `state` | Status — see the table below |
| `resultJson` | On `success` — a JSON string with `resultUrls` (file links, kept for 30 days) |
| `failCode`, `failMsg` | Error code and text on `fail` |
| `creditsConsumed` | Charged, USD (0 after a refund) |
| `refunded` | `true` — the money was refunded (task failed) |
| `callback` | Callback delivery status if a `callBackUrl` was set |
| `costTime`, `createTime`, `completeTime` | Duration and timestamps, ms |

## States

| state | Meaning |
|---|---|
| `waiting` | Accepted, waiting in the queue |
| `queuing` | Handed to the model |
| `generating` | Generating |
| `success` | Done ✓ |
| `fail` | Failed, money refunded |

A task that does not finish within 20 minutes becomes `fail`.

## Examples

```bash
curl "https://ai.aimixmedia.site/api/v1/jobs/recordInfo?taskId=task_nano-banana-2_1790621023886ca4e4d" \
  -H "Authorization: Bearer $API_KEY"
```

```python
import os, requests

r = requests.get(
    "https://ai.aimixmedia.site/api/v1/jobs/recordInfo",
    params={"taskId": "task_nano-banana-2_1790621023886ca4e4d"},
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
print(r.json())  # data.state, data.resultJson
```

```javascript
const r = await fetch("https://ai.aimixmedia.site/api/v1/jobs/recordInfo?taskId=task_nano-banana-2_1790621023886ca4e4d", {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
console.log(await r.json()); // data.state, data.resultJson
```

## Errors

| code | error | When |
|---|---|---|
| 401 | `unauthorized` | Missing or invalid key |
| 404 | `task_not_found` | No such task in your account |
| 422 | `validation_error` | `taskId` is missing |

---

<!-- source: https://docs.aimixmedia.site/en/endpoints/balance -->

# GET /api/v1/user/balance

> Current account balance in USD.

## Request

```http
GET https://ai.aimixmedia.site/api/v1/user/balance
Authorization: Bearer <API_KEY>
```

## Parameters

None.

## Response

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "balance": "4.9600",
    "currency": "USD"
  }
}
```

## Examples

```bash
curl "https://ai.aimixmedia.site/api/v1/user/balance" \
  -H "Authorization: Bearer $API_KEY"
```

```python
import os, requests

r = requests.get(
    "https://ai.aimixmedia.site/api/v1/user/balance",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
print(r.json())  # data.balance
```

```javascript
const r = await fetch("https://ai.aimixmedia.site/api/v1/user/balance", {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
console.log(await r.json()); // data.balance
```

## Errors

| code | error | When |
|---|---|---|
| 401 | `unauthorized` | Missing or invalid key |

---

<!-- source: https://docs.aimixmedia.site/en/endpoints/upload -->

# POST /api/v1/files/upload

> Uploads your photo and returns a link you can pass to the model input.

## Request

```http
POST https://ai.aimixmedia.site/api/v1/files/upload
Authorization: Bearer <API_KEY>
Content-Type: multipart/form-data
```

## Parameters

| Form field | Required | Description |
|---|---|---|
| `file` | yes | JPG, PNG or WebP, up to 15 MB |

The file is kept for 3 days. You can skip uploading and pass any public https link instead.

## Response

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "url": "https://ai.aimixmedia.site/files/5ee4b004b268e2d37c86c33552fe4f3e.jpg",
    "fileName": "5ee4b004b268e2d37c86c33552fe4f3e.jpg",
    "expiresInDays": 3
  }
}
```

## Examples

```bash
curl -X POST https://ai.aimixmedia.site/api/v1/files/upload \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@photo.jpg"
```

```python
import os, requests

r = requests.post(
    "https://ai.aimixmedia.site/api/v1/files/upload",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    files={"file": open("photo.jpg", "rb")},
)
print(r.json()["data"]["url"])
```

```javascript
import fs from "node:fs";

const fd = new FormData();
fd.append("file", new Blob([fs.readFileSync("photo.jpg")], { type: "image/jpeg" }), "photo.jpg");
const r = await fetch("https://ai.aimixmedia.site/api/v1/files/upload", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
  body: fd,
});
console.log((await r.json()).data.url);
```

## Errors

| code | error | When |
|---|---|---|
| 401 | `unauthorized` | Missing or invalid key |
| 422 | `validation_error` | Wrong format or file too large |

---

<!-- source: https://docs.aimixmedia.site/en/endpoints/other -->

# Other endpoints

> Task list and the model catalog as JSON.

## GET /api/v1/jobs/list

Recent account tasks. Parameters: `limit` (1–100, default 20), `state` (filter), `before` (pass `data.nextBefore` for the next page).

```bash
curl "https://ai.aimixmedia.site/api/v1/jobs/list?limit=5" \
  -H "Authorization: Bearer $API_KEY"
```

```python
import os, requests

r = requests.get(
    "https://ai.aimixmedia.site/api/v1/jobs/list",
    params={"limit": "5"},
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
print(r.json())  # data.items, data.nextBefore
```

```javascript
const r = await fetch("https://ai.aimixmedia.site/api/v1/jobs/list?limit=5", {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
console.log(await r.json()); // data.items, data.nextBefore
```

## GET /api/v1/models

Model catalog: IDs, prices and parameters. No key required.

```bash
curl https://ai.aimixmedia.site/api/v1/models
```

---

<!-- source: https://docs.aimixmedia.site/en/callbacks -->

# Callbacks

> We POST the result to your server when the task finishes — no recordInfo polling.

## How to enable

Pass `callBackUrl` to [createTask](https://docs.aimixmedia.site/en/endpoints/create-task). When the task becomes `success` or `fail`, we POST the same JSON that [recordInfo](https://docs.aimixmedia.site/en/endpoints/record-info) returns.

```http
POST <callBackUrl>
Content-Type: application/json
X-Signature: 3f1c9a…e07b        # signature, see below
X-Timestamp: 1790621128
X-Task-Id: task_nano-banana-2_1790621023886ca4e4d
X-Event: task.success           # or task.fail
X-Delivery-Attempt: 1
```

## What to reply

Any 2xx response within 15 seconds. Otherwise we retry after 30 s, 2 min and 10 min (4 attempts in total). An event may arrive twice — dedupe by `taskId`.

## Signature verification

The secret (`whsec_…`) is in [Dashboard → API keys](https://ai.aimixmedia.site/cabinet/keys#webhooks). The signature is the hex HMAC-SHA256 of the **raw** request body:

```python
import hmac, hashlib

def valid(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

# Flask: valid(request.get_data(), request.headers["X-Signature"], "whsec_...")
```

```javascript
import crypto from "node:crypto";

function valid(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// Express: app.post("/callback", express.raw({ type: "application/json" }), (req, res) => {
//   if (!valid(req.body, req.get("X-Signature"), process.env.WEBHOOK_SECRET)) return res.sendStatus(401);
//   const task = JSON.parse(req.body).data; res.send("ok");
// });
```

```php
<?php
$raw = file_get_contents('php://input');
$ok = hash_equals(hash_hmac('sha256', $raw, 'whsec_...'), $_SERVER['HTTP_X_SIGNATURE'] ?? '');
if (!$ok) { http_response_code(401); exit; }
$task = json_decode($raw, true)['data'];
```

Tip: reject requests whose `X-Timestamp` is older than 5 minutes.

## Limits

The URL must be public http(s). Local and private addresses (localhost, 10.x, 192.168.x, etc.) are rejected with code 422. Delivery status is in `recordInfo.data.callback` and in the dashboard.

---

<!-- source: https://docs.aimixmedia.site/en/errors -->

# Errors & limits

> Response codes, task errors and rate limits.

## Response format

Every response is JSON `{"code", "msg", "data"}`. Errors also have an `error` field. **Check `code` in the body** — the HTTP status can be 200 even on errors.

```json
{
  "code": 402,
  "msg": "Insufficient balance",
  "data": {
    "balance": "0.0100",
    "required": "0.0200",
    "topUpUrl": "https://ai.aimixmedia.site/cabinet/billing"
  },
  "error": "insufficient_balance"
}
```

## Error codes

| code | error | Meaning | What to do |
|---|---|---|---|
| 401 | `unauthorized` | Missing, invalid, disabled or deleted key | Check the key |
| 402 | `insufficient_balance` | Not enough balance | Top up |
| 403 | `account_blocked` | Account blocked | Contact support |
| 404 | `task_not_found` | No such task | Check `taskId` |
| 409 | `idempotency_conflict` | `Idempotency-Key` reused with a different body | Use a new key |
| 422 | `validation_error` | Invalid parameter | See `msg` |
| 422 | `unsupported_model` | Unknown model | [Model list](https://docs.aimixmedia.site/en/models) |
| 429 | `rate_limited` | Too many requests | Wait `Retry-After` seconds |
| 500 | `internal_error` | Our failure | Retry later |
| 505 | `model_disabled` | Model temporarily disabled | Pick another one |

## Task errors

If a task was created but failed, recordInfo shows `state: "fail"` and a `failCode`. The money is refunded automatically.

| failCode | Meaning |
|---|---|
| 501 | The model could not or refused to generate (reason in `failMsg`) |
| 504 | Timed out |
| 503 | Model temporarily unavailable |
| 422 | The model rejected the parameters (e.g. a photo could not be downloaded) |
| 500 | Could not get the result |

## Rate limits

| What | Limit |
|---|---|
| Creating tasks and uploads | 20 requests per 10 s per key |
| Reads (recordInfo, list, balance) | 100 requests per 10 s per key |
| Total per IP | 300 requests per 10 s |

Over the limit you get HTTP 429 with `Retry-After`. Concurrent generations are not limited: extra tasks wait in the queue. Need more? Contact us.

---

<!-- source: https://docs.aimixmedia.site/en/authentication -->

# Keys & authentication

> How to send the key and manage keys.

Send the key with every request:

```http
Authorization: Bearer sk-aim-XXXXXXXXXXXXXXXX
```

- Create keys in the [dashboard](https://ai.aimixmedia.site/cabinet/keys), up to 20 active. All keys share one balance.
- A key is shown once. Lost it? Create a new one.
- "Disable" is temporary (can be enabled again). "Delete" is permanent; spend history is kept.
- Never put the key in website or app code — call the API from your server.

---

<!-- source: https://docs.aimixmedia.site/en/idempotency -->

# Idempotency

> The Idempotency-Key header: a retried request does not create a second task or charge twice.

```http
Idempotency-Key: order-1001
```

Pass a unique value (order ID or UUID, up to 128 chars) to `createTask`.

| Situation | Result |
|---|---|
| Retry with the same key and body | Same `taskId`, `idempotentReplay: true`, no charge |
| Same key, different body | `409 idempotency_conflict` |

---

<!-- source: https://docs.aimixmedia.site/en/pricing -->

# Pricing & payment

> Pay per run in USD, refunds on failure, top up in RUB.

| Model | ID | Price |
|---|---|---|
| [Nano Banana 2](https://docs.aimixmedia.site/en/models/nano-banana-2) | `nano-banana-2` | $0.02 |
| [Nano Banana Pro](https://docs.aimixmedia.site/en/models/nano-banana-pro) | `nano-banana-pro` | $0.02 |
| [Nano Banana](https://docs.aimixmedia.site/en/models/nano-banana) | `google/nano-banana-edit` | $0.02 |
| [Nano Banana](https://docs.aimixmedia.site/en/models/nano-banana) | `google/nano-banana` | $0.02 |
| [GPT Image 2.5](https://docs.aimixmedia.site/en/models/gpt-image-2.5) | `gpt-image-2.5-image-to-image` | $0.02 |
| [GPT Image 2.5](https://docs.aimixmedia.site/en/models/gpt-image-2.5) | `gpt-image-2.5-text-to-image` | $0.02 |

- The price is charged when a task is created and fully refunded if it fails.
- Top up in the [dashboard](https://ai.aimixmedia.site/cabinet/billing): Russian cards, SBP, SberPay (YooKassa).
- Balance from code: [GET /api/v1/user/balance](https://docs.aimixmedia.site/en/endpoints/balance).