runway-api

Runway ML Internal API — Python + MCP

Прямой клиент к internal API Runway (api.runwayml.com/v1). Использует JWT из веб-приложения вместо публичного API ключа. Безлимит работает по подписке — не списывает credits на каждый вызов.

Когда использовать

• Сгенерировать видео в Runway (Seedance 2.0, Gen-4.5, Kling 3.0, etc.)
• Оживить статичные картинки (image-to-video)
• Получить статус задачи по task_id
• Скачать готовый артефакт
• Перебрать TTS-голоса Runway
• Заменить браузерную автоматизацию (skill seedance-runway) на прямые API-вызовы

Architecture

• Auth: JWT из localStorage.RW_TOKEN_PLACEHOLDER веб-приложения. Сохранён в ~/.claude/.credentials.master.env как RUNWAY_TOKEN_PLACEHOLDER. Срок жизни ~30 дней — обновлять по истечении (см. ниже).
• Base URL: https://api.runwayml.com/v1/
• Headers: Authorization: Bearer <JWT>, Origin: https://app.runwayml.com
• Team scoping: большинство endpoints требуют ?asTeamId=<team_id> (RUNWAY_TEAM_ID).

Quick start (CLI)

# Profile / план
python ~/.claude/skills/runway-api/scripts/runway_client.py profile

# Список TTS-голосов
python ~/.claude/skills/runway-api/scripts/runway_client.py voices

# Оценить стоимость
python ~/.claude/skills/runway-api/scripts/runway_client.py estimate seedance_2 \
  --duration 5 --aspect 21:9 --resolution 720p

# Загрузить картинку (получить asset_id и cdn_url)
python ~/.claude/skills/runway-api/scripts/runway_client.py upload C:/path/to/frame.jpg

# Полный цикл — генерация + ожидание + скачивание
python ~/.claude/skills/runway-api/scripts/runway_client.py generate \
  --prompt "Eyes slowly open. Subtle head turn. ARRI Alexa, 50mm." \
  --image C:/path/to/frame.jpg \
  --duration 5 --aspect 21:9 --resolution 720p \
  --download out.mp4

# Polling уже запущенной задачи
python ~/.claude/skills/runway-api/scripts/runway_client.py task <task_id>

Quick start (Python)

from runway_client import RunwayClient

c = RunwayClient()

# Один-шаговый высокоуровневый вызов
task = c.generate_seedance(
    prompt="Eyes slowly open. Subtle head turn. ARRI Alexa, 50mm.",
    image_path="C:/path/to/frame.jpg",
    duration=5,
    aspect_ratio="21:9",
    resolution="720p",
    wait=True,  # block until complete
)
url = c.list_artifacts(task)[0]
c.download(url, "out.mp4")

Quick start (MCP — для Claude Code)

После регистрации MCP сервера в settings.json (см. ниже) Claude Code получает прямые tools:

• runway_profile() — кто залогинен, какой план
• runway_can_start(feature='seedance_2') — есть ли квота
• runway_estimate_cost(feature, duration, aspect_ratio, resolution) — сколько credits
• runway_upload(file_path) — залить картинку, вернуть asset_id + cdn_url
• runway_generate_seedance(prompt, image_path, ...) — запустить Seedance, вернуть task_id
• runway_get_task(task_id) — статус и artifacts
• runway_wait_task(task_id, timeout=1800) — заблокироваться до завершения
• runway_download(url, out_path) — скачать артефакт
• runway_list_voices() — список TTS

Реверс-инжиниринг ключевых endpoints

POST /v1/tasks (создание задачи)

{
  "taskType": "seedance_2",
  "options": {
    "name": "<auto-generated from prompt>",
    "textPrompt": "<user prompt>",
    "duration": 5,
    "aspectRatio": "21:9",
    "resolution": "720p",
    "generateAudio": true,
    "exploreMode": true,
    "numGenerations": 1,
    "creationSource": "tool-mode",
    "referenceImages": [
      {"assetId": "<dataset.id>", "url": "<cdn url>", "type": "first_frame"}
    ]
  }
}

Важно: creationSource: "tool-mode" обязателен (если null — сервер вернёт 400).

Response: {task: {id, status: "PENDING"|"THROTTLED", options, ...}}. Сохраняем task.id и пуллим.

GET /v1/tasks/{id}?asTeamId=X (poll)

Status enum: PENDING → THROTTLED → RUNNING → SUCCEEDED | FAILED | CANCELED.

В SUCCEEDED есть массив artifacts: [{url: <signed CDN URL>, ...}] — это и есть видео-результат. URL подписан JWT, истекает через ~7 дней.

Upload — 4-шаговый flow

# 1. Получить два signed S3 URL — для preview и dataset
preview = POST /v1/uploads {filename, numberOfParts: 1, type: "DATASET_PREVIEW"}
dataset = POST /v1/uploads {filename, numberOfParts: 1, type: "DATASET"}

# 2. PUT bytes на оба signed S3 URL → получить ETag из заголовка
preview_etag = put_s3(preview.uploadUrls[0], file_bytes)
dataset_etag = put_s3(dataset.uploadUrls[0], file_bytes)

# 3. Complete uploads
POST /v1/uploads/{preview.id}/complete {parts: [{PartNumber: 1, ETag: preview_etag}]}
POST /v1/uploads/{dataset.id}/complete {parts: [{PartNumber: 1, ETag: dataset_etag}]}

# 4. Создать dataset record (asset)
POST /v1/datasets {
  fileCount: 1,
  name, uploadId: dataset.id, previewUploadIds: [preview.id],
  metadata: {size: {width, height}},
  type: {name: "image", type: "image", isDirectory: false},
  asTeamId, privateInTeam: true
}
# → response.dataset.id используется как assetId в referenceImages

Стоимость

• Seedance 2.0 5s/720p/21:9 + audio = 180 credits (quantityUnit: "credit" — flat rate)
• Gen-4.5 5s = 60 credits (quantityUnit: "second")
• На Unlimited подписке exploreMode: true ставит в общую очередь без расхода credits (но медленнее).

Полный каталог API (выявлен через шпион-перехват fetch/XHR в браузере)

Profile / Account:

• GET /v1/profile — личный профиль
• GET /v1/profile_for_members?asTeamId=X — профиль в контексте команды
• GET /v1/profile/features?asTeamId=X — feature flags плана
• GET /v1/teams — список команд
• GET /v1/teams/{id}/members — участники
• GET /v1/user_properties?asTeamId=X / PUT /v1/user_properties — UI настройки

Tasks (Generation):

• POST /v1/tasks — создать задачу
• GET /v1/tasks/{id}?asTeamId=X — статус
• GET /v1/tasks/can_start?asTeamId=X&mode=credits&feature=Y — квота
• POST /v1/billing/estimate_feature_cost_credits — оценка стоимости

Assets (Upload):

• POST /v1/uploads (type: DATASET/DATASET_PREVIEW) — signed S3 URL
• POST /v1/uploads/{id}/complete — финализация
• POST /v1/datasets — создание asset record
• GET /v1/asset_groups/by_name?name=X&asTeamId=Y — поиск папки
• GET /v1/asset_references?asTeamId=X — реф-ассеты

Sessions (UI workspace):

• GET /v1/sessions/{sessionId}?asTeamId=X — детали сессии + generations
• GET /v1/sessions/{sessionId}/assets?asTeamId=X — ассеты сессии
• POST /v1/generations — UI-side запись о генерации (после POST /v1/tasks)

Audio / TTS:

• GET /v1/generated_audio/voices — список голосов

Workflows / Apps:

• GET /v1/dynamic_workflow_apps (private/team) — пользовательские apps
• GET /v1/dynamic_workflow_apps_public — публичные шаблоны (Ad Concepter и т.д.)
• GET /v1/custom_presets?order=newest&asTeamId=X — пресеты
• GET /v1/brand_kits?asTeamId=X — бренд-киты

Прочее:

• POST /v1/short_jwt — короткий JWT для подписи assets

Каталог моделей (taskType → feature)

Все модели создаются через POST /v1/tasks с разным taskType. feature используется только в /v1/billing/estimate_feature_cost_credits.

Видео (по провайдерам):

UI Name	taskType	feature	Стоимость	Provider
Seedance 2.0	seedance_2	seedance_2	180c flat (5s/720p/21:9 +audio)	ByteDance
Gen-4.5	gen4.5	gen4.5	60 credits/sec	Runway
Gen-4 Turbo	gen4_turbo	gen4_turbo	25 credits/sec	Runway
Gen-4	gen4	gen4	60 credits/sec	Runway
Characters (talking_avatar)	talking_avatar	talking_avatar	2 credits/sec	Runway
Act-Two	(отдельный app)	—	—	Runway
Kling 3.0 Pro / Standard / Motion	kling_*	similar	tbd	Kling
Kling 2.6 / 2.5 Pro / Turbo	kling_*	similar	tbd	Kling
Veo 3.1 / Veo 3	veo3_* (предположительно)	tbd	tbd	Google
HappyHorse 1.0	tbd	tbd	tbd	(text/image to video)
Multi-Shot Video	(workflow)	—	—	Runway

Image (Nano Banana 2):

UI Name	taskType	feature	model param
Nano Banana 2	gemini_3_1_flash_image	gemini_3_1_flash_image	gemini-3.1-flash-image-preview

Upscale:

UI	taskType (request)	taskType (response)	feature
4K Upscale	media_upscale	harrods (internal)	media_upscale

Routes (для Gen-4 семейства):

• i2v — image-to-video (Gen-4 Turbo)
• k2v — keyframe-to-video (Gen-4.5)
• t2v — text-to-video (предположительно)

Что ещё стоит докрутить (опциональное)

1. TTS (Audio mode) — endpoint не пойман в текущем шпионе. Список голосов: GET /v1/generated_audio/voices. Submit вероятно POST /v1/generated_audio или POST /v1/tasks с taskType="generated_audio". Ещё в Characters есть Character script с Text/Audio переключателем — тот же TTS.
2. Kling, Veo, HappyHorse — точные taskType не пойманы (UI не доезжает до estimate из-за лимита очереди). Подсказка: имя совпадает с UI normalized (например kling_3_pro, veo3, happy_horse_1).
3. Workflows / Apps (/v1/dynamic_workflow_apps) — endpoint известен, payload для запуска workflow не пойман.

Чтобы добавить — открой Runway, включи шпион (см. ниже), сделай нужное действие, посмотри payload в window.__runwaySpy.

Шпион fetch (для добавления новых endpoints)

// Запустить в DevTools console на app.runwayml.com:
window.__runwaySpy = [];
const origFetch = window.fetch;
window.fetch = async function(url, opts) {
  const u = typeof url === 'string' ? url : url.url;
  const method = opts?.method || 'GET';
  let body = opts?.body;
  if (body instanceof FormData) body = '<FormData>';
  else if (body && typeof body === 'string') body = body.slice(0, 2000);
  const resp = await origFetch.apply(this, arguments);
  const clone = resp.clone();
  let r = ''; try { r = (await clone.text()).slice(0, 2000); } catch {}
  if (u.includes('runwayml.com')) {
    window.__runwaySpy.push({t: new Date().toISOString().slice(11,23), method, url: u, status: resp.status, req: body, resp: r});
  }
  return resp;
};
// Сделай в UI нужное действие (Generate / Upload / 4K / etc.)
// Потом:
JSON.stringify(window.__runwaySpy.slice(-30), null, 2)

Обновление JWT (раз в ~30 дней)

// В DevTools console на app.runwayml.com (залогиненный):
copy(localStorage.getItem('RW_TOKEN_PLACEHOLDER'))
// Вставить значение в ~/.claude/.credentials.master.env как RUNWAY_TOKEN_PLACEHOLDER=...

Также проверь RUNWAY_TEAM_ID — id текущей команды:

JSON.parse(localStorage.getItem('rw__lastUsedTeamId')).lastUsedTeamId

Регистрация MCP сервера

Добавь в ~/.claude/mcp.json (или ~/.claude/settings.json под mcpServers):

{
  "mcpServers": {
    "runway": {
      "command": "python",
      "args": ["-u", "${HOME}/.claude/skills/runway-api/scripts/runway_mcp.py"]
    }
  }
}

После рестарта Claude Code появятся tools runway_profile, runway_generate_seedance, etc.

Зависимости

pip install requests python-dotenv mcp pillow

Известные подводные камни

Проблема	Решение
400 creationSource: expected string, received undefined	Добавить "creationSource": "tool-mode" в options
401 Unauthorized	JWT истёк — обновить из браузера
Таски долго в THROTTLED	На Unlimited без credits идёт через explore queue (медленно). Поставь exploreMode=False для priority
numGenerations: undefined warning	Добавить "numGenerations": 1 в options
Upload 200 но dataset не создан	Не забыть POST /v1/datasets после complete
Cyrillic в filename	Работает, но проще дать ASCII имя файла

Связанные скиллы

• seedance-runway — браузерная автоматизация Runway через Playwright (медленнее, но не требует JWT — работает через UI)
• elevenlabs — альтернативный TTS (более качественные русские голоса)
• video-editor — FFmpeg для финальной сборки
• nano-banana-pro — генерация исходных кадров перед animation

Ключевая разница API vs Browser

	Public API (api.runwayml.com/v1/*)	Internal Web API (этот скилл)
Auth	API key (отдельный billing)	JWT из веб-сессии
Биллинг	per-call $$	по подписке (Unlimited)
Доступ к Seedance 2.0	Через ttv-2 endpoint	taskType: "seedance_2" напрямую
Гарантии	Стабильный	Может сломаться при обновлении UI
Скорость	Обычная очередь	Priority queue + Explore mode