Быстрый старт
Один ключ, один формат запроса, все модели изображений и видео. Отправьте задачу, опросите её, получите файл.
/data/models.json.POST /v1/chat/completions, оплата за токены из тех же кредитов: см. chat completions.| Базовый URL | https://api.revana.si/v1 |
| Авторизация | Authorization: Bearer <key> |
| Отправка | POST /v1/generations |
| Опрос | GET /v1/generations/{id} |
| Модели | GET /v1/models (без ключа): все модели, с которыми можно генерировать прямо сейчас |
| Баланс | GET /v1/balance: сколько может потратить аккаунт вашего ключа |
| Загрузить | POST /v1/uploads: ссылка на референсный файл с вашего компьютера |
| Формат | JSON на входе, JSON на выходе. Цены в USD; 100 кредитов = $1. |
| Машиночитаемо | /openapi.json · /llms.txt |
Аутентификация
Создайте ключ в своём аккаунте, затем передавайте его как bearer-токен в каждом запросе. Храните его на сервере; никогда не включайте его в браузерное или мобильное приложение.
Отправка генерации
Передайте идентификатор модели и её input. Ответ приходит сразу, с id генерации и статусом queued; работа выполняется в фоне.
| Поле | Тип | Описание |
|---|---|---|
model | строка, обязательно | Идентификатор модели со страницы моделей, напр. seedance-2.5. |
input | объект, обязательно | Промпт и настройки; см. входные поля. Неизвестные поля отклоняются. |
max_cost_usd | число, необязательно | Максимум, который вы заплатите за эту генерацию, вплоть до 100 (по умолчанию). Маршруты дороже этого значения пропускаются; если не остаётся ни одного, запрос отвечает 422 max_cost_exceeded. |
max_wait_s | целое число, необязательно | Маршруты, которые, как ожидается, займут больше этого числа секунд, пропускаются. После истечения этого времени новые маршруты не пробуются, но уже запущенному разрешается завершиться (до 40 минут), и плата списывается, если он выдал результат. |
Idempotency-Key | заголовок, необязательно | До 200 символов. Отправьте тот же ключ и то же тело снова (после тайм-аута или 503), и вы получите ту же генерацию, а не вторую. Тот же ключ с другим телом — это 409 idempotency_conflict. |
Получение результата
Нужен эндпоинт для каждой модели и вебхуки о завершении? См. fal-совместимый API очереди: идентификаторы запросов, URL статуса и результата, поддерживаемые псевдонимы fal и ограничения миграции.
Опрашивайте раз в несколько секунд, пока status не станет succeeded или failed, затем скачайте файлы из output.urls со своим ключом: GET /v1/generations/{id}/content для первого и /content/2, /content/3…, когда модель изображений возвращает несколько. Изображения обычно занимают секунды; видео — от менее минуты до нескольких минут в зависимости от модели и длительности.
Завершённая генерация:
Входные поля
Одни и те же названия используются во всех моделях. Какие поля и значения принимает каждая модель и их значения по умолчанию перечислены по моделям в /data/models.json (options, tasks). Если модель не поддерживает поле или значение, запрос отклоняется с 422 invalid_input до какого-либо списания.
| Поле | Тип | Используется для |
|---|---|---|
prompt | string | Что генерировать. Обязательно для «текст в изображение» и «текст в видео». |
image_url | строка (URL) | Начальный кадр для «изображения в видео» или изображение для редактирования в «изображение в изображение». |
end_image_url | строка (URL) | Последний кадр, для моделей с первым и последним кадром. |
image_urls | string[] | Референсные изображения, до лимита модели. |
resolution | string | 720p, 1080p, 2K… одно из разрешений модели. |
duration | number | Длительность видео в секундах, одна из длительностей модели. |
aspect_ratio | string | 16:9, 9:16, 1:1... |
audio | boolean | Генерировать звук вместе с видео, если модель это поддерживает. Может изменить цену. |
negative_prompt | string | Чего избегать, для моделей, которые это принимают. |
video_url | строка (URL) | Клип для преобразования, продления или повышения разрешения. Его длительность измеряется и, у моделей с оплатой за секунду, тарифицируется. |
audio_url | строка (URL) | Голос или звук, под который анимирует модель говорящего аватара или синхронизации губ. |
quality | string | Уровень качества для моделей, цена которых зависит от него (напр. low, medium, high). |
seed | integer | Seed для моделей, которые его принимают. |
Seedance 2.5 по умолчанию использует 720p, 5 секунд (4–30), 16:9 и без звука, а также принимает:
| Поле | Тип | Используется для |
|---|---|---|
video_url | строка (URL) | Клип на 4–30 с для редактирования. Результат сохраняет его длительность, поэтому опустите duration. |
video_urls | string[] | Референсные клипы, до 10 штук и 30 секунд суммарно. Их секунды тарифицируются по ставке входного видео. |
audio_urls | string[] | Референсный звук, до 10 штук и 30 секунд суммарно. |
image_url — это точный первый кадр, поэтому его нельзя сочетать с референсными медиафайлами; для менее строгой визуальной отсылки используйте image_urls. end_image_url требует image_url. Медиафайлы должны быть публичными URL https, которые скачиваются напрямую.
Nemesis
nemesis заново ставит клип с вашими людьми, продуктами и местами: движение, тайминг и камера клипа, исполненные по до 8 референсным картинкам. Результат сохраняет длительность и формат клипа. Цена равна ставке правки Seedance 2.5 плюс $0.02 за секунду ($0.08, $0.17 и $0.36 в 480p, 720p и 1080p) за секунду входного клипа плюс выходное видео.
Он следует рецепту Scenario ALTER: редактируется сам ваш клип, без звука, при этом один его кадр перерисовывается с уже внесённым изменением и становится первым референсом, а собственный звук клипа возвращается после. Если людей несколько, картинки сопоставляются слева направо в порядке, в котором люди стоят в первом кадре.
| Поле | Тип | Используется для |
|---|---|---|
video_url | string (URL), обязательно | Клип на 4–30 с для постановки заново. |
image_urls | string[], обязательно | 1–8 референсных картинок. |
roles | string[] | По одному на картинку: person (по умолчанию), product, location или look. |
target_frame | boolean | Перед рендером первый кадр клипа перерисовывается с уже внесённым изменением, в той же позе, размере и свете, и отправляется как первый референс, чтобы волосы, лицо и одежда оставались верны вашим картинкам. Включено по умолчанию для nemesis, выключено для nemesis-lite. Бесплатно. |
guide | string | nemesis-lite только (nemesis всегда редактирует сам клип). clip (по умолчанию при наличии целевого кадра): следует собственной картинке клипа. people (по умолчанию без него): люди заменяются, фон сохраняется. scene: всё видимое берётся из референсов и промпта. |
sound | string | original (по умолчанию включено для nemesis): собственный звук клипа возвращается. none (по умолчанию для nemesis-lite): без звука. |
face_mesh | boolean | nemesis-lite только. Отслеживает каждое лицо в клипе, чтобы новое лицо сохраняло мимику, глаза и губы. По умолчанию включено с guide: "people", выключено для scene и clip. Передайте false, чтобы оставить выключенным. В результате никогда не показывается. |
resolution | string | 480p, 720p (по умолчанию) или 1080p. |
prompt | string | Необязательное указание, до 5000 символов. |
В nemesis-lite клип, в котором никого нет, отправленный с guide: "people", отклоняется с invalid_input без списания; отправьте его с scene или clip.
Сколько это занимает. Сначала подготавливается клип: в nemesis рисуется целевой кадр, около 15–40 секунд; в nemesis-lite отделяется голос и каждый кадр превращается в карту глубины, около 25 секунд для клипа в 8 секунд и полторы минуты для клипа в 30 секунд. Затем рендерится видео, на что уходит большая часть ожидания: клип на 8 секунд в 480p занимает около 4–7 минут. Опрашивайте генерацию, пока она не завершится.
Nemesis Lite
nemesis-lite принимает те же входные данные, что и nemesis, и рендерит их на Wan 3.0: дешевле, чуть менее точно в лицах и мелких деталях. Клип — 2–15 с. Цена равна ставке Wan 3.0 плюс $0.02 за секунду ($0.07, $0.11 и $0.19 в 480p, 720p и 1080p) за секунду входного клипа плюс выходное видео.
Объект генерации
| Поле | Тип | Описание |
|---|---|---|
id | string | Идентификатор генерации (gen_…), используется для опроса. |
object | string | Всегда generation. |
model | string | Модель, которую вы запросили. |
status | string | См. статусы. |
message | string | Только пока результат подтверждается у провайдера: что происходит. |
quoted_usd | number | Цена на самом дешёвом маршруте, который пробуется первым. Если он не может выполнить задачу, а более дорогой запасной маршрут может, списывается цена этого маршрута, до reserved_usd. |
reserved_usd | number | Что резервируется на вашем балансе: максимум, который может стоить эта генерация, если более дорогой запасной маршрут выполнит её после других попыток. Разница освобождается при расчёте. Чтобы никогда не платить больше quoted_usd, задайте max_cost_usd равным этому значению: более дорогие запасные маршруты тогда пропускаются. |
output | object | null | При succeeded: urls — файлы результата (модель изображений может вернуть несколько), с width и height; у видео также есть duration_s и has_audio. Скачивайте их без промедления; файлы истекают. |
cost_usd | number | null | Что было списано. Устанавливается, когда генерация завершилась успешно; 0, если она завершилась ошибкой. |
attempts | number | Опробованные маршруты, включая запасные. Тарифицируется только успешный. |
error | object | null | При failed: code, message и retryable; при отказе по содержимому также есть reason. См. почему генерация завершилась ошибкой. |
created_at, completed_at | string | Временные метки ISO 8601. |
Статусы
| Статус | Значение |
|---|---|
queued | Принято, ожидает маршрута. |
running | Генерируется. Если маршрут не сработал, задача остаётся running, пока переходит на следующий, а также пока результат подтверждается (см. message). |
succeeded | Готово. output.urls содержит файлы, а cost_usd — сумму, которую вы заплатили. |
failed | Не сработал ни один маршрут, либо входные данные отклонены. Ничего не списывается. |
Тарификация
- Вы платите из предоплаченных кредитов, 100 за доллар, покупаемых пакетами от $10 до $5000. Каждая цена — целое число кредитов.
- При отправке
reserved_usdрезервируется на вашем балансе. Если генерация завершилась ошибкой, резерв освобождается полностью. - Плата списывается только когда генерация завершилась успешно, по цене, названной для маршрута, который её выполнил. Обычно это первый маршрут по
quoted_usd. Если выполнять её пришлось запасному маршруту, она может стоить дороже: цена этого маршрута или, если маршрут, опробованный до него, тарифицировался его поставщиком, стоимость этих попыток плюс 10% — что больше. Никогда не вышеreserved_usd. - Нет ни ежемесячной квоты, ни лимита в минуту: предел — ваш баланс и
max_cost_usd. - Цена каждой модели — на её странице и в таблице цен.
Баланс
Аккаунт, которому принадлежит ваш ключ. Проверьте его перед большой партией; это бесплатно и не учитывается в лимитах генераций.
| Поле | Значение |
|---|---|
available_usd | Сколько новая генерация может зарезервировать. Отправка с reserved_usd больше этого значения получает 402 insufficient_credits. |
held_usd | Зарезервировано выполняющимися генерациями. Неиспользованное возвращается при их завершении. |
balance_usd | Доступно плюс зарезервировано. |
spent_usd | Списано за завершённые генерации, за всё время. |
*_credits | Те же суммы в кредитах (100 за доллар), округлённые так, чтобы доступная сумма никогда не выглядела больше, чем есть. |
Загрузка референсного файла
Референсы передаются как публичные ссылки https://. Для файла на вашем компьютере запросите ссылку для загрузки, отправьте туда байты и используйте полученную ссылку. Это бесплатно.
| Поле | Значение |
|---|---|
upload_url | Отправьте файл сюда через PUT в течение часа, ровно с теми заголовками, что указаны в upload_headers (его тип и размер). Всё остальное отклоняется. |
url | Ссылка на файл на api.revana.si, действует до expires_at (14 дней). Ключ не нужен, ссылка перенаправляет на файл, поэтому прочитать его может всё, что умеет открывать ссылки. Используйте её как референс в POST /v1/generations. Вскоре после этого файл удаляется. |
id | upl_… |
Картинки (image/*) до 30 МБ, клипы (video/*) до 50 МБ, звук (audio/*) до 15 МБ. Файл большего размера или другого типа получает 413 too_large или 400 invalid_request.
Почему генерация завершилась ошибкой
У генерации failed есть error.code, message, написанный для показа тому, кто сделал запрос, и retryable: true, когда повторная отправка того же запроса позже может сработать, false, когда нужно изменить сам запрос. Неудавшаяся генерация никогда не тарифицируется.
| Код | Повторяемо | Когда |
|---|---|---|
content_policy | no | Модель отклонила промпт или медиафайл либо не отдала то, что создала. reason указывает правило: sexual (NSFW или контент для взрослых), minors (дети или подростки), copyright (материалы, защищённые авторским правом, или сторонние материалы, бренды, персонажи), real_person (облик реального или известного человека) или other, когда модель не называет причину. |
invalid_input | no | Референс не удалось прочитать, промпт называет @Image2, когда отправлено одно изображение, или значение, которое модель отклоняет. Сообщение указывает, что именно. |
model_declined | no | Модель ответила словами вместо создания картинки или видео, обычно потому, что промпт просит о чём-то, что ей нужно и что не было передано. Пусть промпт описывает сам результат. |
reference_changed | no | Файл-референс изменился после проверки. Отправьте его снова. |
max_cost_exceeded | no | Единственный маршрут, который мог выполнить задачу, стоит больше max_cost_usd. |
model_busy | yes | Все маршруты модели были перегружены. Повторите через минуту. |
model_unavailable | yes | Ни один маршрут модели сейчас не может принять задачу. |
timeout | yes | Ни один маршрут не вернул результат вовремя, либо истёк max_wait_s. |
all_routes_failed | yes | Все маршруты не сработали по причинам с их стороны. |
Ошибки
Ошибки используют коды состояния HTTP и тело в формате JSON: {"error": {"code": "...", "message": "..."}}.
| HTTP | Код | Когда |
|---|---|---|
| 400 | invalid_request | Тело не в формате JSON, в нём нет model или input, либо есть поле, которое API не знает. |
| 401 | unauthorized | Отсутствующий или недействительный API-ключ. |
| 402 | insufficient_credits | Ваш доступный баланс не покрывает reserved_usd. Пополните и повторите. |
| 403 | account_disabled | Аккаунт приостановлен. Обратитесь в поддержку. |
| 403 | generation_not_enabled | Ваш ключ может читать цены, но пока не может генерировать. |
| 404 | not_found | На вашем аккаунте нет генерации с этим id. |
| 409 | idempotency_conflict | Этот Idempotency-Key уже использовался с другим телом запроса. |
| 409 | not_ready | Файл запрошен до того, как генерация завершилась успешно. |
| 413 | body_too_large | Тело больше 1 МБ. Передавайте медиафайлы как URL. |
| 422 | invalid_input | Поле, значение или сочетание, которое модель не поддерживает, либо медиафайл, который не удаётся прочитать. Ничего не списывается. |
| 422 | max_cost_exceeded | Все маршруты стоят больше max_cost_usd. |
| 422 | model_not_available | В API нет модели с таким id. Идентификаторы — на странице моделей. |
| 429 | rate_limited | Слишком много запросов за одну секунду с одного аккаунта (защита от неконтролируемых циклов, а не квота). Подождите Retry-After с. |
| 429 | concurrency_limit | На аккаунте уже выполняется максимальное число генераций. Повторите, когда одна из них завершится. |
| 503 | busy | Момент повышенной нагрузки. Повторите через Retry-After с тем же Idempotency-Key. |
| 503 | model_unavailable | Сейчас нет доступных маршрутов для этой модели. Повторите немного позже. |
| 500 | server_error | Что-то сломалось с нашей стороны. Можно безопасно повторить с тем же Idempotency-Key. |
Список моделей
Каждая модель, её параметры и цены опубликованы в виде JSON по адресу /data/models.json — это тот же файл, из которого строится этот сайт.