阿里万相3.0上线 OpenRouter意味着什么简单说你不需要再关心本地显卡够不够、显存占用多少、驱动版本对不对直接在 OpenRouter 上申请一个 API Key就能用 HTTP 请求调用万相 3.0 的多模态生成能力。这个模式对于那些想快速验证效果、做内容生产工具或者只是想把生成能力接进现有系统的团队来说性价比非常直接。这次我们要做的事也很明确注册 OpenRouter、找到阿里万相 3.0 的模型入口、把 API Key 配好然后用 curl、Python requests 和 OpenAI SDK 三种方式把接口调通最后再补一套批量任务脚本设计顺带解决“模型列表里找不到模型”“API 调用 404”“余额不足”这类高频问题。从搜索热度看大家关心的点集中在 OpenRouter 注册、充值、API Key 使用还有“配置后找不到某个模型”这类细节上。这篇文章会尽量把这些问题都覆盖到。适配哪些读者第一类是本地显卡不够但想用万相能力的人第二类是想把万相 3.0 接进自动化流程、做批量生成的开发者第三类是刚接触 OpenRouter想知道这套 API 聚合平台怎么玩的人。看完这篇文章你应该能独立完成从账号到批量任务的全链路打通。1. 核心能力速览能力项说明服务类型多模态生成模型 API 接入通过 OpenRouter 平台调用阿里万相 3.0计费方式按量计费具体单价以 OpenRouter 模型页面为准硬件门槛本地无需 GPU 推理只需能发起 HTTP 请求调用方式HTTP API兼容 OpenAI SDK 风格批量任务可自行封装脚本实现批量调用是否需要本地模型文件不需要适用客户端Windows / Linux / macOS 均可典型应用场景文生图、图生视频、内容生产、自动化测试、工具集成核心优势有三点。第一零部署成本没有环境依赖第二接口标准OpenRouter 提供统一的 API 格式换模型不需要改太多代码第三接入链路短拿到 Key 就能跑通。需要提醒的是万相 3.0 在 OpenRouter 上具体开放哪些生成能力、支持哪些参数要以模型页面的实际说明为准。OpenRouter 模型列表更新很快有些能力可能在不同时间有调整所以下文涉及模型 ID 和参数的地方都以你从模型页复制到的内容为准。2. 适用场景与使用边界2.1 适合什么场景第一类快速效果验证。想看看万相 3.0 生成图或视频的效果又不想先折腾部署用 OpenRouter 是最省时间的路径。申请 Key、复制模型 ID、发一次请求结果直接回来。第二类业务系统集成。比如你正在做一款内容创作工具需要给用户提供“文生图”“图生视频”的能力直接通过 API 接入比自己在服务器上维护推理服务省心很多。OpenRouter 还支持 OpenAI SDK 兼容格式意味着很多现有的生成代码可以复用。第三类批量生成测试。如果你有一批 Prompt 需要逐个测试效果通过脚本循环调用 API比在 WebUI 里一张张生成要高效得多。后面第 7 节会给出一套批量脚本示例。2.2 不适合什么场景数据隐私要求极高的场景不建议走这种公开 API。你的输入内容会发送到第三方平台涉密数据、未公开的商业素材、他人隐私信息都不应该直接送进去。超大批量且成本敏感的场景也需要先算账。API 按量计费当调用量特别大时单次费用累计起来会超过本地部署的硬件成本。这种情况更适合本地部署推理服务。完全离线环境就不用考虑了。OpenRouter 提供的是在线 API没有网络就无法调用。2.3 安全与合规边界使用任何生成模型都要注意几个基本底线不要用生成能力制造虚假信息、伪造证据、冒充他人。涉及人脸生成、声音克隆、版权素材、品牌元素时必须确认拥有合法授权。输出内容如果用于商用要提前确认模型服务条款和生成内容的使用限制。API Key 要妥善保管不要提交到公开代码仓库避免被他人盗用造成费用损失。3. 环境准备与前置条件在正式调用之前先把环境准备清单过一遍。OpenRouter 本身是云端 API所以本地环境要求很低。操作系统Windows 10/11、macOS、主流 Linux 发行版均可 网络要求能正常访问 OpenRouter 官网和 API 服务 Python可选3.8 及以上用于 requests 和 openai SDK 调用 工具curl、Postman/Apifox 任选3.1 需要准备的信息OpenRouter 账号登录凭证OpenRouter API Key账户余额用于按量扣费万相 3.0 的模型 ID以 OpenRouter 模型页展示为准3.2 国内网络下的可达性检查很多用户问“OpenRouter 国内能用吗”这个问题没有一个全国统一的答案取决于你的网络环境和 OpenRouter 服务的实时可达性。更稳妥的判断是OpenRouter 是海外服务因此在国内网络环境直连时可能出现延迟高、请求超时或部分页面无法加载的情况。这里只建议做一件事先测试再使用。可以通过一条命令检查 API 基础连通性curl -I --max-time 10 https://openrouter.ai/api/v1如果这个请求能正常返回 HTTP 响应头说明基础连通性没问题。如果长时间超时说明当前网络到 OpenRouter 的链路不稳定这时候就不要继续配置了先解决网络可达性问题再使用。接口调用同理建议在服务端或能稳定访问海外 API 的网络环境中运行。3.3 Python 依赖安装如果要用 Python 调用建议先装好 requests 和 openai 两个库。pip install requests openaiopenai 库并不是只能调用 OpenAI 的服务因为 OpenRouter 的 API 端点和响应格式与 OpenAI 兼容所以可以直接用这个 SDK 指定 base_url 来访问 OpenRouter。这个特性在后文会详细演示。4. 注册、充值、查找万相 3.04.1 注册与登录访问 OpenRouter 官网进入登录页面通常支持邮箱注册和 Google/GitHub 等第三方账号登录。注册完成后进入控制台这里能看到 API Key、余额和调用记录。如果是第一次使用 OpenRouter建议按下面顺序操作登录 OpenRouter 控制台。检查账户余额新账户如果有赠送额度可以先用于小规模测试没有额度则先充值。进入 API Keys 页面创建一个新的 Key命名最好能区分用途例如wanxiang-test。把 Key 复制保存到本地安全位置关闭页面后可能无法再次查看完整 Key。关于充值OpenRouter 支持的支付方式以平台页面实际展示为准一般支持国际信用卡或平台内余额充值。充值金额建议从小到大先充一小笔跑通流程后再根据用量追加。支付过程中注意核对金额、币种和手续费避免多付不必要的成本。4.2 找到万相 3.0 模型登录后在 OpenRouter 的模型列表页搜索“万相”或“Wan”相关关键词就可以看到对应的模型入口。点进模型页后关注三个信息模型 ID即 API 请求时填写的 model 字段内容支持的生成能力列表例如文生图、图生视频、视频生成等计费方式按张数/按 Token 还是按秒计费。这里有个高频问题“为什么我在 OpenRouter 配置后找不到想要的模型”原因通常是下面几种关键词拼写不对。不同模型在 OpenRouter 上的命名可能和中文习惯不一致优先搜索英文名或模型官方名称。模型尚未在该区域/该平台版本上架。OpenRouter 模型的可见性可能受平台策略影响。页面缓存或地区原因导致模型列表加载不完整刷新页面或换个网络环境再看。有些用户把“API 调用中的模型 ID”和“网页显示的模型名称”搞混了。API 调用必须用模型页上的完整 ID而不是显示名称。如果确实在模型列表里找不到万相 3.0保守的做法是返回模型页刷新或者用另一个网络环境重新访问。如果始终找不到就说明当前没有可用的入口不要硬凑一个不存在的模型 ID 去调用。4.3 API Key 的保存与使用创建好 Key 后在代码里不要直接写死推荐用环境变量保存。下面是 Windows 和类 Unix 系统的设置方式。# Linux / macOS 临时设置 export OPENROUTER_API_KEYsk-or-你的key:: Windows 命令行临时设置 set OPENROUTER_API_KEYsk-or-你的key更推荐把 Key 放在项目根目录的.env文件中并用.gitignore排除提交。如果你用的是 Python可以借助 python-dotenv 加载pip install python-dotenvimport os from dotenv import load_dotenv load_dotenv() API_KEY os.getenv(OPENROUTER_API_KEY) print(Key 已加载 (是 if API_KEY else 否))这样做的好处是代码本身不包含敏感信息即使仓库被分享出去也不会直接泄露 Key。5. 接口 API 调用示例OpenRouter 的 API 基础地址是https://openrouter.ai/api/v1鉴权方式是在请求头中携带Authorization: Bearer API_KEY。模型 ID 从模型页复制。下面的示例假设你已经拿到了有效的 Key 和模型 ID。5.1 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: 你的万相模型ID, messages: [ { role: user, content: 生成一张赛博朋克风格的城市夜景图 } ] }注意这里用的是 chat/completions 接口因为 OpenRouter 对大部分模型统一走这个协议。如果万相 3.0 在 OpenRouter 上有独立的生成接口例如专门的多模态生成端点要以模型页的调用说明为准。curl 请求返回 200 并带响应体说明链路已通。5.2 Python requests 调用如果你要在脚本里用requests 是最直观的方式。import os import requests API_KEY os.getenv(OPENROUTER_API_KEY) MODEL_ID 你的万相模型ID url https://openrouter.ai/api/v1/chat/completions headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } payload { model: MODEL_ID, messages: [ { role: user, content: 生成一张赛博朋克风格的城市夜景图, } ], # 如果模型支持更多参数按模型页说明追加例如 # num_images: 1, } response requests.post(url, headersheaders, jsonpayload, timeout120) print(HTTP 状态码:, response.status_code) if response.status_code 200: data response.json() print(生成结果:, data) else: print(错误信息:, response.text)这段代码的关键点是超时时间设得比较长因为生成类模型响应时间普遍比普通文本接口慢默认 30 秒可能不够。如果返回 401 或 403检查 API Key 是否有效如果是 404检查模型 ID 是否完整。5.3 OpenAI SDK 兼容调用OpenRouter 支持把 base_url 改为自己的地址这样就能复用 OpenAI SDK 的调用习惯。from openai import OpenAI client OpenAI( base_urlhttps://openrouter.ai/api/v1, api_keyos.getenv(OPENROUTER_API_KEY), ) response client.chat.completions.create( model你的万相模型ID, messages[ { role: user, content: 生成一张赛博朋克风格的城市夜景图, } ], ) print(response.choices[0].message.content)这个方式的优势是如果你的项目之前已经用 OpenAI SDK现在切换到万相 3.0只需要改 model 字段和 base_url代码结构基本不用动。5.4 关于“Claude Code 如何接入 OpenRouter”热搜里有一个非常具体的问题Claude Code 如何接入 OpenRouter 的大模型 API Key。这里可以给一个通用思路Claude Code 这类代码工具通常支持通过环境变量或配置文件指定第三方模型网关。如果它兼容 OpenAI 风格 API可以尝试把它的 base_url 指向 OpenRouter并在配置中填上对应的模型 ID。具体字段名因工具版本而异所以先查工具本身的接入文档再对照 OpenRouter 的模型 ID 进行配置。注意不是所有工具都开放了自定义 base_url如果工具没有这个入口就不能简单替换。6. 功能测试与效果验证接口调通之后不要急着上生产先用一组测试用例把功能边界摸清楚。下面是一个适合大多数多模态生成场景的测试清单。测试维度输入示例预期结果失败时的常见原因基础连通性最小生成请求HTTP 200返回结果Key 失效、网络不通、模型 ID 错误参数扩展增加分辨率/数量等参数按参数返回对应的生成结果参数名不被模型支持长文本提示词多段提示词拼接生成结果不报错输入长度超限批量调用脚本循环 5 次请求全部成功或可重试成功限流 429、单次请求超时内容合规正常内容生成正常返回触发内容安全策略6.1 文生图测试如果你确认万相 3.0 支持文生图先跑单张再跑多张。测试目的验证图生成是否正常检查分辨率、风格还原度。输入示例一张江南水乡的水彩画雨后清晨青石板路。操作步骤用 Python requests 脚本发送请求保存返回结果到本地。判断标准返回图片地址或 base64 内容且无 HTTP 错误。失败排查404 通常是模型 ID 不对400 大概率是参数格式有问题403 是鉴权失败。6.2 图生视频或文生视频测试如果模型支持视频生成建议先验证最短时长/最简单提示词因为视频类请求耗时更长响应体也可能更大。输入示例城市繁忙的十字路口延时摄影效果4秒。预期结果返回视频文件地址或可下载的临时链接。判断标准链接能正常下载且内容不是错误页。失败排查视频生成超时是常见现象适当加大 timeout如果是返回 URL 但无法下载检查网络可达性。6.3 自定义参数测试不同的模型支持不同参数比如宽高比、生成数量、视频时长、运动幅度等。建议先读取模型页的说明再用小批量参数逐一测试。每次只改一个参数不要同时改多个这样出了问题更容易定位。6.4 失败后的重试策略在线 API 天然存在偶发超时和限流所以测试阶段就要考虑重试。基本原则是收到网络错误、5xx、429 时可以做有限次重试收到 4xx 时不要盲目重试先检查请求格式和 Key 状态。重试之间加入退避等待避免在限流状态下继续大量请求。7. 批量任务与工程化如果只是调用一两次脚本随便写。但如果要做批量生成必须考虑队列、重试、日志和结果管理。下面给出一套最小可用的批量脚本设计。7.1 批量任务设计思路输入管理把需要生成的 Prompt 放在一个文本文件或 JSON 文件里每行一条或每条一个对象。任务循环按顺序读取每一条 Prompt调用 API。结果保存每次成功调用后把结果写入独立文件防止后面中断导致结果丢失。日志记录记录每个任务的开始时间、结束时间、HTTP 状态码、耗时时长。失败重试对可重试错误做指数退避重试重试次数建议不超过 3 次。并发控制初期先单线程跑确认稳定后再考虑并发并发过大会触发限流。7.2 批量脚本示例import os import time import json import requests from datetime import datetime API_KEY os.getenv(OPENROUTER_API_KEY) MODEL_ID 你的万相模型ID URL https://openrouter.ai/api/v1/chat/completions def generate_one(prompt, retry_times3): headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } payload { model: MODEL_ID, messages: [{role: user, content: prompt}], } for attempt in range(retry_times): try: resp requests.post(URL, headersheaders, jsonpayload, timeout180) if resp.status_code 200: return resp.json() if resp.status_code in (400, 401, 403, 404): # 请求格式或鉴权问题重试无意义 print(f不可重试错误: {resp.status_code} {resp.text[:200]}) return None # 429、5xx 等可重试错误 wait 2 ** attempt print(f重试 {attempt 1}/{retry_times}等待 {wait}s) time.sleep(wait) except requests.exceptions.Timeout: print(f请求超时进行第 {attempt 1} 次重试) time.sleep(2 ** attempt) except Exception as e: print(f未知异常: {e}) time.sleep(2 ** attempt) return None def batch_generate(input_file, output_dir): with open(input_file, r, encodingutf-8) as f: prompts [line.strip() for line in f if line.strip()] os.makedirs(output_dir, exist_okTrue) results [] for idx, prompt in enumerate(prompts): start time.time() print(f[{datetime.now().isoformat()}] 开始任务 {idx 1}/{len(prompts)}) result generate_one(prompt) elapsed time.time() - start item { index: idx 1, prompt: prompt, success: result is not None, elapsed: round(elapsed, 2), result: result, } results.append(item) # 每个任务单独保存一份结果 with open(os.path.join(output_dir, ftask_{idx 1:04d}.json), w, encodingutf-8) as f: json.dump(item, f, ensure_asciiFalse, indent2) print(f[{datetime.now().isoformat()}] 任务 {idx 1} 完成耗时 {elapsed:.2f}s) with open(os.path.join(output_dir, all_results.json), w, encodingutf-8) as f: json.dump(results, f, ensure_asciiFalse, indent2) print(批量任务全部结束) if __name__ __main__: batch_generate(prompts.txt, ./output)prompts.txt 的格式为每行一条提示词一张赛博朋克风格的城市夜景图 一张江南水乡的水彩画 一个未来主义风格的室内空间设计图这套脚本虽然简单但已经把输入管理、结果持久化、日志记录、失败重试四个关键点都覆盖了。如果需要更高并发可以在此基础上引入线程池但要注意限流不要一上来就开几十个并发。7.3 JSON 格式批量输入如果你的 Prompt 还带额外参数可以用 JSON 文件管理输入。[ { prompt: 赛博朋克城市夜景, width: 1024, height: 1024 }, { prompt: 江南水乡水彩画, width: 768, height: 512 } ]然后在脚本中循环读取字典把 width、height 拼进请求参数。这样批量任务的灵活度更高。8. 成本控制与性能观察使用 OpenRouter 这种在线 API不需要关心本地显存占用但需要关心另外三个维度请求耗时、并发上限、费用。8.1 请求耗时观察生成类模型的响应时间通常比文本模型长可能是几十秒到上百秒不等。建议在代码里记录每次请求的耗时设置一个合理的超时阈值。如果大量请求耗时接近超时上限就需要检查是不是输入太长、参数太大或者当前 API 服务负载较高。8.2 并发与限流OpenRouter 按计划对 API 请求有速率限制。常见限流表现是返回 429 Too Many Requests。遇到 429 不能继续硬怼正确做法是指数退避重试或者在两次请求之间加固定间隔比如 0.5 到 1 秒。如果你的批量任务规模很大建议先小批量测试观察限流阈值后再逐步调高并发。8.3 费用估算思路成本估算可以从两个方向入手。一是从模型页拿到单价乘以计划调用次数二是先跑一批小规模测试统计单次调用实际消耗再按比例换算到大任务量。线上环境建议设定每日预算或请求上限防止脚本异常导致费用飙升。# 简单费用估算 unit_price 0.01 # 替换为模型页实际价格 total_requests 100 estimated_cost unit_price * total_requests print(f预估费用: {estimated_cost})8.4 降低成本的策略测试阶段用小参数比如低分辨率、短时长。大批量任务前先用 5 条数据验证效果。相同 Prompt 不要重复调用结果做本地缓存。失败任务不要无限重试设好最大重试次数。9. 常见问题与排查方法下面整理一套常见问题表基本覆盖了 OpenRouter 阿里万相 3.0 使用过程中会碰到的高频故障。问题现象可能原因排查方式解决方案打开 OpenRouter 官网超时网络链路不稳定用 curl 测试基础连通性确认网络可达后再使用注册/登录收不到验证邮件邮箱限制或网络延迟查看垃圾箱换网络重试更换邮箱或等待一段时间重试页面显示余额不足账户未充值或赠额已用完查看余额明细和账单完成充值后再调用创建 Key 后马上 401Key 复制不完整或权限不足重新创建 Key检查复制内容替换为新的有效 KeyAPI 返回 404模型 ID 不存在或未上架在模型页核对 ID使用模型页展示的完整 IDAPI 返回 400参数格式错误或参数不支持检查请求体和模型页参数说明按文档修正参数API 返回 429请求频率超限检查限流状态退避重试或降低并发生成结果为空模型能力限制或内容安全策略查看返回的 error 字段调整输入内容或参数找不到想要的模型模型未上架/名称拼写错误/页面缓存换关键词搜索刷新页面参考第 4.2 节排查批量任务中途卡住单次请求超时或进程被中断查看任务日志和输出目录脚本增加超时和断点续跑机制这里重点说两个容易被忽视的问题。第一API Key 的有效性。有些用户注册后遇到 free API Key但没注意这个 Key 是否有调用权限或余额绑定。建议在正式集成前先用 curl 发起一次最小请求确认 200 之后再写业务代码。第二模型 ID 不要自己猜。搜索热词里“为什么配置后找不到 stealth/ox-alpha 这个模型”类似问题在万相 3.0 上也可能出现。OpenRouter 的模型 ID 是平台维护的可能和你以为的名称不一致。唯一正确的获取方式是从模型页复制不要靠记忆输入。10. 最佳实践与使用建议10.1 先小后大分步上线无论你是做测试还是做生产集成都不要第一次就批量生成几十张图或几十个视频。正确顺序是最小请求 → 参数扩展 → 小规模批量 → 全量任务。每一步都要检查结果文件确认无误再进行下一步。10.2 Key 管理与安全把 Key 放进环境变量或 .env 文件不要硬编码在脚本里。Git 提交前检查代码仓库确保没有把 Key 提交上去。如果 Key 泄露第一时间在 OpenRouter 控制台吊销并重新创建。10.3 结果目录规范建议按日期和任务名组织输出目录output/ ├── 20250401/ │ ├── task_0001.json │ ├── task_0002.json │ └── all_results.json这样后续复盘时能够清晰知道哪些内容是哪个批次生成的、用了什么 Prompt、什么参数。10.4 日志与可观测性批量任务必须记录日志。至少包含每条任务的 Prompt发起时间、结束时间、耗时HTTP 状态码或异常信息结果文件路径尽量不要用 print 代替日志。如果任务量大建议使用 Python logging 模块把日志同时输出到控制台和文件。10.5 合法合规使用生成内容使用阿里万相 3.0 生成图片、视频相关内容时要注意不生成虚假信息、仿冒他人身份的内容。不生成侵权、违法、危害公共安全的内容。涉及真实人物肖像、品牌标识、受版权保护的素材时必须获得授权。商用前确认模型服务方的内容使用条款和 OpenRouter 的适用政策。11. 总结与下一步阿里万相 3.0 上线 OpenRouter给开发者的核心价值就是“少部署、快接入”。没有本地显卡压力也没有复杂的环境配置注册 OpenRouter、创建 API Key、复制模型 ID三步就能跑通请求。更重要的是OpenRouter 兼容 OpenAI SDK 风格的调用方式这意味着很多现有的生成代码改动成本很低。建议你拿到 Key 后第一件事不是跑复杂功能而是先用 curl 发一个最小请求确认网络、Key、模型 ID 三个基础条件都成立。然后再用 Python 脚本跑通一个简单生成任务最后再考虑并发和批量。最容易踩的坑有三个模型 ID 从模型页复制而不是自己猜API Key 不要硬编码在代码里批量任务必须先做小规模测试再放大。把这三点处理好后面基本不会遇到大问题。后续如果你想更深入可以从这几个方向继续扩展把批量脚本封装成定时任务增加数据库记录生成记录把接口接到聊天机器人或内容管理系统中或者对比 OpenRouter 上其他多模态模型的效果和成本选出最适合自己业务的那一个。建议把这篇收藏备用需要接入的时候照着操作一遍会省很多查资料的功夫。