Обратный вызов о завершении задачи (Webhook)

При отправке асинхронных задач генерации, таких как видео / изображение / аудио, вы можете указать URL обратного вызова. После завершения задачи (успешно или с ошибкой) мы активно отправим результат через POST на ваш URL, чтобы вам не приходилось постоянно опрашивать статус.

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

При отправке задачи добавьте поле webhook в тело запроса:

curl -X POST https://ваш-домен-доступа/v1/images/generations \
  -H "Authorization: Bearer ВАШ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red apple on a table",
    "size": "1024x1024",
    "webhook": "https://your-server.com"
  }'

После завершения задачи мы отправим POST-запрос на ваш URL + /callback.

Другие конечные точки асинхронных задач (видео, аудио и т. д.) работают так же — просто добавьте поле webhook в тело запроса.

Правила URL

Указанный вами webhook — это базовый URL (base), к которому мы автоматически добавляем /callback:

Ваш `webhook`	Куда мы фактически отправляем POST
`https://your-server.com`	`https://your-server.com/callback`
`https://your-server.com/api`	`https://your-server.com/api/callback`
`https://your-server.com/api/`	`https://your-server.com/api/callback`

Поэтому на вашем сервере нужна конечная точка, принимающая POST .../callback.

Что вы получите

Отправляемое содержимое полностью совпадает с тем, что возвращает конечная точка «Получение статуса задачи» — вы можете обрабатывать его той же логикой разбора.

{
  "id": "task_01KV7FXR8BEYS1BWHJCT3JMCJ5",
  "status": "completed",
  "progress": 100,
  "created": 1781589029,
  "completed": 1781589058,
  "actual_time": 29,
  "cost": 0.006,
  "credits_cost": 0.06,
  "result": {
    "images": [{ "url": ["https://.../result.png"], "expires_at": 1781675458 }]
  }
}

{
  "id": "task_xxx",
  "status": "failed",
  "progress": 100,
  "created": 1781589029,
  "completed": 1781589050,
  "error": { "message": "причина ошибки...", "code": "" }
}

Для видеозадач результат находится в result.videos, а для аудио — в result.audios.

Мы отправляем уведомление только когда задача достигает конечного состояния (completed / failed); во время обработки уведомления не отправляются.

Повторные попытки и дедупликация (важно)

Повторные попытки: Если ваш сервер не вернёт 2xx примерно за 10 секунд или вернёт 5xx, мы автоматически повторим попытку, до 3 раз, с интервалами около 10 с, 30 с и 60 с. Если все 3 попытки неудачны, мы прекращаем (примерно за 2 минуты).
Без повтора: Если ваша конечная точка вернёт 4xx (считается проблемой URL / запроса), мы сразу прекращаем без повторных попыток.
Дедупликация: Обычно задача отправляется только один раз. Но в крайних случаях (например, перезапуск на нашей стороне после отправки, но до подтверждения) вы можете получить повторные отправки. Обязательно выполняйте идемпотентную дедупликацию по id (task_id), чтобы избежать повторной обработки.

Рекомендации для вашей принимающей конечной точки:

Возвращайте 2xx как можно быстрее

Сначала примите и поставьте в очередь, затем обрабатывайте асинхронно — не заставляйте нас ждать завершения вашей обработки.

Дедуплицируйте по id

Используйте id (task_id) как ключ идемпотентности, чтобы избежать повторной обработки.

Настройте и проверяйте подпись

В продакшене проверяйте источник запросов обратного вызова и отклоняйте поддельные.

Требования к URL обратного вызова

В целях безопасности URL обратного вызова должен соответствовать следующему:

Требование	Описание
Публично доступен	Не может быть внутренним / локальным адресом (например, `127.0.0.1`, `10.x`, `192.168.x` будут отклонены)
Протокол	`http` или `https` (рекомендуется `https`)
Порт	Используйте стандартные порты (`80` / `443`); нестандартные порты могут блокироваться
Домен	Не может указывать на наш собственный сервисный домен

URL, не отвечающие этим требованиям, отбрасываются (без отправки и без повторов).

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

Отправил задачу с webhook, но не получил уведомление?

Проверьте по пунктам:

Задача действительно завершена? Проверьте детали задачи — status равен completed / failed (во время обработки уведомления не отправляются)?
Ваш URL публично доступен? Можем ли мы достучаться до вашего /callback?
Порт стандартный (80 / 443)? Нестандартные порты могут блокироваться политиками безопасности.
Ваш /callback вовремя вернул 2xx? При 4xx мы сразу прекращаем.
Используете ли вы https? Действителен ли сертификат?

Почему url в result — это массив?

Некоторые модели создают несколько изображений за раз, поэтому images[].url может быть массивом — просто обрабатывайте его как массив.

Истекает ли срок действия ссылок результата?

Если в result есть expires_at (метка времени Unix), это время истечения срока действия ссылки — вовремя перенесите/сохраните её.

Отправляете ли вы статус «в обработке»?

Нет. Мы отправляем уведомление только один раз, когда задача окончательно завершается успехом или ошибкой.

Минимальный пример приёмника

Python

from http.server import BaseHTTPRequestHandler, HTTPServer
import json

class H(BaseHTTPRequestHandler):
    def do_POST(self):
        n = int(self.headers.get("Content-Length") or 0)
        body = self.rfile.read(n)
        data = json.loads(body)
        print("Получен обратный вызов задачи:", data["id"], data["status"])
        # TODO: дедуплицировать по id, проверить подпись, затем обработать
        self.send_response(200); self.end_headers()
        self.wfile.write(b'{"ok":true}')

HTTPServer(("0.0.0.0", 443), H).serve_forever()

Возвращайте 200 как можно быстрее, а логику обработки выполняйте асинхронно в фоне.

Обзор

Текстовая серия

Серия изображений

Видеосерия

Аудиосерия

Серия модерации

Управление загрузками

Управление задачами

Управление аккаунтом

Обратный вызов о завершении задачи (Webhook)

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

Правила URL

Что вы получите

Повторные попытки и дедупликация (важно)

Требования к URL обратного вызова

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

Минимальный пример приёмника

​Быстрый старт

​Правила URL

​Что вы получите

​Повторные попытки и дедупликация (важно)

​Требования к URL обратного вызова

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

​Минимальный пример приёмника

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

Правила URL

Что вы получите

Повторные попытки и дедупликация (важно)

Требования к URL обратного вызова

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

Минимальный пример приёмника