Руководство по реализации
Медиазадача переживает HTTP-вызов, который её создал, страницу, которая её запустила, и нередко тот деплой, что шёл в это время. Всё дальнейшее — про то, как это пережить.
Задача
Между отправкой и готовым файлом есть четыре места, где теряется работа: вслепую повторённый вызов создания после таймаута, обратный вызов, который нельзя проверить, цикл опроса, который долбит или сдаётся, и ссылка на результат, истёкшая, пока вы решали, что с ней делать.
01
Idempotency-Key делает так, что повтор той же модели, того же ввода и того же адреса обратного вызова в течение 24 часов возвращает исходную задачу и не резервирует средства дважды. Область действия — один ключ API; соседний ключ с тем же значением получит 409 и не получит идентификатор задачи.
02
Доставки несут X-Webhook-Timestamp и Base64-подпись HMAC-SHA256 в X-Webhook-Signature, вычисленную по taskId.timestamp.sha256(raw_body). Сверяйте по сырым байтам за постоянное время и отклоняйте устаревшие отметки до изменения состояния задачи или списаний.
03
recordInfo — это резервный путь, а не транспорт. Начните примерно с двух секунд, увеличивайте в полтора раза, остановитесь на пятнадцати и завершайте по сроку, который выбрали вы, а не сеть.
Подход
Сохраняйте ключ идемпотентности, taskId и собственный идентификатор корреляции в той же транзакции, в которой отвечаете вызывающей стороне. Любое последующее событие — вызов, опрос, повтор, вопрос поддержки — разрешается в эту строку, и повторная доставка становится обновлением, а не вторым заказом.
Сначала проверка, потом чтение. Подпись покрывает сырые байты, поэтому разбор идёт после сравнения.
Verify the callback before you trust it
import { createHash, createHmac, timingSafeEqual } from "node:crypto";
// rawBody is the exact bytes that arrived. Parse only to read the task ID:
// the digest is always computed over those raw bytes, never over a re-encode.
export function verifyDelivery(rawBody, headers, webhookKey) {
const timestamp = headers["x-webhook-timestamp"];
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const taskId = JSON.parse(rawBody).data.taskId; // payload version 2
const digest = createHash("sha256").update(rawBody).digest("hex");
const expected = createHmac("sha256", webhookKey)
.update(`${taskId}.${timestamp}.${digest}`)
.digest("base64");
const sent = Buffer.from(headers["x-webhook-signature"] ?? "", "utf8");
const mine = Buffer.from(expected, "utf8");
return sent.length === mine.length && timingSafeEqual(sent, mine);
}Delivery headers
X-Webhook-Timestamp: 1788652800
X-Webhook-Signature: <base64>
X-Webhook-Payload-Version: 2
{
"code": 200,
"msg": "success",
"request_id": "whd_01k3m8x9q2z4v7n5p6r8s0t1w3",
"data": { "taskId": "job_01k3…", "state": "succeeded", "settled": true, … }
}Контракт
| Поле или заголовок | Значение или предел |
|---|---|
| Idempotency-Key | 24 h · scoped to one API key |
| X-Webhook-Signature | base64(HMAC-SHA256) |
| signed string | taskId.timestamp.sha256(raw_body) |
| X-Webhook-Payload-Version | 2 for new integrations |
Проведите по горизонтали, чтобы увидеть все столбцы.
Интеграция
Применимость
Проверки
Конверт у всех операций /api/v1 — {code, msg, data, request_id}. В версии полезной нагрузки 2 request_id доставки не меняется при повторной отправке, поэтому он и есть естественный ключ дедупликации.
cost при settled: false — это зарезервированная оценка, settled: true — итоговое списание. Успех никогда не превышает резерв, а ошибка или истечение срока освобождают его полностью.
errorCode принимает одно из девяти стабильных значений: invalid_request, unsupported_combination, content_rejected, rate_limited, upstream_unavailable, generation_failed, timeout, invalid_asset, upstream_failed. Любое другое значение трактуйте как upstream_failed.
Перед запуском
Частые вопросы
Модели
Каждая ссылка ведёт на страницу семейства моделей: входные данные, ограничения, контентная политика и текущая цена за единицу.
Дальше
Отправляйте долгие медиазадачи с сервера и надёжно доводите до конца: ключи идемпотентности, подписанные вызовы, ограниченный опрос, пять состояний.
