Решение: видео-API
Видео — самый дорогой результат в большинстве продуктов и самый долгий. Обе величины задают три поля в теле запроса, а задача продолжает работать задолго после того, как исчезло соединение, которое её начало.
Задача
Видеозапрос — это не медленный запрос картинки. Длительность, разрешение и переключатель звука определяют, сколько вы заплатите и сколько подождёте, и определяют это до того, как появится первый кадр.
01
Большинство видеоэндпоинтов тарифицируются за секунду результата в выбранном разрешении. Перевод duration_seconds с 5 на 10 примерно удваивает сумму, шаг по разрешению удваивает её ещё раз. Оба поля помечены в схеме как влияющие на цену, поэтому оценка должна стоять рядом с элементом управления, а не появляться в счёте.
02
Там, где есть generate_audio, этот флаг переводит запрос на другой тариф. Форма, которая его прячет, будет молча отправлять более дорогой вариант каждый раз.
03
createTask отвечает 202 Accepted и возвращает taskId в состоянии queued. Генерация продолжается на сервере минутами. Любой код, ждущий на исходном сокете, упрётся в таймаут, пока задача и списание идут своим чередом.
Подход
Запросите оценку точного тела через POST /api/v1/jobs/quote, покажите сумму и отправьте то же тело в createTask вместе с quoteId, expectedCost и сохранённым Idempotency-Key. Цена, изменившаяся между двумя вызовами, вернёт бизнес-код 40901 вместо сюрприза в счёте.
Один вызов создания несёт модель, проверенный ввод и необязательный обратный вызов. HTTP 202 означает «принято», а не «готово».
POST /api/v1/jobs/createTask
POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Idempotency-Key: 7b1f0c2e-9a4d-4f31-8c67-2b5e0d9a1c44
Content-Type: application/json
{
"model": "<publisher>/<model>/text-to-video",
"input": {
"prompt": "A slow aerial drift over a misty pine forest at sunrise",
"duration_seconds": 5,
"resolution": "1080p",
"generate_audio": true
},
"callBackUrl": "https://example.com/hooks/spicyapi"
}202 Accepted
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3
{
"code": 200,
"msg": "success",
"request_id": "req_example_create",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "queued",
"estimatedCost": "0.750000"
}
}Контракт
| Поле или заголовок | Значение или предел |
|---|---|
| POST /api/v1/jobs/createTask | 202 Accepted · state queued |
| duration_seconds · resolution · generate_audio | price-affecting fields |
| Idempotency-Key | 24 h · scoped to one API key |
| output.assets[].expiresAt | signed URL · results kept 14 days |
Проведите по горизонтали, чтобы увидеть все столбцы.
Интеграция
Применимость
Проверки
Форма на странице модели строится из input_schema этого эндпоинта, и сервер проверяет по тому же документу. Необъявленное поле даёт 400, а не молчаливое отбрасывание.
createTask резервирует оценочную сумму и возвращает её в cost с settled: false. Итоговое списание никогда не превышает резерв, а при ошибке или истечении срока резерв освобождается полностью.
Задайте ключу лимит на день, на месяц и за всё время, ограничьте его набором моделей и списком IP, а каждую запись отправляйте с одним и тем же ключом идемпотентности.
Перед запуском
Частые вопросы
Модели
Каждая ссылка ведёт на страницу семейства моделей: входные данные, ограничения, контентная политика и текущая цена за единицу.
Дальше
Сравните видеоэндпоинты по длительности, разрешению, звуку и цене, а затем отправьте тот же запрос со своего сервера.
