Как подключить API Runway: первый запрос

Как подключить API Runway и сделать первый запрос: заведите Dev-аккаунт на dev.runwayml.com, создайте проект и ключ, пополните API-баланс, установите официальный SDK (npm install --save @runwayml/sdk или pip install runwayml), затем отправьте задачу image-to-video на модель gen4.5 и дождитесь выходной ссылки. Ниже — весь цикл по официальной справке: от ключа до разбора ошибок.

Подготовка Dev-аккаунта и ключа

Работа начинается в портале разработчика. В справке Runway Dev описан порядок: сначала регистрация аккаунта в developer portal, после чего портал предлагает создать новый проект. Проект соответствует вашей интеграции и хранит ресурсы вроде API-ключей и конфигурации. Один проект удобно заводить под одну интеграцию, чтобы ключи и лимиты не смешивались между разными приложениями.

Дальше — вкладка API Keys. Ключу дают описательное имя, например «Matt Testing», чтобы позже можно было отозвать именно его. Создание и отключение ключей требует роли Admin или Developer — это указано в разделе Projects and roles. Если у вас роль Viewer, попросите администратора проверить права на создание ключей.

Ключ показывается один раз, сразу после создания. В справке прямо сказано: скопируйте его в надёжное место, например в менеджер паролей, потому что в открытом виде он больше не вернётся. Потерянный ключ отключают и создают новый. Отдельно отмечено: удаление пользователя из проекта не отзывает его API-ключи, поскольку ключи привязаны к проекту. Чтобы полностью закрыть доступ, ключи отключают вручную.

Для тестов ключ удобно держать в переменной окружения. Справка приводит экспорт RUNWAYML_API_SECRET для macOS и Linux и setx для Windows. В продакшене ключ загружают через секрет-менеджер и не хардкодят в коде.

Веб-кредиты и API-баланс: два разных счёта

При проблеме баланса проверьте, какой счёт вы пополняли. В официальном FAQ Runway сказано: кредиты и планы, купленные в веб-приложении (app.runway.com), полностью отдельны от кредитов, купленных через API (dev.runway.com). Веб-кредиты никогда не появятся в API-кредитах, и наоборот.

Пополнение идёт во вкладке billing портала разработчика. Минимальный платёж для старта — $10 при цене $0.01 за кредит. Пополнение требует роли Admin или Billing admin. Кредиты оплачивают вычислительные ресурсы, которые используют ваши модели.

Практический вывод: подписка на веб-приложение не даёт права на API-запросы. Если вы платите за веб-тариф и получаете ошибку баланса при вызове API, проверьте именно API-баланс проекта. Это два независимых кошелька, и пополнять нужно тот, из которого списывается генерация.

Установка официального SDK по справке

В FAQ Runway для интеграций на Node.js и Python дана прямая рекомендация: не подключаться к API напрямую, а использовать официальные SDK. Они дают лучшую обработку ошибок, автоматические повторы и поддерживаются вместе с обновлениями API, что защищает код от ломающих изменений.

Установка по справке: для Node.js — npm install --save @runwayml/sdk, для Python — pip install runwayml. После установки SDK импортируется и создаётся клиент: import RunwayML, { TaskFailedError } from '@runwayml/sdk' и const client = new RunwayML(); в Node, from runwayml import RunwayML, TaskFailedError и client = RunwayML() в Python.

Клиент автоматически подставляет ключ, если он лежит в переменной окружения RUNWAYML_API_SECRET. Это тот самый экспорт, который вы сделали на шаге с ключом. Если переменная не задана, SDK не найдёт ключ и запрос не уйдёт.

Если вы пока не готовы писать код, справка предлагает протестировать API через cURL. Тогда ключ и версия передаются заголовками вручную: Authorization: Bearer $RUNWAYML_API_SECRET и X-Runway-Version: 2024-11-06. Официальный hostname API — api.dev.runwayml.com; все запросы направляются на этот адрес.

Первый запрос: модель gen4.5 и её параметры

Учебный пример из справки — генерация видео из изображения на модели gen4.5. Задача создаётся методом imageToVideo.create (в Python — image_to_video.create) со следующими параметрами:

• model: 'gen4.5' — конкретная модель генерации видео;
• promptImage — URL изображения; в примере справки это ссылка на фото Эйфелевой башни с Wikimedia;
• promptText — текстовое описание; в примере «A timelapse on a sunny day with clouds flying by»;
• ratio: '1280:720' — соотношение сторон;
• duration: 5 — длительность в секундах.

В справке отмечено: при встраивании в своё приложение замените promptImage на URL вашего изображения, а promptText — на свой текст. Пример из документации носит учебный характер; редакция платный запрос не выполняла.

Тот же вызов доступен через cURL: POST на https://api.dev.runwayml.com/v1/image_to_video с JSON-телом, где перечислены promptImage, promptText, model, ratio и duration, и заголовками Content-Type: application/json, Authorization и X-Runway-Version: 2024-11-06.

Модель gen4.5 поддерживает и режим text-to-video: достаточно не передавать promptImage. В примере справки для этого режима используется промпт «A serene mountain landscape at sunrise with mist rolling through the valleys» с теми же ratio и duration.

Готовый промпт для описания сцены, который можно скопировать и подставить в promptText:

Опиши сцену для генерации видео: [ваш объект] в [ваше место], время суток [утро/день/вечер], погода [ясно/облачно/дождь], движение в кадре [что происходит], стиль съёмки [реализм/кинематографично/документально]. Дай один краткий абзац, без диалогов и текста в кадре.

Замените квадратные скобки на свои значения. Для режима image-to-video этот текст идёт в promptText, а изображение — в promptImage.

Полный учебный пример на Python по официальной справке. Сначала задайте переменную окружения RUNWAYML_API_SECRET, установите runwayml и замените prompt_image своим доступным URL. Этот запрос расходует API-кредиты; редакция его не выполняла.

from runwayml import RunwayML, TaskFailedError

client = RunwayML()
pending = client.image_to_video.create(
    model="gen4.5",
    prompt_image="https://upload.wikimedia.org/wikipedia/commons/8/85/Tour_Eiffel_Wikimedia_Commons_(cropped).jpg",
    prompt_text="A timelapse on a sunny day with clouds flying by",
    ratio="1280:720",
    duration=5,
)
print("Сохраните ID:", pending.id)
try:
    completed = pending.wait_for_task_output()
    print(completed.output[0])
except TaskFailedError as error:
    print("Генерация завершилась ошибкой:", error.task_details)

Первичная инструкция: https://docs.dev.runwayml.com/guides/using-the-api/

Ожидание задачи и получение выходной ссылки

Создание задачи возвращает JSON с идентификатором задачи. В справке сказано: после команды вы увидите ответ с task ID, который используется для получения статуса задачи. Сохраните этот ID — по нему задачу можно перепроверить, не создавая новую генерацию.

В примерах SDK ожидание встроено в вызов: .waitForTaskOutput() в Node и .wait_for_task_output() в Python. Метод дожидается завершения и возвращает результат. В примере генерации изображения результат читается как task.output[0] — это и есть выходная ссылка на готовый файл.

Важная деталь из руководства по SDK: остановка ожидания или срабатывание таймаута не отменяют саму задачу. Прерывание waitForTaskOutput останавливает только ваше ожидание, а генерация на стороне сервиса продолжается. Для фактической отмены нужен отдельный endpoint отмены. Практический вывод: если вы прервали ожидание по таймауту, не запускайте новую генерацию вслепую — сначала запросите статус по сохранённому task ID.

Сетевой повтор запроса и повторное создание задачи — разные вещи. Повтор HTTP-запроса при обрыве связи не означает, что нужно заново создавать генерацию: сначала проверьте статус существующей задачи по её ID.

Разбор документированных ошибок

Официальный FAQ разбирает две частые ошибки. Ошибка 400 возникает по одной из двух причин: используется endpoint, которого нет в документации API, либо в коде есть ошибка. В обоих случаях Runway рекомендует проверить код на ошибки.

Ошибка Invalid API key указывает на проблему в коде или формате запроса. Рекомендация та же: проверить код и убедиться, что используется формат из API Reference. Для начала проверьте заголовок Authorization, префикс Bearer и наличие переменной RUNWAYML_API_SECRET.

Отдельный класс — сбой самой задачи. SDK предоставляет TaskFailedError с полем taskDetails. В примерах справки этот тип ошибки перехватывается отдельно от прочих: при сбое генерации выводится сообщение о неудаче и детали задачи. Это позволяет отличить ошибку формата запроса от ошибки выполнения генерации.

Таблица проверки: ключ, модель, изображение, результат

Соберите проверку по этапам. Таблица ниже связывает каждый шаг с входными данными, ожидаемым результатом и способом диагностики.

Изображение можно передать двумя способами. Первый — внешний URL, как в примере справки. Второй — base64 как data URI в поле promptImage; справка отмечает, что это удобно для локального файла и позволяет избежать лишнего сетевого обмена при загрузке. Для генерации изображений на модели gen4_image референсы передаются в referenceImages с тегами, а в promptText на них ссылаются через синтаксис at-mention, например @EiffelTower painted in the style of @StarryNight.

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

Нужен ли отдельный аккаунт для API Runway?

Да. В FAQ Runway указано, что для API-аккаунта нужно зарегистрироваться на dev.runway.com. Это отдельный портал разработчика, где создаётся проект и ключи. Веб-аккаунт приложения и Dev-аккаунт ведут разные балансы.

Почему мои кредиты не отображаются в API?

Кредиты веб-приложения и API полностью раздельны. В FAQ сказано, что купленное на app.runway.com не появится в API-кредитах, и наоборот. Пополнять нужно баланс API-проекта во вкладке billing.

Какую модель использовать для первого запроса?

В справке для первого примера используется модель gen4.5 в режиме image-to-video с параметрами ratio: '1280:720' и duration: 5. Тот же вызов доступен через cURL на hostname api.dev.runwayml.com.

Что делать при ошибке Invalid API key?

Проверьте формат запроса и код. FAQ связывает эту ошибку с проблемой в коде или форматировании и советует сверяться с API Reference. Убедитесь, что ключ лежит в RUNWAYML_API_SECRET или передан в заголовке Authorization с префиксом Bearer.

Можно ли прервать ожидание генерации?

Остановка ожидания или таймаут не отменяют задачу. В руководстве по SDK сказано, что для фактической отмены нужен отдельный endpoint. Сохраните task ID и запросите статус, прежде чем создавать новую генерацию.