Runway Gen4 Image API

Runway Gen4 Image API

Runway Gen4 Image создаёт изображения по текстовому описанию. Главная её сила - референсы: можно передать до трёх картинок, и модель перенесёт в новую сцену того же человека, предмет, одежду или стиль. Так удобно делать серию кадров с одним персонажем, ставить товар в разные интерьеры или менять время суток на знакомой сцене.

Основные сценарии:

• Генерация по тексту - без входных изображений.
• Генерация с одним референсом - например, тот же человек в новой обстановке.
• Генерация с несколькими референсами - от 2 до 3 картинок: персонаж, одежда, место.

Каждый вызов создаёт асинхронную операцию. Сохраните её id из ответа и проверяйте статус отдельным запросом.

Создание операции

• Endpoint: POST /api/v1/operations
• Авторизация: Authorization: Bearer brth_...
• Выполнение асинхронное: запрос сразу возвращает id и стартовый статус queued.

Отдельного переключателя режимов нет: если передать reference_images, модель опирается на референсы, если не передать - рисует только по тексту.

Тело запроса

{
  "tool": "runway-gen4-image",
  "input": {
    "prompt": "...",
    "reference_images": [
      "https://cdn.example.com/reference-1.jpg",
      "https://cdn.example.com/reference-2.jpg"
    ],
    "aspect_ratio": "4:3",
    "resolution": "1080p"
  }
}

• tool - slug нейросети, всегда "runway-gen4-image".
• input - параметры запуска. Все поля передаются прямо внутри этого объекта, без дополнительной вложенности.

Параметры

Для reference_images нужны внешние http/https ссылки, которые открываются без авторизации. Размер одного файла - до 128 МБ.

Примеры запросов

Генерация по тексту

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "runway-gen4-image",
  "input": {
    "prompt": "Маленький книжный магазин на углу старой улицы в дождливый вечер, тёплый свет в витрине, отражения фонарей в лужах, реалистичная фотография",
    "aspect_ratio": "16:9",
    "resolution": "1080p"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'runway-gen4-image',
    input: {
      prompt: 'Маленький книжный магазин на углу старой улицы в дождливый вечер, тёплый свет в витрине, отражения фонарей в лужах, реалистичная фотография',
      aspect_ratio: '16:9',
      resolution: '1080p',
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'runway-gen4-image',
        'input': {
            'prompt': 'Маленький книжный магазин на углу старой улицы в дождливый вечер, тёплый свет в витрине, отражения фонарей в лужах, реалистичная фотография',
            'aspect_ratio': '16:9',
            'resolution': '1080p',
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Генерация с одним референсом

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "runway-gen4-image",
  "input": {
    "prompt": "Этот же человек с референса сидит в уютной кофейне у окна с чашкой капучино, вечер, тёплый свет ламп, реалистичная фотография",
    "reference_images": [
      "https://cdn.example.com/reference-1.png"
    ],
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'runway-gen4-image',
    input: {
      prompt: 'Этот же человек с референса сидит в уютной кофейне у окна с чашкой капучино, вечер, тёплый свет ламп, реалистичная фотография',
      reference_images: [
        'https://cdn.example.com/reference-1.png',
      ],
      aspect_ratio: '16:9',
      resolution: '720p',
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'runway-gen4-image',
        'input': {
            'prompt': 'Этот же человек с референса сидит в уютной кофейне у окна с чашкой капучино, вечер, тёплый свет ламп, реалистичная фотография',
            'reference_images': [
                'https://cdn.example.com/reference-1.png',
            ],
            'aspect_ratio': '16:9',
            'resolution': '720p',
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Генерация с несколькими референсами

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "runway-gen4-image",
  "input": {
    "prompt": "Девушка с первого референса в пальто со второго референса идёт по улице из третьего референса, осенний день, съёмка в полный рост",
    "reference_images": [
      "https://cdn.example.com/reference-1.jpg",
      "https://cdn.example.com/reference-2.jpg",
      "https://cdn.example.com/reference-3.webp"
    ],
    "aspect_ratio": "3:4",
    "resolution": "1080p"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'runway-gen4-image',
    input: {
      prompt: 'Девушка с первого референса в пальто со второго референса идёт по улице из третьего референса, осенний день, съёмка в полный рост',
      reference_images: [
        'https://cdn.example.com/reference-1.jpg',
        'https://cdn.example.com/reference-2.jpg',
        'https://cdn.example.com/reference-3.webp',
      ],
      aspect_ratio: '3:4',
      resolution: '1080p',
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'runway-gen4-image',
        'input': {
            'prompt': 'Девушка с первого референса в пальто со второго референса идёт по улице из третьего референса, осенний день, съёмка в полный рост',
            'reference_images': [
                'https://cdn.example.com/reference-1.jpg',
                'https://cdn.example.com/reference-2.jpg',
                'https://cdn.example.com/reference-3.webp',
            ],
            'aspect_ratio': '3:4',
            'resolution': '1080p',
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Примеры ответов

Ответ после создания

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "runway-gen4-image",
  "cost": 8,
  "balance_after": 492,
  "created_at": "2026-09-30T19:50:36.759732+00:00"
}

Ответ после завершения

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "runway-gen4-image",
  "cost": 8,
  "created_at": "2026-09-30T19:50:36.759732+00:00",
  "completed_at": "2026-09-30T19:53:10.125197+00:00",
  "result": {
    "type": "image",
    "urls": [
      "https://storage.bratuha.ru/results/runway-gen4-image/image-1.png"
    ]
  },
  "error_message": null
}

Ответ при ошибке

{
  "id": "op_uuid-123",
  "status": "failed",
  "tool": "runway-gen4-image",
  "cost": 8,
  "created_at": "2026-09-30T19:50:36.759732+00:00",
  "completed_at": "2026-09-30T19:50:51.402118+00:00",
  "result": null,
  "error_message": "Ваш запрос не прошел модерацию."
}

Проверка статуса

Сохраните id из ответа на создание и запрашивайте статус операции по нему:

GET /api/v1/operations/{id}

curl -H "Authorization: Bearer brth_ваш_ключ" \
  https://bratuha.ru/api/v1/operations/op_uuid-123

async function waitForResult(id: string) {
  while (true) {
    const response = await fetch(`https://bratuha.ru/api/v1/operations/${id}`, {
      headers: { Authorization: 'Bearer brth_ваш_ключ' },
    })
    const operation = await response.json()
    if (operation.status === 'completed' || operation.status === 'failed') {
      return operation
    }
    await new Promise((resolve) => setTimeout(resolve, 5000))
  }
}

Статус меняется с queued на processing, а затем на completed или failed. Обычно картинка готова меньше чем за минуту, но иногда генерация занимает 2-3 минуты. Опрашивать одну операцию можно не чаще раза в секунду, разумный интервал - 3-5 секунд.

Формат результата

После завершения в result приходит:

{
  "type": "image",
  "urls": [
    "https://storage.bratuha.ru/results/runway-gen4-image/image-1.png"
  ]
}

• type - всегда "image".
• urls - массив с одной ссылкой на готовое изображение в формате PNG.

Размер зависит от resolution и aspect_ratio: например, 16:9 в 720p приходит размером 1280 × 720 пикселей.

Ценообразование

Цена фиксирована за одно изображение и зависит только от разрешения. Число референсов, пропорции и длина задания на цену не влияют.

Стоимость списывается при создании операции и приходит в поле cost ответа.

Ограничения и практические заметки

• POST /api/v1/operations не идемпотентен: каждый повторный запрос создаёт новую оплаченную операцию. Если ответ потерялся, не повторяйте запрос вслепую.
• Все операции асинхронные: сначала приходит queued, результат забирается по id.
• Референсов - не больше трёх. Ссылки должны быть внешними http/https URL на файлы jpg, jpeg, png или webp.
• Референс - это образец, а не исходник для точечной правки: модель рисует новый кадр и переносит в него то, что вы описали. Чем яснее в задании сказано, что взять с какого референса, тем точнее результат.
• Один запуск - одно изображение. Нужно несколько вариантов - отправьте несколько запросов.
• Задания проходят модерацию. Если запрос её не прошёл, операция завершится со статусом failed и сообщением «Ваш запрос не прошел модерацию.»