OpenRouter 视频生成 API 的接入难点通常不在请求怎么写而在任务怎么异步化、错误怎么处理、结果怎么落盘。很多开发者第一次调用文本模型很顺利换到视频生成就发现同一个 Key、同一个网关返回却从一段完整文本变成了一个任务 ID。这篇文章采用代码优先的方式从创建 API Key 开始逐步完成一个可运行的视频生成接入脚本并给出参数说明、响应解析、异步轮询和常见错误排查方法。文中所有代码都以最小可运行作为目标读者可以把示例复制到自己的 Python 项目中再按实际模型 ID 和业务需求调整。1. 先理解 OpenRouter 视频生成 API 的调用模型1.1 聚合网关解决多提供商接入成本OpenRouter 是一个模型聚合网关它把来自不同提供商的模型统一到一套 API 体系里。对开发者来说最大的收益不是某一个模型有多强而是接入方式统一了。以往接入视频生成能力需要阅读每个厂商的鉴权文档、请求格式、错误码和返回结构使用聚合网关后大部分请求只需要调整模型 ID 和少量生成参数。视频生成 API 同样可以走这个思路。调用时客户端向 OpenRouter 网关发送一个包含模型 ID、提示词、可选参数的请求网关负责路由到实际供应商。供应商的质量、价格和并发表现会不同但对业务代码来说它们共享一套鉴权和响应解析逻辑。这里要注意一点OpenRouter 上的模型池会随时间调整不同账号能看到的能力可能不同。代码里的模型 ID 必须以控制台或模型列表页展示的 ID 为准不能从历史文章里复制一个 ID 就当成永久可用。1.2 视频生成任务为什么通常是异步的文本生成通常只需要几秒客户端可以一直等待最终结果。视频生成不一样从提示词到完整视频文件可能需要十几秒甚至几分钟。如果把请求保持同步连接一旦中间网络抖动客户端就会看到一个连接中断错误但服务端任务其实还在运行。因此生产级接入不能把第一次请求响应当成最终结果。常见做法是提交请求拿到任务 ID。轮询状态接口或者接收服务端回调。状态变为成功或失败后再处理结果。如果某些模型在支持范围内返回了直接可用的资源 URL也需要对 URL 的有效期做校验。很多临时地址会在几小时内失效业务系统不要直接持久化这类地址应该尽快下载到自己的对象存储或本地磁盘。1.3 接入前必须确认的边界条件在写代码之前先确认以下边界条件否则后面容易出现“能跑通一次但无法稳定上线”的问题账号是否拥有视频生成相关模型的访问权限。目标模型的计费方式是按次、按时长还是按分辨率。请求是同步返回还是需要轮询。结果 URL 是否有有效期限制。生成内容是否需要进行合规审核是否允许直接对外展示。这些信息在 OpenRouter 控制台和模型详情页都能查看。实际项目里最容易出问题的不是请求语法而是没有考虑到异步任务失败后的重试和费用控制。2. 环境准备API Key、网络检查和 Python 依赖2.1 注册并创建访问凭证第一次使用 OpenRouter 时需要先注册账号然后在控制台的 Keys 页面创建 API Key。创建时会给出一段以sk-or-开头的密钥这个密钥只会完整显示一次页面刷新后无法再次查看。创建 Key 时的命名建议带上用途和环境前缀例如local-dev本地开发调试用。test-runner自动化测试环境用。prod-api生产服务专用。生产环境的 Key 要单独创建不要和本地开发共用。这样即使本地密钥泄露也不会影响线上服务同时可以通过控制台的用量明细观察每个 Key 的调用情况。2.2 用环境变量保存密钥不要写死在代码里把 API Key 写死在代码仓库里是风险最高的做法。仓库一旦被推送到公开平台或者内部成员不小心泄露密钥就会被滥用。推荐使用环境变量或本地.env文件管理。在项目根目录创建.env文件OPENROUTER_API_KEYsk-or-xxxxxxxxxxxxxxxx OPENROUTER_API_BASEhttps://openrouter.ai/api/v1然后在.gitignore中确认.env被忽略.envPython 代码中通过环境变量读取import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(OPENROUTER_API_KEY) api_base os.getenv(OPENROUTER_API_BASE, https://openrouter.ai/api/v1) if not api_key: raise RuntimeError(缺少 OPENROUTER_API_KEY 环境变量)注意.env文件专门用于本地开发。生产环境应该由部署平台注入环境变量而不是把.env文件传到服务器上。2.3 检查网络和超时策略不同地区访问同一个网关延迟和稳定性差异很大。实际项目里不要一开始就假设网络一定可用先用最简单的方式做一次连通性测试。curl -I --max-time 10 https://openrouter.ai/api/v1如果返回结果包含 HTTP 状态码说明网络链路可以到达网关。如果请求一直卡住直到超时优先排查 DNS 解析、防火墙规则和出口 IP 限制而不是在业务代码里无限调大超时时间。在编写正式代码时要给 HTTP 客户端设置两层超时连接超时建立 TCP 连接的最大等待时间。读取超时等待响应数据块的最大时间。不要把timeout设置为空或者一个极大的值否则服务端异常时客户端可能无限挂起。2.4 准备 Python 工作目录与依赖这篇指南的代码基于 Python 3.9 以上版本主要依赖两个库requests发送 HTTP 请求。python-dotenv读取本地环境变量。安装命令pip install requests python-dotenv建议在虚拟环境中安装避免污染系统级 Python 环境。创建虚拟环境并激活python -m venv venv source venv/bin/activate # Windows 下使用 venv\Scripts\activate依赖安装完成后可以建立一个video_client.py文件后续代码都写在这个文件里。先把最简单的基础结构搭好import os import requests from dotenv import load_dotenv load_dotenv() API_KEY os.getenv(OPENROUTER_API_KEY) API_BASE os.getenv(OPENROUTER_API_BASE, https://openrouter.ai/api/v1) HEADERS { Authorization: fBearer {API_KEY}, Content-Type: application/json, }这段代码定义了一个全局请求头后面所有请求都会复用。创建请求时只需要传入具体路径和请求体。3. 最小可运行案例提交视频生成请求3.1 模型 ID 从哪来OpenRouter 的模型 ID 通常由提供商名和模型名组成中间用斜杠分隔。视频生成类模型的 ID 需要在控制台模型列表中搜索“video”等关键词确认不同供应商提供的模型 ID 命名方式不同。不要从网上复制一个模型 ID 就直接使用。模型列表页会展示当前可以调用的模型、上下文长度、计费单位、是否支持图片输入等信息。选择模型时除了关注名称还要看它是支持“文生视频”还是“图生视频”这会影响请求参数。如果你在控制台没有看到视频生成相关模型说明当前账号或地区可用的模型池不同以控制台实际展示为准。3.2 用 curl 发起第一个请求先用 curl 做一个最小请求目的是快速验证 Key、接口路径和模型 ID 是否正确。curl -X POST https://openrouter.ai/api/v1/chat/completions \ -H Authorization: Bearer $OPENROUTER_API_KEY \ -H Content-Type: application/json \ -d { model: your-provider/your-video-model, messages: [ { role: user, content: 一只橘猫在草地上慢慢走动镜头跟随光线自然 } ] }这里使用/chat/completions作为 OpenAI 兼容入口。如果你的模型文档里明确使用了视频生成专用端点请以官方文档为准。your-provider/your-video-model需要替换成控制台里实际存在的模型 ID。第一次请求如果返回 401说明 Key 无效或环境变量没有正确传递。如果返回 400通常是模型 ID 不存在、请求体格式不匹配或缺参数。如果返回 529说明服务端当前负载过高属于暂时性错误可以等几秒重试。3.3 用 Python 脚本完成提交下面这段代码把上面的 curl 请求改写成 Python 脚本并做了一些基础校验import os import requests from dotenv import load_dotenv load_dotenv() API_KEY os.getenv(OPENROUTER_API_KEY) API_BASE os.getenv(OPENROUTER_API_BASE, https://openrouter.ai/api/v1) HEADERS { Authorization: fBearer {API_KEY}, Content-Type: application/json, } def create_video_task(model: str, prompt: str, **kwargs): url f{API_BASE}/chat/completions payload { model: model, messages: [ {role: user, content: prompt} ], } # 允许调用方传入额外参数例如 image、duration 等 payload.update(kwargs) response requests.post(url, headersHEADERS, jsonpayload, timeout(10, 120)) response.raise_for_status() return response.json() if __name__ __main__: result create_video_task( modelyour-provider/your-video-model, prompt一只橘猫在草地上慢慢走动镜头跟随光线自然, duration10 ) print(result)这个函数可以直接在交互式环境里运行也可以被其他模块调用。timeout(10, 120)表示连接超时 10 秒读取超时 120 秒。视频生成任务如果返回时间较长120 秒不一定够所以这只是“提交请求”阶段的超时限制后面的轮询逻辑单独控制。3.4 第一次运行可能看到的响应不同模型对视频生成的响应结构不同但通过 OpenAI 兼容接口提交时通常会有以下两种形态第一种响应体直接包含结果信息{ id: gen_abc123, object: video.generation, status: completed, output: { video_url: https://example.com/tmp/video_abc123.mp4 } }第二种响应体只是一个任务占位符需要继续轮询{ id: gen_abc123, status: queued, model: your-provider/your-video-model }拿到响应后不要直接假设video_url一定存在。先用代码判断状态和字段再决定是解析结果还是进入轮询流程。4. 请求参数、返回结构和 OpenAI 兼容层差异4.1 请求参数速查表下面列出视频生成请求中常见参数的通用说明。具体支持哪些参数以目标模型和 OpenRouter 文档为准。参数类型含义默认值注意事项modelstring模型 ID无必须与控制台一致promptstring描述生成内容的文本无尽量具体包含主体、动作、环境、光照和镜头imagestring 或 URL参考图用于图生视频无部分模型支持格式可能是 base64 或 URLdurationinteger期望视频时长单位秒模型默认不是所有模型都支持传了不支持的参数会 400resolutionstring分辨率例如1080p模型默认分辨率越高耗时和费用可能越高qualitystring质量档位模型默认低档位适合快速验证流程extra_bodyobject模型特有扩展参数无OpenAI SDK 中可以使用extra_body这里有一个容易混淆的点OpenAI SDK 的chat.completions.create方法只会读取它认识的参数。视频模型特有参数如果没有对应的 SDK 参数名不能直接放进model或messages下面应该通过extra_body传递或者直接使用requests构造完整 JSON。4.2 同步返回与异步任务状态一个视频生成请求的生命周期大致是queued - processing - completed / failedqueued表示请求已经进入服务端队列等待资源分配。processing表示模型正在生成视频。completed表示生成成功结果中应该包含可下载地址。failed表示生成失败响应中通常会带有错误信息。如果接口设计为同步返回那么在生成完成前HTTP 连接会一直处于打开状态。这种方式对短任务友好但对长时间视频不友好因为中间任何一个网络节点断开客户端都无法拿到结果只能重新提交。建议在代码里明确区分“请求已受理”和“生成完成”两个概念。凡是返回状态不是最终态都走轮询逻辑。4.3 响应字段说明与判空拿到响应后先提取任务 ID 和状态字段再根据状态处理结果。下面是通用解析逻辑def extract_status(data: dict): if not isinstance(data, dict): raise ValueError(响应不是 JSON 对象) task_id data.get(id) status data.get(status) or data.get(state, unknown) output data.get(output) if isinstance(output, dict): video_url output.get(video_url) elif isinstance(output, str): video_url output else: video_url None return { task_id: task_id, status: status, video_url: video_url, }这里用output可能为字符串、字典或缺失的情况做兼容。实际项目里不同模型的字段命名可能不同有的是output.video_url有的是output.url有的是data.video_url。接入前先看一次真实响应再定字段解析规则。4.4 openai SDK 可以直接用吗OpenAI Python SDK 可以用于 OpenRouter 的 OpenAI 兼容端点但视频生成场景要慎重。原因在于视频生成可能涉及异步任务轮询而 SDK 原生按文本生成的方式设计。视频特有的参数不能全部通过**kwargs传入部分参数会被 SDK 过滤或报错。错误响应的解析方式可能与文本接口不同。如果只是为了快速验证可以这样用from openai import OpenAI client OpenAI( api_keyAPI_KEY, base_urlhttps://openrouter.ai/api/v1, ) response client.chat.completions.create( modelyour-provider/your-video-model, messages[{role: user, content: 一只橘猫在草地上走动}], extra_body{duration: 10}, )如果 SDK 版本不支持某个参数或者目标接口不是/chat/completions路径直接使用requests反而更可控。代码优先的意思是以 API 协议为准而不是以某个 SDK 的方法签名为准。5. 轮询任务、校验结果并保存视频文件5.1 轮询策略间隔、上限、指数退避视频生成任务耗时通常不确定。轮询间隔太短会占用服务端资源也容易触发限流轮询间隔太长会让用户等待过久。推荐的轮询策略初始间隔 2 秒。每次轮询后间隔增加 1 到 2 秒或者使用指数退避。设置最大轮询次数例如 60 次。如果超过最大次数仍未完成把任务标记为超时不要无限循环。如果业务要求更高实时性优先考虑服务端回调或任务完成通知而不是用极短间隔暴力轮询。5.2 实现一个可中断的轮询脚本下面这段代码在提交请求后根据响应状态决定是否轮询。为了方便本地测试增加了任务超时控制import time POLL_INTERVAL 3 MAX_POLL_COUNT 60 def query_task(task_id: str): url f{API_BASE}/video/generations/{task_id} response requests.get(url, headersHEADERS, timeout(10, 30)) response.raise_for_status() return response.json() def wait_for_video(task_id: str): for attempt in range(1, MAX_POLL_COUNT 1): data query_task(task_id) status data.get(status, unknown) if status in (completed, succeeded): return data if status in (failed, error, cancelled): raise RuntimeError(f视频生成失败: {data.get(error)}) print(f[{attempt}/{MAX_POLL_COUNT}] 当前状态: {status}) time.sleep(POLL_INTERVAL) raise TimeoutError(视频生成任务超时)轮询接口的路径需要结合 OpenRouter 文档确认。如果文档只给出了任务查询路径的示例替换成实际地址即可。wait_for_video函数只负责轮询不负责下载职责边界更清晰。5.3 校验下载文件避免只检查状态码当轮询到completed状态后先从响应中提取视频地址再下载文件。下载时不能只看 HTTP 状态码是 200还要检查文件大小和扩展名。import os import requests def download_video(video_url: str, save_path: str): response requests.get(video_url, streamTrue, timeout(10, 300)) response.raise_for_status() temp_path save_path .tmp total_size 0 with open(temp_path, wb) as f: for chunk in response.iter_content(chunk_size8192): if chunk: f.write(chunk) total_size len(chunk) if total_size 1024: os.remove(temp_path) raise ValueError(下载文件小于 1KB疑似异常响应) os.replace(temp_path, save_path) return save_path使用临时文件加os.replace是为了防止下载中途进程异常退出留下一个半截文件。如果文件太小直接删除临时文件并抛出异常不要覆盖最终结果。5.4 用日志和中间文件支持断点续跑生产环境里视频生成任务可能因为进程重启、网络抖动、代码部署而中断。建议任务提交后立即将任务 ID 写入本地队列或数据库轮询完成后再更新状态。日志至少要记录三个阶段任务提交成功记录任务 ID、模型 ID、请求时间。轮询中间状态记录第几次轮询、当前状态、耗时。最终结果记录成功、失败、文件大小、保存路径。这样即使某一个任务失败也能从日志中恢复任务 ID重新查询最终状态避免重复提交导致重复扣费。6. 高频错误排查从负载超限到参数校验6.1 429 与 529服务端负载过高在视频生成调用中最容易遇到的是负载类错误。请求返回 429 表示触发了限流返回 529 表示服务端过载。一个典型的 529 响应{ error: { message: api error: 529 overloaded. this is a server-side issue, usually temporary, type: server_error } }遇到这类错误时先判断是账号级限流还是网关级过载。缓解手段包括降低并发数。增加重试等待时间。拆批提交任务。错峰提交。重试必须设置最大次数例如 5 次并使用指数退避。否则服务端负载恢复后大量积压请求同时重试会再次造成过载。6.2 连接中断connection lost mid-response连接中断错误多发生在长时间等待的场景api error: connection lost mid-response. the response above may be incomplete看到这个错误不要立刻认为是代码问题。可能原因有服务端任务还在执行但连接被网关或网络中间设备断开。客户端读取超时时间太短。目标模型不支持在原始连接上返回完整结果必须走异步轮询。处理方式先检查是否拿到了任务 ID。如果拿到了用任务查询接口恢复状态。检查客户端超时设置是否在等待期间被强制断开。如果任务是异步模型改成提交后立刻返回再轮询而不是保持长连接等待。这个错误提醒我们长耗时任务不能依赖一次 HTTP 请求完成所有工作。6.3 400 参数错误thinking_budget 与上下文长度400 参数错误通常表示请求体里有模型不接受的字段或者字段值不合法。常见的两个示例api error: 400 the thinking_budget parameter must be a positive integer and ...api error: 400 this models maximum context length is 1048576 tokens. however...第一种大多数情况下是参数被传成了字符串、负数或浮点数改成正整数即可。第二种是输入内容过长需要截断提示词、图片描述或压缩上下文。这里有一个容易踩的坑同一个聚合网关下多个模型的参数要求不同。在模型 A 上有效的参数迁移到模型 B 上可能变成非法参数。切换模型后建议先用最小参数跑一次成功请求再逐步添加扩展参数。6.4 认证失败、模型不存在与计费余额不足认证失败通常返回 401表现为API Key 为空。API Key 前缀错误。Key 已经被删除或禁用。模型不存在或不可用时通常返回 404 或 400错误信息会提示模型名称不被支持。计费余额不足则可能返回 402 或 403。排查顺序建议确认环境变量是否加载成功。确认 Key 是否能在控制台查询到。确认模型 ID 是否完整复制是否包含多余空格。确认模型在当前账号下可用。确认账号余额和计费状态正常。6.5 稳定的排查链路下面这张表汇总了常见问题的排查优先级问题现象常见原因检查方式处理建议401 UnauthorizedKey 无效或未加载打印 Key 前缀和前几位重新创建 Key 并写入环境变量404 Model Not Found模型 ID 不存在在控制台模型列表搜索复制完整模型 ID400 参数错误参数名不合法或类型不对对照文档检查请求体移除非法参数或修正类型429 限流并发过高或触发单 Key 限制查看响应头和用量页面降低并发增加退避529 过载服务端临时负载高查看错误类型等待后重试设置最大次数connection lost长连接断开或任务未完成检查是否有任务 ID转为异步轮询或查询任务结果文件过小下载不完整或返回异常检查文件大小和响应头保存临时文件并校验后改名排查时先看网络层再看请求格式最后看服务端负载和账号状态。不要一开始就去改业务逻辑。7. 从示例脚本到生产代码的关键改造7.1 学习环境、测试环境和生产环境分开配置示例脚本适合本地跑通流程但进入生产环境前需要拆分配置。学习环境.env本地配置方便替换 Key 和模型 ID。测试环境使用独立 Key调用量小重点验证参数和状态流转。生产环境配置由部署平台注入不落盘到代码仓库同时开启监控告警。配置项建议用一个配置类统一管理class Settings: def __init__(self): self.api_key os.getenv(OPENROUTER_API_KEY) self.api_base os.getenv(OPENROUTER_API_BASE, https://openrouter.ai/api/v1) self.timeout (10, int(os.getenv(OPENROUTER_TIMEOUT, 120))) self.max_poll_count int(os.getenv(OPENROUTER_MAX_POLL, 60))这样所有参数都在启动时读取一次不要在每个请求里反复读取环境变量。7.2 重试、幂等与队列生产环境里直接在前台代码里同步等待一个几分钟的视频生成任务是不合适的。推荐结构是收到用户请求后把任务写入队列。后台 Worker 从队列取出任务调用 OpenRouter。拿到任务 ID 后持久化到数据库。Worker 定时轮询完成后通知业务方或直接存储结果。重试必须考虑幂等。如果第一次请求已经提交成功但客户端因为网络超时没有拿到任务 ID直接重试可能会创建第二个视频生成任务。可以引入请求幂等键例如request_id在请求体中传递服务端识别重复提交时返回已存在的任务。7.3 成本、限流和内容合规视频生成的成本通常远高于文本生成生产环境必须设计成本控制策略每次提交前检查账号余额。为单用户设置每日调用次数上限。为失败重试设置次数上限避免死循环扣费。对生成结果进行内容审核后再对外展示。不要在没有任何审核机制的情况下把模型生成结果直接发布到用户可见页面。视频数据比文本更难即时审核更需要在业务流程里加入人工抽检或自动审核步骤。7.4 发布前检查清单上线前可以按这份清单逐项确认[ ] 生产环境使用独立 API Key且权限最小化。[ ] API Key 没有写入代码仓库或镜像。[ ] 所有请求都设置了连接超时和读取超时。[ ] 提交任务后能拿到任务 ID并持久化到数据库。[ ] 轮询逻辑有最大次数和失败状态处理。[ ] 下载结果使用临时文件加文件大小校验。[ ] 重试逻辑带指数退避且设置最大次数。[ ] 账号余额不足时有告警。[ ] 生成内容有审核或风控流程。[ ] 日志记录了任务生命周期可以按任务 ID 回溯。8. 扩展方向与工程建议8.1 从单次生成到视频帧生成视频生成 API 除了直接生成完整视频在一些工作流里还会用到“视频帧生成”能力。帧生成通常是输入起始帧或结束帧让模型补全中间帧变化。这种模式对人物连续性要求高也更考验请求参数的精度。在 API 接入层面帧生成任务通常需要传入参考图路径、关键描述和帧率参数。不同模型的帧率控制方式不同有的通过fps参数有的通过frame_count参数。接入前先看模型文档不要假设所有模型都接受同样的帧率字段。8.2 在 ComfyUI 等工具中保持人物 ID 一致的思路如果后续把视频生成能力集成到 ComfyUI 这类可视化工具中最常遇到的问题是如何保证人物 ID 不变。OpenRouter 这类聚合 API 通常无法直接访问模型内部的多阶段工作流但可以借助以下方式改善一致性在请求中传入角色参考图让模型基于参考图生成。保持提示词中的主体描述稳定不要在同一人物身上混用不同发型、服饰描述。对生成结果做首帧和末帧比较提取特征后决定是否重新生成。如果模型支持种子参数固定种子可以增加结果的可复现性。工具链越复杂越建议把 API 请求封装成独立模块让 ComfyUI 节点只负责组合参数不直接处理鉴权和错误重试。8.3 给新手的下一步建议如果你刚接触 OpenRouter 视频生成 API建议按下面顺序练习用 curl 跑通一次最小请求确认模型 ID 和 Key 可用。用 Python 脚本提交任务打印出原始响应 JSON。实现一个轮询函数观察状态从 queued 到 completed 的变化。写一个下载函数校验文件大小和扩展名。把日志和任务 ID 记录下来模拟一次断网恢复。最后再考虑封装成生产可用的队列和重试机制。这组练习做完你对视频生成 API 的理解就不是停留在“能用”层面而是知道一个完整任务从提交到落盘要经历哪些环节以及各个环节失败后如何恢复。实际项目里真正拉开稳定性和成本差距的正是这些看起来琐碎的任务状态处理和异常恢复逻辑。