RunwayML

RunwayML provides APIs for generating videos with Runway Gen and Runway-hosted models. AISIX lets applications submit and manage those tasks through the gateway's video API while managing the Runway credential, caller access, rate limits, and usage accounting.

This guide configures RunwayML for the AISIX video-generation API. Runway does not provide a chat-completions API, so use Runway-backed model aliases only for video tasks.

Prerequisites

Before starting, prepare the following:

One AISIX setup:
- For AISIX Cloud, an environment with an attached gateway and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
- For the open-source AISIX gateway, prepare either a local AISIX installation or the Docker setup from the Open-Source AISIX Gateway Quickstart. Configure the gateway to load a declarative resources file.
A Runway API key from the Runway developer portal.
curl and jq.

The developer portal is a separate surface from the runwayml.com web app. API keys exist only in the portal, and API credits are a separate pool from web-app credits — a web-app subscription does not fund API calls. See the Runway API FAQs.

Configure with AISIX Cloud

Export the AISIX Cloud connection details:

# Replace with your values
export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Create a provider key, model alias, and caller API key for the Runway-backed video route.

Create a Provider Key

Create the provider key that stores the Runway credential and API root:

# Replace with your value
export RUNWAY_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "runwayml-prod",
    "provider": "runwayml",
    "api_key": "'"${RUNWAY_API_KEY}"'",
    "api_base": "https://api.dev.runwayml.com",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider is runwayml, the provider value the AISIX video routes recognize. The AISIX Cloud Admin API derives the openai adapter for this provider; the adapter field is only accepted on BYO provider keys. The derived adapter applies only to chat-style routes that Runway does not serve.

❷ api_key stores the Runway API key and is sent as a bearer token on upstream calls. It follows the credential-handling behavior in Provider Keys.

❸ api_base is the bare host. Runway's documented API base carries no version segment — the /v1 belongs to the endpoint paths, so AISIX composes /v1/text_to_video and /v1/tasks/{id} onto this root as written. The field is optional for this provider — when it is omitted, the AISIX Cloud Admin API fills in the same value. Set it explicitly so the upstream root stays visible on the resource. Do not append /v1: AISIX strips no version suffix from this provider's base, so https://api.dev.runwayml.com/v1 builds /v1/v1/… paths and fails upstream.

The command captures the returned provider key ID in PROVIDER_KEY_ID.

Create a Model

Runway's text-to-video endpoint — the endpoint the gateway submits to — serves the Gen-family flagship gen4.5, the Runway-hosted Veo models veo3.1, veo3.1_fast, and veo3, and seedance2. Other Runway model IDs, such as the image-to-video model gen4_turbo, are rejected by this endpoint, so an alias naming them fails at submission. Check the Runway API documentation for the current catalog and each model's accepted parameters before creating a model alias.

Create the model alias callers will send in requests:

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "runway-video-prod",
    "model_name": "gen4.5",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name is the alias callers send in model.

❷ model_name is the Runway model ID, for example gen4.5 or veo3.1.

❸ provider_key_id attaches the alias to the RunwayML provider key.

Create a Caller API Key

Create the caller API key that can access the model alias. The plaintext key is server-generated and returned once in the response, so capture it now:

AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "runwayml-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "$AISIX_API_KEY"

The allowed_models value must reference the model ID captured in the previous step, so the key can only access the alias you created. After the write, the configuration projects to attached gateways automatically.

Configure with the Open-Source AISIX Gateway

Export the upstream credential and choose the caller API key that applications will send to the gateway:

export RUNWAY_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

Create a complete declarative resources file for this provider:

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "runwayml-prod"
    provider: "runwayml"
    adapter: "openai"
    api_key: ${RUNWAY_API_KEY}
    api_base: "https://api.dev.runwayml.com"

models:
  - display_name: "runway-video-prod"
    provider: "runwayml"
    model_name: "gen4.5"
    provider_key: "runwayml-prod"

api_keys:
  - display_name: "runwayml-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "runway-video-prod"

If AISIX is installed locally, validate the file before loading it:

aisix validate --resources resources.yaml

After validation, start the gateway with the referenced environment variables in its process environment. Reload an existing gateway only if those variables are already available to the process; otherwise, restart it with the updated environment.

If you use Docker, adapt the validation and startup commands in the Open-Source AISIX Gateway Quickstart. Mount this resources.yaml file and pass every environment variable it references with -e in both commands. After the resources load, prepare the shared verification request below:

export AISIX_PROXY="http://127.0.0.1:3000"
export AISIX_API_KEY="$CALLER_API_KEY"

Verify the Provider Connection

Because this provider serves no chat surface, verify the connection with a video task. Submit it through the AISIX proxy:

curl -sS -X POST "http://127.0.0.1:3000/v1/videos" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "runway-video-prod",
    "prompt": "A lighthouse beam sweeps across a foggy harbor at night.",
    "seconds": 5,
    "size": "1280x720"
  }'

The gateway returns a video job object whose status is queued — Runway's create response confirms only that the task was accepted — and whose id is the gateway-issued video ID for the follow-up calls. Poll the task until it completes, then download the result:

curl -sS "http://127.0.0.1:3000/v1/videos/YOUR_VIDEO_ID" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

curl -sS -L -o video.mp4 \
  "http://127.0.0.1:3000/v1/videos/YOUR_VIDEO_ID/content" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

If the submission fails, check the provider key api_key, the bare-host api_base, and the Runway model ID in model_name. Four provider-specific behaviors are worth knowing before you script around this route:

The gateway sends the mandatory API version header itself. Runway requires an X-Runway-Version header on every API call and rejects requests without it. AISIX sets X-Runway-Version: 2024-11-06 — the API version its request and response handling is written against — on both the submit and the poll calls. The header is not operator-configurable and never appears in gateway configuration.
size maps to Runway's ratio and is required in practice. AISIX converts the unified WIDTHxHEIGHT value to Runway's WIDTH:HEIGHT resolution string by swapping the separator, so 1280x720 reaches Runway as "1280:720". Runway validates the result against a per-model list of supported pixel resolutions, and its text-to-video endpoint requires ratio, so a request without size is rejected by the provider rather than defaulted by the gateway. seconds is forwarded as the provider's integer duration; accepted durations are also model-specific. Check the model's entry in the Runway API documentation for both lists.
THROTTLED is a queued state. AISIX maps Runway's PENDING and THROTTLED task states to queued — both mean the task is accepted but not yet running — with RUNNING reported as in_progress, SUCCEEDED as completed, and FAILED or CANCELLED as failed. A failed task carries Runway's machine-readable failureCode and human-readable failure text in the unified error object.
Finished videos are delivered by redirect. A completed Runway task reports its output as a list of signed URLs, and GET /v1/videos/{id}/content returns 302 with a Location header pointing at the first of them. The bytes travel from Runway's storage to the client and do not pass through the gateway, so use curl -L when downloading.

For the full submit, poll, and download workflow, including status semantics and rate-limit behavior on polling, see Video Generation.

Model IDs and Cost Metadata

RunwayML is not listed on models.dev, the public catalog AISIX Cloud draws model suggestions and pricing from. That has two consequences for this provider:

The dashboard suggests no model IDs. Take IDs from the Runway API documentation and enter them in model_name directly.
The pricing catalog carries no prices for Runway models, so any cost figure used in usage reporting or budget checks is operator-supplied on the model alias — the same posture as bring-your-own endpoints. See Cost Metadata.

Video traffic is additionally bounded by the accounting behavior of the video surface itself: each submission is recorded in usage logs as a zero-token event, and duration-based cost accounting for video tasks is not yet applied to AISIX Cloud budgets. See Video Generation.

Endpoint Coverage

A RunwayML provider key exists for the video routes. Every chat-shaped route resolves a URL under the same bare host, and Runway serves none of them:

Route	Behavior with a `runwayml` model alias
`/v1/videos` and its status and content routes	Supported. This is the only modeled route the provider serves. See Verify the Provider Connection.
`/v1/chat/completions`	Fails upstream. Runway publishes no chat-completions API; AISIX appends `/chat/completions` to the provider key base and the resulting path does not exist at the upstream.
`/v1/embeddings`	Fails upstream. Runway publishes no embeddings API.
`/v1/responses`	Fails upstream. The Responses bridge issues a chat-completions call, which Runway does not serve.
`/v1/images/generations`	Not supported. The route accepts only models whose configured provider is `openai`. Reach Runway's image endpoints through passthrough instead.
`/v1/rerank`	Not supported. The route accepts only the `openai`, `cohere`, and `jina` provider values.
`/passthrough/runwayml/*rest`	Supported for Runway APIs the gateway has not modeled, such as image-to-video. The tunnel forwards caller headers and injects only the credential, so the caller must set `X-Runway-Version` itself — AISIX adds that header only on the modeled video routes.

See Provider Compatibility for the full endpoint and provider matrix.

Next Steps

You have now connected AISIX to RunwayML and verified the model alias with a video task. Continue with these guides:

Model Aliases: configure routing, retry behavior, or cost metadata for this alias.
Video Generation: follow the full submit, poll, and download workflow.
Provider Passthrough: reach Runway APIs the gateway has not modeled.
Provider Compatibility: review supported proxy endpoints and provider-specific boundaries.

Prerequisites​

Configure with AISIX Cloud​

Create a Provider Key​

Create a Model​

Create a Caller API Key​

Configure with the Open-Source AISIX Gateway​

Verify the Provider Connection​

Model IDs and Cost Metadata​

Endpoint Coverage​

Next Steps​