> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getbifrost.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Runway ML

> Runway ML API conversion guide - text-to-video, image-to-video, and video-to-video generation

## Overview

Runway ML provides video generation via an asynchronous task-based API. Bifrost maps the unified video schema to Runway's task API and polls until completion.

### Supported Operations

| Operation        | Supported | Endpoint                                                        |
| ---------------- | --------- | --------------------------------------------------------------- |
| Video Generation | ✅         | `/v1/text_to_video`, `/v1/image_to_video`, `/v1/video_to_video` |
| Video Retrieve   | ✅         | `/v1/tasks/{task_id}`                                           |
| Video Download   | ✅         | via Retrieve + URL download                                     |
| Video Delete     | ✅         | `/v1/tasks/{task_id}` (cancel)                                  |
| Video List       | ❌         | -                                                               |
| Video Remix      | ❌         | -                                                               |

***

# 1. Video Generation

## Generate (`POST /v1/videos`)

**Request Parameters**

| Parameter         | Type   | Required | Notes                                                                                  |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `model`           | string | ✅        | Runway model                                                                           |
| `prompt`          | string | ✅        | Text description of the video                                                          |
| `input_reference` | string | ❌        | Input image for image-to-video                                                         |
| `seconds`         | string | ❌        | Duration in seconds (default: `"2"`)                                                   |
| `size`            | string | ❌        | Resolution as `WxH` (e.g., `1280x720`; default: `1280x720`) - converted to `W:H` ratio |
| `seed`            | int    | ❌        | **Gen models only**                                                                    |
| `audio`           | bool   | ❌        | Enable audio generation. **Veo models only**                                           |
| `video_uri`       | string | ❌        | Source video URL for video-to-video. **gen4\_aleph only**                              |

**Extra Params**

| Key                  | Type   | Notes                                                                       |
| -------------------- | ------ | --------------------------------------------------------------------------- |
| `references`         | array  | Video reference objects `[{"uri": "...", "tag": "..."}]` for video-to-video |
| `content_moderation` | object | Content moderation config                                                   |
| `reference_images`   | array  | Reference image objects for style/asset guidance                            |

**Generation Modes** (auto-detected from inputs)

* **Text-to-video**: `prompt` only
* **Image-to-video**: `prompt` + `input_reference`
* **Video-to-video**: `prompt` + `video_uri` - **gen4\_aleph only**

**Response**: [`BifrostVideoGenerationResponse`](https://github.com/maximhq/bifrost/blob/main/core/schemas/videos.go) with `id`, `status`, `videos[]`

**Bifrost statuses** (normalized): `queued` → `in_progress` → `completed` / `failed`

These values are the normalized view returned by Bifrost's API. Runway's native statuses are: `PENDING`, `THROTTLED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`.

## Retrieve / Download / Delete

| Operation        | Endpoint                      | Notes                          |
| ---------------- | ----------------------------- | ------------------------------ |
| Get status       | `GET /v1/videos/{id}`         | Poll until `status: completed` |
| Download content | `GET /v1/videos/{id}/content` | Returns raw video bytes (MP4)  |
| Cancel/Delete    | `DELETE /v1/videos/{id}`      | Cancels the running task       |

***

## Configuration

<Tabs>
  <Tab title="Gateway">
    ```bash theme={null}
    curl --location 'http://localhost:8080/api/providers' \
    --header 'Content-Type: application/json' \
    --data '{
        "provider": "runway",
        "keys": [
            {
                "name": "runway-key-1",
                "value": "env.RUNWAY_API_KEY",
                "models": ["*"],
                "weight": 1.0
            }
        ]
    }'
    ```

    See **[Provider Configuration](../../quickstart/gateway/provider-configuration)** for full setup options.
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    case schemas.Runway:
        return []schemas.Key{{
            Value:  os.Getenv("RUNWAY_API_KEY"),
            Models: []string{"*"},
            Weight: 1.0,
        }}, nil
    ```

    See **[Provider Configuration](../../quickstart/go-sdk/provider-configuration)** for full setup options.
  </Tab>
</Tabs>

***

## Reference Links

* [Runway ML API Documentation](https://docs.dev.runwayml.com/)
* [Runway ML Models](https://runwayml.com/research/)