# МиксМедиа API — полная документация

> Сгенерировано из https://docs.aimixmedia.site/

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

# Быстрый старт

> Первая картинка через API за 3 шага: ключ → задача → результат.

Базовый адрес: `https://ai.aimixmedia.site/api/v1`

## 1. Получите ключ

Войдите на [ai.aimixmedia.site](https://ai.aimixmedia.site/login) и откройте [Кабинет → API-ключи](https://ai.aimixmedia.site/cabinet/keys). Нажмите «Создать ключ» и скопируйте его. Новым пользователям — $5 на баланс.

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

## 2. Создайте задачу

```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":"Кот-астронавт в неоновом городе"}}'
```

```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": "Кот-астронавт в неоновом городе"
      }
    },
)
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": "Кот-астронавт в неоновом городе"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

Ответ — номер задачи:

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

## 3. Получите результат

Спрашивайте статус раз в 3–5 секунд, пока `state` не станет `success` или `fail`. Обычно это 1–2 минуты.

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

Готово, когда `state` = `success`. Ссылки на картинки — в `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
  }
}
```

Если задача завершилась ошибкой (`fail`), деньги возвращаются автоматически.

## Всё вместе: готовый скрипт

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

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

# 1. создать задачу
task = requests.post(f"{API}/jobs/createTask", headers=HEADERS, json={
    "model": "nano-banana-2",
    "input": {"prompt": "Кот-астронавт в неоновом городе"},
}).json()
task_id = task["data"]["taskId"]

# 2. ждать результат
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. ссылки на картинки
if info["state"] == "success":
    print(json.loads(info["resultJson"])["resultUrls"])
else:
    print("ошибка:", info["failMsg"])
```

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

// 1. создать задачу
const task = await fetch(`${API}/jobs/createTask`, {
  method: "POST", headers,
  body: JSON.stringify({ model: "nano-banana-2", input: { prompt: "Кот-астронавт в неоновом городе" } }),
}).then((r) => r.json());

// 2. ждать результат
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. ссылки на картинки
console.log(info.state === "success" ? JSON.parse(info.resultJson).resultUrls : info.failMsg);
```

## Что дальше

- [Модели](https://docs.aimixmedia.site/models) — параметры и примеры для каждой модели
- [Callback](https://docs.aimixmedia.site/callbacks) — мы сами пришлём результат на ваш сервер, без опроса
- [Ошибки и лимиты](https://docs.aimixmedia.site/errors)

---

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

# Все модели

> Какие модели доступны, их ID для API и цены.

В `createTask` передайте ID модели в поле `model`. У одной модели может быть несколько режимов — у каждого свой ID.

| Модель | Режим | ID | Цена |
|---|---|---|---|
| [Nano Banana 2](https://docs.aimixmedia.site/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/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/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/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 |

Цена — за одну картинку. Неудачные задачи бесплатны.

---

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

# Nano Banana 2

> Gemini 3.1 Flash Image: быстрая генерация и редактирование, точный текст на картинке, до 14 референсов.

Nano Banana 2 (Gemini 3.1 Flash Image) — основная image-модель Google. Хорошо держит сходство персонажа, пишет читаемый текст на изображениях, понимает длинные промпты (до 20 000 символов) и принимает до 14 изображений-референсов для редактирования, объединения и переноса стиля.

| Режим | ID | Цена |
|---|---|---|
| [Image to Image](#image-to-image) | `nano-banana-2` | $0.02 |
| [Text to Image](#text-to-image) | `nano-banana-2` | $0.02 |

Оба режима — одна модель `nano-banana-2`: если передать фото, она их отредактирует или использует как референсы.

## Image to Image

Загрузите фото и опишите, что изменить. ID: `nano-banana-2` · $0.02 за картинку · ~1.5 мин

**Параметры** (поле `input`)

| Параметр | Обязательный | Описание | Значения (по умолчанию — жирным) |
|---|---|---|---|
| `prompt` | да | Что нарисовать или что изменить | текст, до 20000 символов |
| `image_input` | да | Ссылки на ваши фото (https), до 14 шт. | `["https://…"]` |
| `aspect_ratio` | нет | Форма картинки | **`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` | нет | Качество: 1K быстрее, 2K детальнее | **`1K`** `2K` `4K` |
| `output_format` | нет | Формат файла | **`jpg`** `png` |

**Пример**

```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":"Сделай фон ночным неоновым городом","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": "Сделай фон ночным неоновым городом",
        "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": "Сделай фон ночным неоновым городом",
      "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

Опишите картинку — модель создаст её с нуля. ID: `nano-banana-2` · $0.02 за картинку · ~1.5 мин

**Параметры** (поле `input`)

| Параметр | Обязательный | Описание | Значения (по умолчанию — жирным) |
|---|---|---|---|
| `prompt` | да | Что нарисовать или что изменить | текст, до 20000 символов |
| `aspect_ratio` | нет | Форма картинки | **`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` | нет | Качество: 1K быстрее, 2K детальнее | **`1K`** `2K` `4K` |
| `output_format` | нет | Формат файла | **`jpg`** `png` |

**Пример**

```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":"Кот-астронавт в неоновом городе, кинематографичный свет","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": "Кот-астронавт в неоновом городе, кинематографичный свет",
        "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": "Кот-астронавт в неоновом городе, кинематографичный свет",
      "aspect_ratio": "auto",
      "resolution": "1K"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

## Результат

Как у любой задачи: запросите [recordInfo](https://docs.aimixmedia.site/endpoints/record-info) или получите [callback](https://docs.aimixmedia.site/callbacks). Ссылки на картинки — в `resultJson` (хранятся 30 дней).

Свои фото загрузите через [files/upload](https://docs.aimixmedia.site/endpoints/upload) или передайте любые публичные https-ссылки.

---

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

# Nano Banana Pro

> Gemini 3 Pro Image: максимальное качество, сложные композиции и инфографика.

Nano Banana Pro (Gemini 3 Pro Image) — старшая image-модель Google для сложных сцен, инфографики, постеров и фотореализма. Принимает до 8 референсов.

| Режим | ID | Цена |
|---|---|---|
| [Image to Image](#image-to-image) | `nano-banana-pro` | $0.02 |
| [Text to Image](#text-to-image) | `nano-banana-pro` | $0.02 |

Оба режима — одна модель `nano-banana-pro`: если передать фото, она их отредактирует или использует как референсы.

## Image to Image

Загрузите фото и опишите, что изменить. ID: `nano-banana-pro` · $0.02 за картинку · ~2.5 мин

**Параметры** (поле `input`)

| Параметр | Обязательный | Описание | Значения (по умолчанию — жирным) |
|---|---|---|---|
| `prompt` | да | Что нарисовать или что изменить | текст, до 10000 символов |
| `image_input` | да | Ссылки на ваши фото (https), до 8 шт. | `["https://…"]` |
| `aspect_ratio` | нет | Форма картинки | **`1:1`** `2:3` `3:2` `3:4` `4:3` `4:5` `5:4` `9:16` `16:9` `21:9` `auto` |
| `resolution` | нет | Качество: 1K быстрее, 2K детальнее | **`1K`** `2K` `4K` |
| `output_format` | нет | Формат файла | **`png`** `jpg` |

**Пример**

```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":"Сделай фон ночным неоновым городом","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": "Сделай фон ночным неоновым городом",
        "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": "Сделай фон ночным неоновым городом",
      "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

Опишите картинку — модель создаст её с нуля. ID: `nano-banana-pro` · $0.02 за картинку · ~2.5 мин

**Параметры** (поле `input`)

| Параметр | Обязательный | Описание | Значения (по умолчанию — жирным) |
|---|---|---|---|
| `prompt` | да | Что нарисовать или что изменить | текст, до 10000 символов |
| `aspect_ratio` | нет | Форма картинки | **`1:1`** `2:3` `3:2` `3:4` `4:3` `4:5` `5:4` `9:16` `16:9` `21:9` `auto` |
| `resolution` | нет | Качество: 1K быстрее, 2K детальнее | **`1K`** `2K` `4K` |
| `output_format` | нет | Формат файла | **`png`** `jpg` |

**Пример**

```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":"Кот-астронавт в неоновом городе, кинематографичный свет","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": "Кот-астронавт в неоновом городе, кинематографичный свет",
        "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": "Кот-астронавт в неоновом городе, кинематографичный свет",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

## Результат

Как у любой задачи: запросите [recordInfo](https://docs.aimixmedia.site/endpoints/record-info) или получите [callback](https://docs.aimixmedia.site/callbacks). Ссылки на картинки — в `resultJson` (хранятся 30 дней).

Свои фото загрузите через [files/upload](https://docs.aimixmedia.site/endpoints/upload) или передайте любые публичные https-ссылки.

---

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

# Nano Banana

> Лёгкая и быстрая модель Google: генерация по тексту и редактирование фото по инструкции.

| Режим | ID | Цена |
|---|---|---|
| [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

Загрузите фото и опишите, что изменить. ID: `google/nano-banana-edit` · $0.02 за картинку · ~1.5 мин

**Параметры** (поле `input`)

| Параметр | Обязательный | Описание | Значения (по умолчанию — жирным) |
|---|---|---|---|
| `prompt` | да | Что нарисовать или что изменить | текст, до 5000 символов |
| `image_urls` | да | Ссылки на ваши фото (https), до 10 шт. | `["https://…"]` |
| `aspect_ratio` | нет | Форма картинки | **`1:1`** `9:16` `16:9` `3:4` `4:3` `3:2` `2:3` `5:4` `4:5` `21:9` `auto` |
| `output_format` | нет | Формат файла | **`png`** `jpeg` |

**Пример**

```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":"Сделай фон ночным неоновым городом","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": "Сделай фон ночным неоновым городом",
        "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": "Сделай фон ночным неоновым городом",
      "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

Опишите картинку — модель создаст её с нуля. ID: `google/nano-banana` · $0.02 за картинку · ~1 мин

**Параметры** (поле `input`)

| Параметр | Обязательный | Описание | Значения (по умолчанию — жирным) |
|---|---|---|---|
| `prompt` | да | Что нарисовать или что изменить | текст, до 5000 символов |
| `aspect_ratio` | нет | Форма картинки | **`1:1`** `9:16` `16:9` `3:4` `4:3` `3:2` `2:3` `5:4` `4:5` `21:9` `auto` |
| `output_format` | нет | Формат файла | **`png`** `jpeg` |

**Пример**

```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":"Кот-астронавт в неоновом городе, кинематографичный свет","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": "Кот-астронавт в неоновом городе, кинематографичный свет",
        "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": "Кот-астронавт в неоновом городе, кинематографичный свет",
      "aspect_ratio": "1:1"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

## Результат

Как у любой задачи: запросите [recordInfo](https://docs.aimixmedia.site/endpoints/record-info) или получите [callback](https://docs.aimixmedia.site/callbacks). Ссылки на картинки — в `resultJson` (хранятся 30 дней).

Свои фото загрузите через [files/upload](https://docs.aimixmedia.site/endpoints/upload) или передайте любые публичные https-ссылки.

---

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

# GPT Image 2.5

> OpenAI GPT Image 2.5: фотореализм, чистый текст, продуктовые кадры и точное редактирование фото.

| Режим | ID | Цена |
|---|---|---|
| [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

Загрузите фото и опишите, что изменить. ID: `gpt-image-2.5-image-to-image` · $0.02 за картинку · ~2 мин

**Параметры** (поле `input`)

| Параметр | Обязательный | Описание | Значения (по умолчанию — жирным) |
|---|---|---|---|
| `prompt` | да | Что нарисовать или что изменить | текст, до 20000 символов |
| `input_urls` | да | Ссылки на ваши фото (https), до 16 шт. | `["https://…"]` |
| `aspect_ratio` | нет | Форма картинки | **`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` | нет | Качество: 1K быстрее, 2K детальнее | **`1K`** |
| `background` | нет | Фон: `transparent` — прозрачный | **`auto`** `opaque` `transparent` |

**Пример**

```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":"Сделай фон ночным неоновым городом","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": "Сделай фон ночным неоновым городом",
        "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": "Сделай фон ночным неоновым городом",
      "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

Опишите картинку — модель создаст её с нуля. ID: `gpt-image-2.5-text-to-image` · $0.02 за картинку · ~1.5 мин

**Параметры** (поле `input`)

| Параметр | Обязательный | Описание | Значения (по умолчанию — жирным) |
|---|---|---|---|
| `prompt` | да | Что нарисовать или что изменить | текст, до 20000 символов |
| `aspect_ratio` | нет | Форма картинки | **`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` | нет | Качество: 1K быстрее, 2K детальнее | **`1K`** |
| `background` | нет | Фон: `transparent` — прозрачный | **`auto`** `opaque` `transparent` |

**Пример**

```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":"Кот-астронавт в неоновом городе, кинематографичный свет","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": "Кот-астронавт в неоновом городе, кинематографичный свет",
        "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": "Кот-астронавт в неоновом городе, кинематографичный свет",
      "aspect_ratio": "auto",
      "resolution": "1K"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

## Результат

Как у любой задачи: запросите [recordInfo](https://docs.aimixmedia.site/endpoints/record-info) или получите [callback](https://docs.aimixmedia.site/callbacks). Ссылки на картинки — в `resultJson` (хранятся 30 дней).

Свои фото загрузите через [files/upload](https://docs.aimixmedia.site/endpoints/upload) или передайте любые публичные https-ссылки.

---

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

# POST /api/v1/jobs/createTask

> Создаёт задачу генерации и сразу возвращает её номер (taskId). Цена списывается сразу и возвращается при ошибке.

## Запрос

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

## Параметры

| Поле | Обязательное | Описание |
|---|---|---|
| `model` | да | ID модели, например `nano-banana-2` — [список](https://docs.aimixmedia.site/models) |
| `input` | да | Параметры модели: `prompt`, фото и т. д. — см. страницу модели |
| `callBackUrl` | нет | Куда прислать результат, когда задача завершится — [callback](https://docs.aimixmedia.site/callbacks) |

Необязательный заголовок `Idempotency-Key` защищает от дублей при повторе запроса — [подробнее](https://docs.aimixmedia.site/idempotency).

## Ответ

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

## Примеры

```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":"Постер «Лето в Москве»","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": "Постер «Лето в Москве»",
        "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": "Постер «Лето в Москве»",
      "aspect_ratio": "3:4"
    }
  }),
});
console.log(await r.json()); // { code: 200, data: { taskId: "..." } }
```

## Ошибки

| code | error | Когда |
|---|---|---|
| 401 | `unauthorized` | Нет ключа или он неверный |
| 402 | `insufficient_balance` | Не хватает денег на балансе |
| 422 | `validation_error` | Неверный параметр (что именно — в `msg`) |
| 422 | `unsupported_model` | Нет такой модели |
| 429 | `rate_limited` | Слишком много запросов |

Все коды — в разделе [Ошибки и лимиты](https://docs.aimixmedia.site/errors).

---

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

# GET /api/v1/jobs/recordInfo

> Статус задачи и результат. Спрашивайте раз в 3–5 секунд, пока state не станет success или fail.

## Запрос

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

## Параметры

| Параметр | Обязательный | Описание |
|---|---|---|
| `taskId` | да | Номер задачи из createTask |

## Ответ

```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
  }
}
```

| Поле | Что это |
|---|---|
| `state` | Статус — см. таблицу ниже |
| `resultJson` | При `success` — строка JSON с `resultUrls` (ссылки на файлы, хранятся 30 дней) |
| `failCode`, `failMsg` | Код и текст ошибки при `fail` |
| `creditsConsumed` | Сколько списано, USD (0 после возврата) |
| `refunded` | `true` — деньги вернули (задача не удалась) |
| `callback` | Статус доставки callback, если был `callBackUrl` |
| `costTime`, `createTime`, `completeTime` | Время выполнения и отметки времени, мс |

## Статусы

| state | Что значит |
|---|---|
| `waiting` | Принята, ждёт очереди |
| `queuing` | Передана модели |
| `generating` | Генерируется |
| `success` | Готово ✓ |
| `fail` | Ошибка, деньги возвращены |

Если задача не завершилась за 20 минут, она становится `fail`.

## Примеры

```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
```

## Ошибки

| code | error | Когда |
|---|---|---|
| 401 | `unauthorized` | Нет ключа или он неверный |
| 404 | `task_not_found` | Нет такой задачи в вашем аккаунте |
| 422 | `validation_error` | Не передан `taskId` |

---

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

# GET /api/v1/user/balance

> Текущий баланс аккаунта в долларах.

## Запрос

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

## Параметры

Нет.

## Ответ

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

## Примеры

```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
```

## Ошибки

| code | error | Когда |
|---|---|---|
| 401 | `unauthorized` | Нет ключа или он неверный |

---

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

# POST /api/v1/files/upload

> Загружает ваше фото и возвращает ссылку, которую можно передать в input модели.

## Запрос

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

## Параметры

| Поле формы | Обязательное | Описание |
|---|---|---|
| `file` | да | JPG, PNG или WebP, до 15 МБ |

Файл хранится 3 дн. Можно не загружать, а сразу передать любую публичную https-ссылку.

## Ответ

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

## Примеры

```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);
```

## Ошибки

| code | error | Когда |
|---|---|---|
| 401 | `unauthorized` | Нет ключа или он неверный |
| 422 | `validation_error` | Не тот формат или слишком большой файл |

---

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

# Другие методы

> Список задач и каталог моделей в JSON.

## GET /api/v1/jobs/list

Последние задачи аккаунта. Параметры: `limit` (1–100, по умолчанию 20), `state` (фильтр), `before` (для следующей страницы передайте `data.nextBefore`).

```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

Каталог моделей: ID, цены и параметры. Ключ не нужен.

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

---

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

# Callback

> Мы сами пришлём результат на ваш сервер, когда задача завершится, — без опроса recordInfo.

## Как включить

Передайте `callBackUrl` в [createTask](https://docs.aimixmedia.site/endpoints/create-task). Когда задача станет `success` или `fail`, мы отправим на этот адрес POST с тем же JSON, что возвращает [recordInfo](https://docs.aimixmedia.site/endpoints/record-info).

```http
POST <callBackUrl>
Content-Type: application/json
X-Signature: 3f1c9a…e07b        # подпись, см. ниже
X-Timestamp: 1790621128
X-Task-Id: task_nano-banana-2_1790621023886ca4e4d
X-Event: task.success           # или task.fail
X-Delivery-Attempt: 1
```

## Что ответить

Любой ответ 2xx в течение 15 секунд. Иначе повторим: через 30 с, 2 мин и 10 мин (всего 4 попытки). Одно событие может прийти дважды — обрабатывайте по `taskId`.

## Проверка подписи

Секрет (`whsec_…`) — в [Кабинете → API-ключи](https://ai.aimixmedia.site/cabinet/keys#webhooks). Подпись = HMAC-SHA256 от **сырого** тела запроса, в hex:

```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'];
```

Совет: отклоняйте запросы, где `X-Timestamp` старше 5 минут.

## Ограничения

Адрес должен быть публичным http(s). Локальные и внутренние адреса (localhost, 10.x, 192.168.x и т. п.) отклоняются с кодом 422. Статус доставки виден в `recordInfo.data.callback` и в кабинете.

---

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

# Ошибки и лимиты

> Коды ответов, ошибки задач и лимиты запросов.

## Формат ответа

Каждый ответ — JSON вида `{"code", "msg", "data"}`. При ошибке есть ещё поле `error`. **Смотрите на `code` в теле** — HTTP-статус бывает 200 и при ошибке.

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

## Коды ошибок

| code | error | Что значит | Что делать |
|---|---|---|---|
| 401 | `unauthorized` | Нет ключа, он неверный, отключён или удалён | Проверьте ключ |
| 402 | `insufficient_balance` | Не хватает денег | Пополните баланс |
| 403 | `account_blocked` | Аккаунт заблокирован | Напишите в поддержку |
| 404 | `task_not_found` | Нет такой задачи | Проверьте `taskId` |
| 409 | `idempotency_conflict` | `Idempotency-Key` уже использован с другим телом | Возьмите новый ключ |
| 422 | `validation_error` | Неверный параметр | Смотрите `msg` |
| 422 | `unsupported_model` | Нет такой модели | [Список моделей](https://docs.aimixmedia.site/models) |
| 429 | `rate_limited` | Слишком много запросов | Подождите `Retry-After` секунд |
| 500 | `internal_error` | Сбой у нас | Повторите позже |
| 505 | `model_disabled` | Модель временно отключена | Возьмите другую |

## Ошибки задач

Если задача создана, но не выполнилась, в recordInfo будет `state: "fail"` и код в `failCode`. Деньги возвращаются автоматически.

| failCode | Что значит |
|---|---|
| 501 | Модель не смогла или отказалась генерировать (причина в `failMsg`) |
| 504 | Слишком долго |
| 503 | Модель временно недоступна |
| 422 | Модель не приняла параметры (например, не скачалось фото) |
| 500 | Не удалось получить результат |

## Лимиты

| Что | Лимит |
|---|---|
| Создание задач и загрузка файлов | 20 запросов за 10 с на ключ |
| Чтение (recordInfo, list, balance) | 100 запросов за 10 с на ключ |
| Всего с одного IP | 300 запросов за 10 с |

Сверх лимита — HTTP 429 и заголовок `Retry-After`. Число одновременных генераций не ограничено: лишние задачи ждут в очереди. Нужно больше — напишите нам.

---

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

# Ключи и авторизация

> Как передавать ключ и управлять ключами.

Передавайте ключ в каждом запросе:

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

- Ключи создаются в [кабинете](https://ai.aimixmedia.site/cabinet/keys), до 20 активных. Баланс общий на все ключи.
- Ключ показывается один раз. Потеряли — создайте новый.
- «Отключить» — временно (можно включить обратно). «Удалить» — навсегда, история расходов сохраняется.
- Не вставляйте ключ в код сайта или приложения — вызывайте API со своего сервера.

---

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

# Защита от дублей

> Заголовок Idempotency-Key: повтор запроса не создаст вторую задачу и не спишет деньги дважды.

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

Передайте уникальное значение (номер заказа или UUID, до 128 символов) в `createTask`.

| Ситуация | Результат |
|---|---|
| Повтор с тем же ключом и телом | Тот же `taskId`, `idempotentReplay: true`, без списания |
| Тот же ключ, другое тело | `409 idempotency_conflict` |

---

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

# Цены и оплата

> Оплата за каждый запуск в долларах, возврат при ошибке, пополнение в рублях.

| Модель | ID | Цена |
|---|---|---|
| [Nano Banana 2](https://docs.aimixmedia.site/models/nano-banana-2) | `nano-banana-2` | $0.02 |
| [Nano Banana Pro](https://docs.aimixmedia.site/models/nano-banana-pro) | `nano-banana-pro` | $0.02 |
| [Nano Banana](https://docs.aimixmedia.site/models/nano-banana) | `google/nano-banana-edit` | $0.02 |
| [Nano Banana](https://docs.aimixmedia.site/models/nano-banana) | `google/nano-banana` | $0.02 |
| [GPT Image 2.5](https://docs.aimixmedia.site/models/gpt-image-2.5) | `gpt-image-2.5-image-to-image` | $0.02 |
| [GPT Image 2.5](https://docs.aimixmedia.site/models/gpt-image-2.5) | `gpt-image-2.5-text-to-image` | $0.02 |

- Цена списывается при создании задачи и полностью возвращается, если задача не удалась.
- Пополнение — в [кабинете](https://ai.aimixmedia.site/cabinet/billing): карты РФ, СБП, SberPay (ЮKassa).
- Баланс из кода: [GET /api/v1/user/balance](https://docs.aimixmedia.site/endpoints/balance).