Запуск генерации

Список моделей

Те же модели отдаёт GET /v1/models, а GET /v1/models/{model_key} даёт JSON Schema настроек и документацию на языке запроса. Все модели с их схемами одним запросом: GET /v1/models/schemas.

curl "https://api.cyhub.ai/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

Запустить задачу

Задача создаётся одним запросом: ключ модели и её настройки. Какие поля есть у модели, сказано на её странице. Заголовок Idempotency-Key необязателен, но с ним повтор запроса безопасен (ниже).

curl -X POST "https://api.cyhub.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  --data '{
  "model": "veo",
  "settings": {
    "prompt": "Рыбацкая лодка выходит из тумана на рассвете, крики чаек",
    "mode": "text_to_video",
    "tier": "lite",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }
}'

Ответ 201 с задачей: id, status (сначала queued), amount_minor и currency (цена). Цена считается при приёме и резервируется на балансе, списывается после успешной генерации; при ошибке или отмене резерв возвращается.

Если денег не хватает, ответ 402 insufficient_funds: задача не создаётся, деньги не трогаются. Незнакомое поле в settings это 422 unknown_setting, неподходящее значение 422 invalid_settings.

Узнать цену заранее

Те же модель и настройки в POST /v1/price: задача не создаётся, деньги не трогаются.

curl -X POST "https://api.cyhub.ai/v1/price" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "veo",
  "settings": {
    "prompt": "Рыбацкая лодка выходит из тумана на рассвете, крики чаек",
    "mode": "text_to_video",
    "tier": "lite",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }
}'

В ответе credits (внутренние единицы модели), amount_minor и currency (цена в деньгах), regular_minor и discount (цена без скидки и скидка, ниже) и available_minor (сколько доступно). Цена справочная: у новой задачи она считается заново при приёме.

Скидки

Если у кабинета есть скидка, amount_minor в POST /v1/price и у задачи уже с ней: столько и будет зарезервировано и списано. Рядом regular_minor (цена без скидки) и процент скидки: discount.percent у цены, discount_percent у задачи. Без скидки regular_minor равен amount_minor, а процент 0.

Уровень скидки кабинета, оборот и цены моделей на каждом уровне отдаёт GET /v1/discounts. Пока скидки у кабинета нет, ответ {"active": false}.

curl "https://api.cyhub.ai/v1/discounts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Повторные запросы

Idempotency-Key это метка одной генерации, которую придумывает ваша программа: UUID или свой номер, например order-1042. Передаётся заголовком или полем idempotency_key в теле запроса.

Idempotency-Key: order-1042

Ответ не дошёл (обрыв связи, таймаут): повторите тот же запрос с той же меткой. Вернётся уже созданная задача, второй генерации и второго резерва не будет. Для следующей генерации нужна новая метка, даже если настройки те же.

Та же метка с другими настройками это 409 idempotency_conflict.

Повторы с одной меткой можно слать и одновременно: задачу ставит первый, остальные дожидаются его и получают ту же задачу. Если первый ещё не закончил за 40 секунд, ответ 409 request_in_progress: повторите чуть позже.