RunwayML

RunwayML 提供使用 Runway Gen 和 Runway 托管模型生成视频的接口。AISIX 让应用可通过网关的视频 API 提交并管理这些任务，同时管理 Runway 凭证、调用方访问权限、限流和用量核算。

本指南介绍如何为 AISIX 视频生成 API 配置 RunwayML。Runway 不提供 Chat Completions API，因此由 Runway 支持的模型别名只能用于视频任务。

准备工作

开始前，请准备以下内容：

• 一套 AISIX 环境：
  • 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
  • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
• 一个从 Runway 开发者门户获取的 Runway API Key。
• curl 和 jq。

开发者门户与 runwayml.com Web 应用相互独立。API Key 仅存在于该门户中，API Credits 与 Web 应用 Credits 也是两个独立的额度池；Web 应用订阅无法为 API 调用提供额度。请参阅 Runway API 常见问题。

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

为 Runway 支持的视频路由创建服务提供方密钥、模型别名和调用方 API Key。

创建服务提供方密钥

创建用于保存 Runway 凭证和 API Root 的服务提供方密钥：

# 请替换为实际值
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 为 runwayml，这是 AISIX 视频路由能够识别的服务提供方值。AISIX Cloud Admin API 会为此服务提供方派生 openai 适配器；adapter 字段仅适用于 BYO 服务提供方密钥。派生的适配器只适用于 Runway 并不提供的 Chat 类路由。

❷ api_key 保存 Runway API Key，并在上游调用中作为 Bearer Token 发送。该值遵循服务提供方密钥中的凭证处理行为。

❸ api_base 是裸主机。Runway 文档中的 API Base 不含版本片段；/v1 属于端点路径，因此 AISIX 会按原样在此 Root 上组合 /v1/text_to_video 和 /v1/tasks/{id}。对于此服务提供方，该字段可选；省略时，AISIX Cloud Admin API 会填入相同值。请显式设置该字段，让上游 Root 在资源中清晰可见。不要追加 /v1：AISIX 不会从此服务提供方的 Base 中移除版本后缀，因此 https://api.dev.runwayml.com/v1 会构造 /v1/v1/… 路径并在上游失败。

该命令会把返回的服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。

创建模型

Runway 的文生视频端点（即网关提交任务的端点）目前提供 gen4.5、veo3.1、veo3.1_fast、veo3、happyhorse_1_0、seedance2、seedance2_fast、seedance2_mini 和 gemini_omni_flash。该端点会拒绝其他 Runway 模型 ID，例如图生视频模型 gen4_turbo，因此指向这些模型的别名会在提交时失败。创建模型别名前，请在 Runway API 参考中查看当前目录以及各模型接受的参数。

创建调用方将在请求中发送的模型别名：

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 是调用方在 model 中发送的别名。

❷ model_name 是 Runway 模型 ID，例如 gen4.5 或 veo3.1。

❸ provider_key_id 将该别名关联到 RunwayML 服务提供方密钥。

创建调用方 API Key

创建可访问该模型别名的调用方 API Key。明文密钥由服务器生成，并且只在响应中返回一次，因此请立即保存：

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"

allowed_models 值必须引用上一步保存的模型 ID，使该密钥只能访问已创建的别名。写入后，配置会自动投射到已关联的网关。

使用开源 AISIX 网关配置

导出上游凭证，并选择应用将发送给网关的调用方 API Key：

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

对于新网关，请使用此完整资源文件。对于现有网关，请将这些条目合并到其当前文件中，并保留其他资源：

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"

如果 AISIX 安装在本地，请在加载前验证文件：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供文件引用的环境变量，再启动网关。仅当这些变量已经可供进程使用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两条命令中使用 -e 传入它引用的每个环境变量。资源加载后，准备下文共用的验证请求：

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接

导出 AISIX 网关 Origin：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

由于此服务提供方不提供 Chat 接口，请使用视频任务验证连接。通过 AISIX 代理提交任务：

curl -sS -X POST "$AISIX_PROXY/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"
  }'

网关返回一个视频任务对象，其中 status 为 queued（Runway 的创建响应仅确认任务已被接受），id 则是网关颁发、供后续调用使用的视频 ID。轮询任务直至完成，然后下载结果：

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

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

如果提交失败，请检查服务提供方密钥的 api_key、采用裸主机的 api_base，以及 model_name 中的 Runway 模型 ID。在围绕此路由编写脚本前，需要了解以下四种服务提供方特定行为：

• 网关会自行发送必需的 API 版本请求头。 Runway 要求每次 API 调用都带有 X-Runway-Version 请求头，并拒绝不含该请求头的请求。AISIX 会在提交和轮询调用中设置 X-Runway-Version: 2024-11-06，这是其请求和响应处理所依据的 API 版本。该请求头不可由运维人员配置，也不会出现在网关配置中。
• size 会映射到 Runway 的 ratio，且实际使用中为必填。 AISIX 通过替换分隔符，将统一的 WIDTHxHEIGHT 值转换为 Runway 的 WIDTH:HEIGHT 分辨率字符串，因此 1280x720 会以 "1280:720" 到达 Runway。Runway 会根据各模型支持的像素分辨率列表验证结果，而且其文生视频端点要求 ratio，因此缺少 size 的请求会被服务提供方拒绝，而不是由网关填入默认值。seconds 会作为服务提供方的整数 duration 转发；可接受的时长也因模型而异。请在 Runway API 文档的相应模型条目中查看这两个列表。
• 标准化路由只建模通用的文生视频字段。 AISIX 会发送上游模型 ID、promptText，以及上述可选的 ratio 和 duration 映射。其他 JSON 字段会被忽略，包括负面提示词、生成音频选项和参考媒体等 Runway 专用控制项。若要使用这些字段，请通过 /passthrough/runwayml/v1/text_to_video 发送 Runway 原生请求体、准确的上游模型 ID，以及必需的 X-Runway-Version: 2024-11-06 请求头。本页的 /passthrough/runwayml 路径假定一条透传路由认领该前缀，target_url 设为 Runway 的 API 根地址；在调用方 Key 的 allowed_routes 上授予路由名称。
• THROTTLED 属于排队状态。 AISIX 将 Runway 的 PENDING 和 THROTTLED 任务状态映射为 queued，两者都表示任务已接受但尚未运行；RUNNING 报告为 in_progress，SUCCEEDED 报告为 completed，FAILED 或 CANCELLED 报告为 failed。失败任务会在统一的 error 对象中携带 Runway 机器可读的 failureCode 和人类可读的 failure 文本。
• 完成的视频通过重定向交付。 已完成的 Runway 任务会将输出报告为签名链接列表，而 GET /v1/videos/{id}/content 返回 302，其 Location 响应头指向列表中的第一个链接。视频字节会直接从 Runway 存储传输到客户端，不经过网关，因此下载时请使用 curl -L。

完整的提交、轮询和下载工作流（包括状态语义和轮询时的限流行为）请参阅视频生成。

模型 ID 和成本元数据

AISIX Cloud 从公开目录 models.dev 获取模型建议和定价，而 RunwayML 未列入该目录。这会给此服务提供方带来两个影响：

• Dashboard 不会建议模型 ID。请从 Runway API 文档获取 ID，并直接填入 model_name。
• 定价目录不包含 Runway 模型的价格，因此用量报告或预算检查中使用的任何成本数据都需由运维人员在模型别名上提供，这与自带端点的处理方式相同。请参阅成本元数据。

视频流量还受视频接口自身核算行为的限制：每次提交都会在用量日志中记录为零 Token 事件，基于时长的视频任务成本核算尚未应用于 AISIX Cloud 预算。请参阅视频生成。

端点覆盖范围

RunwayML 服务提供方密钥用于视频路由。所有 Chat 格式路由都会解析到同一裸主机下的 URL，但 Runway 不提供其中任何路由：

路由	使用 runwayml 模型别名时的行为
/v1/videos 及其状态和内容路由	支持。这是该服务提供方唯一提供的已建模路由。请参阅验证服务提供方连接。
/v1/chat/completions	在上游失败。Runway 未发布 Chat Completions API；AISIX 会向服务提供方密钥 Base 追加 /chat/completions，但生成的路径在上游不存在。
/v1/embeddings	在上游失败。Runway 未发布 Embeddings API。
/v1/responses	在上游失败。Responses 桥接会发起 Chat Completions 调用，而 Runway 不提供该调用。
/v1/images/generations	不支持。该路由仅接受所配置服务提供方为 openai 的模型。请改为通过透传访问 Runway 图像端点。
/v1/rerank	不支持。该路由仅接受 openai、cohere 和 jina 服务提供方值。
/passthrough/runwayml/*rest	通过已配置的透传路由可用于网关尚未建模的 Runway API 和字段，包括图生视频和服务提供方专用的文生视频控制项。路由会转发调用方请求头，并且只注入凭证，因此调用方必须自行设置 X-Runway-Version；AISIX 只会在已建模的视频路由上添加该请求头。

完整端点和服务提供方矩阵请参阅服务提供方兼容性。

后续步骤

你已将 AISIX 连接到 RunwayML，并通过视频任务验证了模型别名。接下来可阅读以下指南：

• 模型别名：为此别名配置路由、重试行为或成本元数据。
• 视频生成：完成完整的提交、轮询和下载工作流。
• 透传路由：访问网关尚未建模的 Runway 接口。
• 服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。