# Midjourney — /images/generations

Модель изображений Midjourney (Beta), по умолчанию V8.2. Промпты и параметры — как на midjourney.com; каждое задание — набор из четырёх оригинальных PNG по одной цене, а апскейл, вариации, ремикс, зум и панорама идут через тот же эндпоинт.

**Эндпоинт:** `POST https://kovapi.com/v1/images/generations`

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

Асинхронное задание, как и другие вызовы изображений: отправили, получили id, опрашиваете результат. Три шага ниже — текст в изображение, результат и апскейл изображения 2.

**Шаг 1: отправьте текст в изображение (параметры в конце промпта)**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2", "speed": "fast"}'
```

Ответ (HTTP 202)

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1795248736,
  "model": "midjourney"
}
```

**Шаг 2 · Опрашивайте каждые 2–3 секунды, пока `status` не станет `succeeded` или `failed`**

```
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

В data четыре оригинальных PNG (по порядку 1–4); в actions — что можно сделать дальше.

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1795248736,
  "model": "midjourney",
  "data": [
    {"url": "https://img.kovapi.com/i/5b2c0e8a1f3d4c6b9a7e2d1c0b3a4f5e.png"},
    {"url": "https://img.kovapi.com/i/0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f.png"},
    {"url": "https://img.kovapi.com/i/7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d.png"},
    {"url": "https://img.kovapi.com/i/3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b.png"}
  ],
  "usage": {"images": 4, "model": "midjourney", "speed": "fast", "action": "imagine"},
  "actions": ["upscale", "vary", "remix", "reroll", "zoom", "pan"]
}
```

**Шаг 3: продолжите задание — апскейл изображения 2 (тот же эндпоинт с task_id, action и index)**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "midjourney", "task_id": "img_7f3c9a1e2b4d6f8a0c1e3b5d", "action": "upscale", "index": 2, "mode": "subtle"}'
```

**Полный пример (Python: отправить, дождаться, сохранить на диск)**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

def run(body):
    job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json=body).json()
    if "error" in job:
        raise SystemExit(job["error"]["message"])
    while job["status"] not in ("succeeded", "failed"):
        time.sleep(5)
        job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()
    if job["status"] == "failed":
        raise SystemExit(job["error"]["message"])
    return job

# текст в изображение, затем апскейл изображения 2
grid = run({"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2"})
print([d["url"] for d in grid["data"]], grid["actions"])
big = run({"model": "midjourney", "task_id": grid["id"], "action": "upscale", "index": 2})
with open("midjourney-2.png", "wb") as f:
    f.write(requests.get(big["data"][0]["url"]).content)
```

## Аутентификация
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Параметры

| Параметр | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| model | string | Да | ID модели, здесь midjourney. |
| prompt | string | Нет | Промпт; параметры Midjourney — в конце, как на midjourney.com (--ar, --v, --niji, --s, --c, --w, --seed, --no, --sref, --oref, --cref, --iw, --raw, --tile, --hd, --draft). Обязателен для текста в изображение, remix и edit; до 6000 символов. --repeat и {a, b} не поддерживаются. |
| speed | string | Нет | `relax` (по умолчанию, $0.045), `fast` ($0.055) или `turbo` ($0.10). Можно писать --relax / --fast / --turbo в промпте; это поле важнее. |
| images | array | Нет | Изображения-подсказки, до 5, как URL, data: URI или base64; ставятся перед промптом, как в Midjourney (вес — через --iw). При action blend — 2–5 изображений для смешивания. |
| size | string | Нет | Пропорция (например, `3:2`) или размер в пикселях; превращается в --ar, если в промпте его нет (--ar в промпте важнее). Edit без того и другого сохраняет пропорцию исходного изображения. |
| task_id | string | Нет | Задание, которое продолжаете (img_..., завершено, не старше 7 дней). |
| action | string | Нет | `upscale` (2x, mode subtle / creative), `vary` (strength strong / subtle), `remix` (новый промпт), `reroll`, `zoom` (отдаление 1–2), `pan` (direction), `inpaint` (mask); без task_id — `blend` (2–5 изображений) и `edit` (одно изображение и инструкция). |
| index | integer | Нет | Какое изображение (1–4); для одного апскейла можно не указывать. |
| n | integer | Нет | Только 1: одно задание — набор из четырёх изображений, оплачивается один раз. |
| callback_url | string | Нет | Куда отправить результат, когда задача завершится; подробнее — в разделе о вебхуках ниже. |

## Действия (task_id + action)

Продолжение завершённого задания (не старше 7 дней), по одному действию на каждую кнопку официального приложения; результат — новое задание по цене выбранной скорости.

| action | Поля | Что делает |
| --- | --- | --- |
| upscale | index, mode | Апскейл 2x: mode `subtle` (по умолчанию, детали сохраняются) или `creative` (добавляет детали); одно изображение. |
| vary | index, strength | Четыре вариации изображения index: strength `strong` (по умолчанию) или `subtle`. |
| remix | index, prompt, strength | Сохраняет композицию и переделывает по новому промпту; четыре изображения. |
| reroll | — | Заново генерирует весь набор с тем же промптом; четыре изображения. |
| zoom | index, zoom | Отдаляет кадр: zoom 1–2 (по умолчанию 2); четыре изображения. |
| pan | index, direction | Расширяет влево / вправо / вверх / вниз (left / right / up / down); четыре изображения. |
| inpaint | index, mask, prompt | Перерисовывает только белую (или прозрачную) область маски; маска в пропорции изображения масштабируется под его размер. Доступно, когда в actions задания есть inpaint. |
| blend | images (2–5) | Без task_id: смешивает 2–5 изображений в набор из четырёх; пропорцию укажите в prompt (например, `--ar 3:2`). |
| edit | image, prompt | Без task_id: одно изображение и фраза о том, что изменить (V8.2 / 8.1); четыре изображения в пропорции исходного, если в промпте нет --ar и не передан size. |

## Цена

Оплата за задание — набор из четырёх изображений (при апскейле — одно); действия стоят как одно задание на выбранной скорости. --hd (семейство V8) — вдвое дороже, --draft на V7 — за полцены (с округлением вниз до целых кредитов); вариации и перегенерация HD-набора тоже вдвое дороже. Резервируется при отправке и полностью возвращается при неудаче.

| Скорость | Кредитов за изображение | USD за изображение |
| --- | --- | --- |
| relax (по умолчанию) | 9 | $0.045 |
| fast | 11 | $0.055 |
| turbo | 20 | $0.10 |

## Размеры, версии и ограничения

- Вы получаете оригинальные PNG от Midjourney (с метаданными контента, которые пишет сама Midjourney), без обрезки и масштабирования. Размер зависит от пропорции: 1:1 — 1024×1024, 3:2 — 1344×896, 16:9 — 1456×816; --hd и апскейл — 2x.

- Версии: без указания — V8.2; --v 8.1 / 8 / 7 / 6.1 / 6 или --niji 7 / 6. --hd только для семейства V8, --draft только для V7 и V8 (черновик V8 оплачивается полностью и может прийти в виде 24 изображений).

- --repeat / --r и перестановки {a, b} (один запрос превращается в несколько заданий) не поддерживаются; n должно быть 1.

- До 5 изображений-подсказок, они ставятся перед промптом, как в Midjourney (вес — через --iw); референсы стиля — в --sref <URL>, омни-референсы V7 — в --oref <URL>.

- Результаты и загруженные изображения хранятся 7 дней; более старые задания продолжить нельзя.

- Describe (изображение в промпт) и видео Midjourney пока недоступны.

## Статус задачи и поля ответа

`GET /v1/images/jobs/{id}` возвращает эти статусы; все поля описаны в разделе [Асинхронные задачи](https://docs.kovapi.com/ru/guide/async-jobs#fields). Опрашивайте каждые 2–3 секунды или используйте вебхук.

| Статус | Что значит |
| --- | --- |
| queued | В очереди. В ответе есть `queue_position` (сколько задач впереди) и `eta_seconds` (ожидаемое время ожидания). |
| processing | Генерируется. |
| succeeded | Готово. Результат в `data[0].url`, детали оплаты в `usage`. |
| failed | Ошибка. Причина в `error`; зарезервированные кредиты возвращаются полностью. |

Один аккаунт выполняет до 50 задач одновременно; остальные ждут в порядке отправки, а задача, не начавшаяся за 15 минут, завершается ошибкой с полным возвратом. Записи о задачах хранятся 3 дня, ссылки на изображения — 7 дней.

## Сколько ждать

Замеры 11-21: четыре изображения — около 1,5–2 минут на relax и fast, около 1,5 на turbo; апскейл около 2 минут, зум и панорама около 1,3; с изображениями-подсказками или blend около 4. В часы пик дольше.

## Ошибки и возвраты

Ошибка при отправке сразу возвращается как HTTP 4xx / 5xx: задача не создаётся, ничего не списывается. О неудаче после того, как задача принята, сообщает эндпоинт задачи, а резерв возвращается полностью. Все коды перечислены в разделе [Коды ошибок](https://docs.kovapi.com/ru/guide/errors).

### Ошибки при отправке

| HTTP | code | Причина | Что делать |
| --- | --- | --- | --- |
| 400 | invalid_request | Не удаётся прочитать референсное изображение (битая ссылка, не изображение, больше 16MB…; в `message` указано, какое и почему), в `/v1/images/edits` нет референсного изображения, тело запроса — не JSON-объект или `n` — не целое число. | Исправьте то, что указано в `message`, и отправьте снова. |
| 400 | unsupported_action | Не удаётся прочитать референсное изображение (битая ссылка, не изображение, больше 16MB…; в `message` указано, какое и почему), в `/v1/images/edits` нет референсного изображения, тело запроса — не JSON-объект или `n` — не целое число. | Исправьте то, что указано в `message`, и отправьте снова. |
| 404 | task_not_found | Не удаётся прочитать референсное изображение (битая ссылка, не изображение, больше 16MB…; в `message` указано, какое и почему), в `/v1/images/edits` нет референсного изображения, тело запроса — не JSON-объект или `n` — не целое число. | Исправьте то, что указано в `message`, и отправьте снова. |
| 401 | invalid_api_key | Ключ не существует, удалён или отключён, либо отключён аккаунт. | Проверьте ключ на странице API Keys в консоли. |
| 402 | insufficient_quota | Баланса не хватает, чтобы зарезервировать стоимость этого запроса. Шлюз сначала резервирует максимально возможную стоимость запроса, поэтому ошибка может возникнуть и при всплеске одновременных вызовов. | Если был всплеск запросов, подождите несколько секунд и повторите; в остальных случаях пополните баланс. |
| 429 | rate_limit_exceeded | Превышен лимит запросов в минуту, заданный для этого ключа (считается за последние 60 секунд). Заголовка `Retry-After` нет. | Подождите несколько секунд и повторите или увеличьте лимит ключа в консоли. |
| 503 | service_unavailable | Временный сбой на нашей стороне, например при сохранении референсного файла; `/v1/responses` также отвечает 503 с `Retry-After`, когда временно не может принять запрос. | Повторите чуть позже. |

### Неудачные задачи (`status` — `failed`)

| code | Когда возникает | Что делать |
| --- | --- | --- |
| moderation_blocked | Изображение: система безопасности поставщика модели отклонила промпт или референсное изображение (код может быть и `content_policy_violation`). | Перепишите промпт или замените референс; повторная отправка без изменений обычно снова отклоняется. |
| upstream_error | Любая другая ошибка: автоматические повторы не помогли, задача ждала 15 минут и так и не запустилась, поставщик отказал без объяснения причины и т. п.; что именно произошло, указано в `message`. | Обычно повторная отправка проходит успешно. |

## Вебхуки вместо опроса

Добавьте при отправке `callback_url` — как только задача завершится, успешно или с ошибкой, шлюз отправит на этот URL ровно то же, что возвращает эндпоинт опроса; запрос подписан, а при неудачной доставке повторяется. Общий адрес для всего аккаунта можно также задать в консоли, в разделе «Настройки → Вебхуки». [Документация по вебхукам →](https://docs.kovapi.com/ru/webhooks)

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2", "callback_url": "https://your-domain.com/webhook"}'
```
