Обратный вызов о завершении задачи (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",
    "language": "ru"
  }'

​

Выбор языка сообщения об ошибке

• Значения не зависят от регистра, а пробелы по краям автоматически удаляются. Например, "RU" и " ru " обрабатываются как ru.
• Используйте двухбуквенные коды из таблицы. Региональные теги, такие как zh-CN, en-US и pt-BR, не распознаются.
• Неподдерживаемое значение не приводит к ошибке отправки задачи; в уведомлении сохраняется исходное сообщение.
• Если исходное сообщение уже написано на целевом языке, оно возвращается без повторного перевода.
• При ошибке перевода возвращается исходное сообщение, а доставка уведомления не задерживается и не отменяется.

​

Правила URL

​

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

{
  "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": "Не удалось получить доступ к входному изображению. Убедитесь, что URL общедоступен",
    "type": "task_failed",
    "param": "",
    "code": "task_failed"
  }
}

​

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

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

​

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

​

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

​

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

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()