У Midjourney нет официального публичного API, поэтому на практике подключают сторонние обёртки. Пути, поля и конечные автоматы у разных провайдеров не совпадают, но базовая схема близка: отправить задачу и получить ID, опрашивать статус, после успеха скачать изображение, при необходимости сделать апскейл или вариант. Статья следует этой цепочке и делает акцент на различиях, где легко ошибиться, и на границах комплаенса.

Товарные знаки: Midjourney — товарный знак Midjourney, Inc.; Discord — товарный знак Discord Inc. Статья носит технический характер и не означает сотрудничества, представительства или одобрения. Midjourney официально не предоставляет API; условия и стабильность сторонних интерфейсов нужно проверять самостоятельно.

1. Сначала выберите провайдера, потом пишите код

У сторонних интерфейсов Midjourney нет единого стандарта. Даже при одинаковом действии «отправить задачу» один сервис возвращает task_id, другой — job_id; один использует /imagine, другой — /v1/midjourney/imagine; у одних апскейл и варианты — отдельные задачи, у других — интерфейс действий. При выборе уточните шесть вещей:

  • Способ аутентификации, стабильность Base URL и наличие версионированных путей.
  • Какие типы задач поддерживаются: текст в изображение, апскейл, варианты, перерисовка, смешивание, описание.
  • Поля статуса и перечень конечных состояний, различаются ли успех, ошибка, отказ модерации и тайм-аут.
  • Срок хранения результатов и ограничения скачивания, поддерживается ли callback.
  • Правила параллельности, очереди и лимитов, оплачиваются ли неудачи.
  • Надёжность провайдера и механизм выхода, возможны ли короткий договор и удаление данных.

Чем ближе интерфейс к вашей системе, тем дешевле миграция. Смотрите не только демонстрации, но и документацию по кодам ошибок и возможностям запроса задач.

2. Аутентификация и правила запросов

Обычная практика — API Key в заголовке запроса и JSON-тело. Конкретное имя заголовка уточняйте в документации: встречаются Authorization: Bearer, X-API-Key и собственные поля. Храните ключ, Base URL и тайм-аут в конфигурации, а не в разбросанном по коду виде.

Перед вызовом проверьте три вещи: тестовая это среда или production, привязан ли ключ к IP или квоте, проходит ли запрос через корпоративный прокси. Многие 401 и 403 вызваны не ошибкой ключа, а неверной средой или изменёнными прокси заголовками.

3. Отправка задачи: prompt и параметры

Типичный запрос на отправку выглядит так; поля приведены только как пример:

export MJ_API_KEY="ваш-ключ-провайдера"
export MJ_BASE_URL="https://provider.example.com"

curl -sS -X POST "$MJ_BASE_URL/v1/midjourney/imagine" \
  -H "Authorization: Bearer $MJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "minimalist product photo of a ceramic cup, soft window light --ar 4:3",
    "aspect_ratio": "4:3",
    "callback_url": "https://api.example.com/callbacks/mj"
  }'

Передаются ли параметры --ar, --v, --style из промпта, зависит от провайдера. Одни выносят соотношение сторон в отдельное поле, другие разбирают prompt напрямую. Не предполагайте, что параметр обязательно сработал: после отправки сверьтесь с деталями задачи.

После успешной отправки сразу запишите в таблицу задач ID задачи, номер бизнес-заказа, промпт, параметры, время отправки и оператора. От этой записи зависят последующие опросы, повторы, сверка и распределение затрат.

4. Опрос: конечный автомат и задержки

Статус Значение Рекомендация
queued В очереди Ждать, не отправлять повторно
running Генерация идёт Опрашивать с задержкой
succeeded Успех Прочитать результат и сразу сохранить
failed Ошибка Записать код ошибки, решить, можно ли повторять
moderated Отказ модерации Изменить промпт, не повторять как есть
expired Тайм-аут или истёкшая ссылка Проверить детали задачи, при необходимости отправить заново

Начинайте опрос с 3–5 секунд и постепенно увеличивайте интервал до 15–30 секунд, задав общий тайм-аут. Не опрашивайте раз в секунду и не запускайте несколько экземпляров на одну задачу. После конечного состояния опрос прекращается, а финальный статус и адрес результата записываются в базу.

Если провайдер поддерживает Webhook, его можно использовать как основное уведомление, но обязательно с проверкой подписи, идемпотентностью и периодическим опросом как страховкой. Потеря callback у обёрток встречается нередко.

5. Скачивание и сохранение

Адрес изображения после успеха обычно имеет срок действия — от нескольких минут до нескольких дней, иногда это временный подписанный URL. Не вставляйте его напрямую в страницу и не передавайте клиенту.

Правильный порядок: получив успешный статус, сразу скачать файл, сохранить в собственное объектное хранилище, записать ID задачи, путь объекта, размер файла, контрольную сумму и время скачивания, а затем записать внутренний адрес в бизнес-базу. Для скачивания задайте тайм-аут, повторы и лимит параллельности; большие изображения лучше проксировать через сервер, чтобы избежать проблем с CORS и утечки ссылок.

Midjourney обычно возвращает сетку из четырёх изображений и отдельные увеличенные варианты. При сохранении называйте сетку и апскейлы по-разному, сохраняя исходный ID задачи, чтобы позже можно было сопоставить их с вариантами и перерисовкой.

6. Апскейл, варианты и перерисовка

Апскейл и варианты обычно зависят от исходного ID задачи и номера изображения. Чаще всего отправляется новая задача с task_id и index либо вызывается интерфейс действий провайдера. Нумерация начинается с 1 или с 0 — единого правила нет, поэтому перед интеграцией проверьте тестовой задачей.

Несколько практических советов:

  • Записывайте «исходную задачу» и «производные задачи» как родителя и потомков, чтобы не увеличивать одно изображение дважды.
  • Вариант может создать новую сетку из четырёх изображений, и стоимость считается по новой задаче — оценивайте её до массового запуска.
  • Перерисовка, локальная перерисовка и смешивание поддерживаются не всеми провайдерами; ориентируйтесь на документацию.
  • Увеличенные изображения тоже могут зависеть от срока жизни ссылок upstream, поэтому сохраняйте их сразу после успеха.

7. Лимиты, параллельность и стоимость

Пропускная способность обёртки зависит от пула аккаунтов и очереди upstream: купленная параллельность не равна фактической. Типичные ограничения — число задач в минуту, одновременно выполняемых задач и дневная квота аккаунта. При 429 снижайте параллельность и используйте экспоненциальную задержку, а не слепые повторы.

Стоимость считайте по «успешно доставленным изображениям», а не по числу отправок. Включайте в знаменатель ошибки, отказы модерации, повторные отправки и апскейлы вариантов — только так получится реальная цена одного изображения. Сначала запустите небольшую партию, измерьте долю успеха и среднее время, затем увеличивайте объём.

8. Частые ошибки и диагностика

  • 401: ключ отсутствует, имеет неверный формат, не совпадает со средой или аккаунт upstream недействителен.
  • 403: IP отсутствует в белом списке, недостаточно квоты, права не открыты.
  • 404: неверный путь или ID задачи, либо задача уже очищена.
  • 429: сработал лимит — снизьте параллельность и добавьте задержку.
  • 5xx: сбой upstream или слоя обёртки; проверьте по ключу идемпотентности, что задача не создана, и только потом повторяйте.
  • Задача failed: изучите код ошибки, различайте параметры, модерацию и сбой upstream.
  • Ссылка 403/404: адрес результата истёк или требует аутентификации — вернитесь к деталям задачи и получите его заново.

Записывайте в журнал ID запроса, ID задачи, код ошибки и параметры без чувствительных данных. Ошибки обёрток часто переупакованы, и сохранение исходного ответа заметно ускоряет диагностику.

9. Чек-лист миграции

При переходе от одного провайдера к другому или от собственного прокси к управляемому сервису проверьте по пунктам:

  1. Полностью ли заменяются Base URL, заголовки аутентификации и пути запросов.
  2. Совпадают ли имя поля ID задачи, перечень статусов и определение конечного состояния.
  3. Передаются ли параметры prompt как есть или разбиваются на поля, работают ли --ar и --v.
  4. Совпадают ли способы вызова апскейла, вариантов и перерисовки, правила нумерации.
  5. Проверены ли срок жизни ссылок, ограничения скачивания и логика сохранения.
  6. Поддерживается ли callback, выполнены ли проверка подписи и идемпотентность.
  7. Проведены ли повторные нагрузочные тесты лимитов, параллельности, тайм-аутов и повторов.
  8. Сходятся ли единицы биллинга, возвраты за ошибки и сверка счетов.

После миграции сначала прогоните партию реальных бизнес-примеров, сравните долю успеха, среднее время и стоимость изображения, и только затем переключайте весь трафик. Без сверки и плана отката не переходите целиком за один раз.

Частые вопросы

Midjourney API возвращает изображение сразу?

Обычно нет. Отправка задачи возвращает только ID, затем нужно опрашивать статус или ждать callback, и лишь после успеха скачивать изображение. Синхронная схема легко приводит к тайм-аутам и повторным отправкам.

Сколько обычно длится опрос задачи?

Зависит от очереди и нагрузки upstream: встречаются десятки секунд и несколько минут. Начинайте с 3–5 секунд, постепенно увеличивайте интервал и задайте общий тайм-аут; после тайм-аута проверяйте детали задачи, а не отправляйте сразу заново.

Как долго хранится ссылка на изображение?

У разных провайдеров по-разному: минуты, часы или дни. В production не полагайтесь на upstream-ссылку — сразу после успеха переносите файл в собственное объектное хранилище.

Как вызывать апскейл и варианты?

Обычно нужен исходный ID задачи и номер изображения, затем отправляется производная задача или вызывается интерфейс действий. Начало нумерации и имена полей различаются; проверьте тестовой задачей.

На что обратить внимание командам при подключении?

Сначала проверьте доступность сети, трансграничную передачу данных и комплаенс контента, затем оцените условия провайдера и риск остановки сервиса. Если нужна единая точка входа, зарегистрируйтесь в ZSQH AI Gateway и сверьте поддерживаемые модели на странице тарифов; не считайте интерфейс изображений с не-OpenAI протоколом автоматически совместимым.

Что дальше

Сначала прогоните простой промпт через четыре шага — «отправка, опрос, скачивание, сохранение» — и только потом добавляйте апскейл, варианты и callback. При выборе провайдера ставьте комплаенс и механизм выхода выше эффектных демонстраций. Для управления несколькими входами к моделям зарегистрируйтесь в ZSQH AI Gateway и проверьте доступные модели и биллинг на странице тарифов.

Читайте также: