Модель изображений Midjourney (Beta), по умолчанию V8.2. Промпты и параметры — как на midjourney.com; каждое задание — набор из четырёх оригинальных PNG по одной цене, а апскейл, вариации, ремикс, зум и панорама идут через тот же эндпоинт.
Попробовать в песочнице →Быстрый старт
Асинхронное задание, как и другие вызовы изображений: отправили, получили 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
Чтобы начать, создайте API-ключ в консоли.
Параметры
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| 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} возвращает эти статусы; все поля описаны в разделе Асинхронные задачи. Опрашивайте каждые 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: задача не создаётся, ничего не списывается. О неудаче после того, как задача принята, сообщает эндпоинт задачи, а резерв возвращается полностью. Все коды перечислены в разделе Коды ошибок.
Ошибки при отправке
| 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 ровно то же, что возвращает эндпоинт опроса; запрос подписан, а при неудачной доставке повторяется. Общий адрес для всего аккаунта можно также задать в консоли, в разделе «Настройки → Вебхуки». Документация по вебхукам →
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"}'