OpenRouter 推出统一多模态 API，一个 base URL 调用图像、视频、音频与嵌入

你正在构建一个应用，需要能在聊天中回答问题、生成产品图片、搜索知识库，并把语音备忘录转成文本。默认路径是 4 个提供商 SDK、4 套计费关系、4 种认证方案，这些都得在写第一行功能代码之前接好。r/Bard 上的一位开发者正在寻找 一个统一用于 LLM、图像和视频生成模型的 API。r/ShowYourApp 上的另一位开发者自己动手做了这件事，并反馈说，一旦文本、图像、视频、TTS、STT 和嵌入都必须共存，一个全能型 AI API 远比预期难做。

在 OpenRouter 上，所有这些模态都通过一个兼容 OpenAI 的单一基础 URL 运行：https://openrouter.ai/api/v1。你只需设置一次。之后，你只需更改模型字符串和内容类型。目录涵盖 70+ 个提供商的 400+ 个模型，而保护聊天调用的同一套路由控制也保护嵌入调用。

简而言之

• 设置一个基础 URL（https://openrouter.ai/api/v1），并通过它调用图像、视频、音频、嵌入和转录。通过更改模型字符串和内容类型来切换模态。
• 大多数输入模态都走 /chat/completions 端点。有五个拥有专用端点：/images、/videos、/audio/speech、/audio/transcriptions 和 /embeddings。
• 同一个提供商路由对象（故障转移、data_collection: "deny"、成本/延迟排序）在嵌入调用上的工作方式与在聊天调用上完全相同。
• 一个 API 密钥、一份账单、一种 OpenAI 形式的请求格式，覆盖全部 5 种模态。我们不对提供商定价加价，失败的请求不计费。
• 需要提前规划的真实限制：嵌入不支持流式传输，音频输入仅支持 base64，视频 URL 支持因提供商而异。

一个 API 能处理图像、视频、音频、嵌入和转录吗？

可以。一个基础 URL 服务所有模态，你通过更改模型字符串和请求内容类型在它们之间切换。将 https://openrouter.ai/api/v1 设置为你的基础 URL，把你的 API 密钥作为 Bearer token 传入，你就能通过一个兼容 OpenAI 的接口访问完整目录。

接入 4 个提供商 SDK 意味着每个提供商都带来自己的认证刷新、重试与退避语义、速率限制标头、流式格式和错误模式。你要把这套胶水代码写 4 遍、维护 4 遍，而来自某个提供商的变更永远只能修复它自己那一块。

我们是 OpenAI Chat API 的即插即用替代品，因此同一种请求格式可贯穿所有走 /chat/completions 的模态，而 TTS 端点遵循 OpenAI Audio API。专用端点（图像生成、视频生成、转录和嵌入）各自有自己的请求结构，但我们的 官方 SDK（TypeScript 用 @openrouter/sdk，Python 用 openrouter）把这一切都封装在一个接口之后。

每种模态使用哪个端点？

大多数输入模态都走 /chat/completions，仅内容类型不同。有五种模态拥有专用端点。以下是完整对照表，依据我们的 多模态概览和 嵌入参考。

其中五种模态运行在 /chat/completions 上，只需更改消息数组中的内容类型。另外五种拥有自己的端点，因为它们的调用形式不同：图像生成接收提示词以及图像专属参数（分辨率、宽高比、输出格式），并返回 base64 图像；视频生成是异步的（你需要轮询任务）；语音和转录传输原始音频字节；嵌入返回的是向量而非补全结果。单一提供商的文档很少将这些并排列出，因为没有哪家提供商能同时提供所有这些功能。

你可以免费测试多模态输入。免费套餐无需信用卡，免费模型在较低的每日速率限制下运行，一旦你添加了额度，限制就会提高。这足以让你在正式投入之前，向视觉模型发送一张图片或生成一批嵌入。

何时应该使用每种模态？

即使在同一媒体类型内，生成和理解也是不同的任务，你选择哪个端点取决于你正在做哪一种。

图像：生成 vs. 理解。当你需要一张新图像时使用图像生成，当你有一张图像需要分析时使用图像输入。生成通过 POST 到专用的 /api/v1/images 端点，从文本提示词生成素材、模型图和插图，并可选地使用参考图像进行图生图。视觉输入则相反：你在 /chat/completions 上发送一个 image_url，模型执行 OCR、描述或检测。完整操作指南请参阅图像生成文档。

视频：输入 vs. 生成。使用异步的 /videos 端点生成视频片段，在聊天中使用 video_url 来理解它们。视频生成提交提示词并返回一个任务 ID，你轮询该 ID 直到片段就绪，可配置分辨率、宽高比和时长。视频理解将 video_url 发送给支持视频的模型，用于分析、动作识别或目标检测。更多内容见视频生成公告。

音频和语音：输出 vs. 分析。使用 /audio/speech 进行语音输出，在聊天中使用音频输入进行分析。文本转语音将文本发送到 /api/v1/audio/speech，并通过兼容 OpenAI Audio 的端点返回 MP3 或 PCM 字节，因此 OpenAI 客户端库可以直接使用。音频输入搭载在 /chat/completions 上，使用 input_audio 内容类型，用于情感或内容分析等任务。详情见音频 API 公告。

嵌入：检索和相似度。当你需要检索或相似度而非生成时，使用嵌入。嵌入文档列出了 6 项任务：RAG、语义搜索、推荐、聚类、重复检测和异常检测。你可以在一个请求中批量处理多个输入，某些模型接受文本和图像一起生成单个联合向量（nvidia/llama-nemotron-embed-vl-1b-v2 就是其中之一）。

转录：语音转文本。使用 /audio/transcriptions 进行语音转文本。你发送 base64 编码的音频，返回包含转录文本及使用统计的 JSON。它适用于会议记录、语音命令和字幕生成。

路由和故障转移对嵌入和图像调用也有效吗？

是的。你在聊天调用中使用的同一个 provider 对象在嵌入调用中作用完全相同：提供商顺序、自动故障转移、数据收集策略以及成本或延迟排序。以下是来自嵌入文档的确切形式：

{
  "model": "openai/text-embedding-3-small",
  "input": "Your text here",
  "provider": {
    "order": ["openai", "azure"],
    "allow_fallbacks": true,
    "data_collection": "deny"
  }
}

路由控制同样适用于专用图像端点：/api/v1/images 接受 provider.order、provider.allow_fallbacks、provider.only、provider.ignore 和 provider.sort，因此故障转移、排序以及成本/延迟排序在图像生成调用上与在聊天调用上工作方式相同。

由多个提供商提供的嵌入模型可以在第一个返回错误时回退到另一个。通过提供商对象，同样的跨提供商故障转移适用于嵌入、图像、音频和聊天。

我们不对提供商定价加价：模型目录中的费率就是您支付的价格。零完成保险意味着失败的运行不计费，因此一个故障转移后从未完成的请求不产生任何费用。这适用于所有模态。

整合究竟能为您节省什么？

一个 API 密钥、一份账单、一种请求格式，适用于所有模态。

同一个 Bearer token 可授权视觉调用、TTS 调用和嵌入调用。无需为每个提供商单独设置密钥库，也无需按模态分别接入。当您添加新能力时，比如开始做 RAG，您用已有的密钥调用 /embeddings 即可。

整合计费意味着跨模态的使用量以目录费率汇总到一份 OpenRouter 账单上。您可以在一个地方比较图像生成与嵌入的成本，而不必从 4 个仪表盘导出 CSV。这种对账摩擦正是 r/ShowYourApp 的构建者在一体化技术栈变得比预期更难时遇到的。

有哪些需要提前规划的局限？

每种模态都有在构建前值得了解的约束。以下是我们当前的局限，如实说明，以便您据此设计，而不是在生产环境中才发现它们。

当您需要不止一种媒体类型、当更换模型只需改一个字符串、或当提供商故障不应导致您的功能下线时，统一 API 才物有所值。如果您的整个应用只是针对单一提供商的一个通用模型的一个聊天功能，那么直接集成更简单，整合带来的好处也更有限。

从一次调用开始

针对基础 URL 发送单个嵌入请求。

import requests

response = requests.post(
    "https://openrouter.ai/api/v1/embeddings",
    headers={
        "Authorization": "Bearer <OPENROUTER_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "model": "openai/text-embedding-3-small",
        "input": "The quick brown fox jumps over the lazy dog",
    },
)

print(response.json()["data"][0]["embedding"][:5])

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });

const response = await openRouter.embeddings.generate({
  model: 'openai/text-embedding-3-small',
  input: 'The quick brown fox jumps over the lazy dog',
});

console.log(response.data[0].embedding);

curl https://openrouter.ai/api/v1/embeddings \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/text-embedding-3-small", "input": "The quick brown fox jumps over the lazy dog"}'

从这里开始，您可以按模态深入了解多模态概览，或浏览按输出模态分类的模型，找到适合每次调用的模型。

常见问题

我可以用一个 API 进行图像生成、嵌入和转录吗？

可以。这三者都通过我们的基础 URL https://openrouter.ai/api/v1 运行，使用一个 API 密钥。图像生成使用专用 /images 端点，嵌入使用 /embeddings，转录使用 /audio/transcriptions。您更改的是端点和内容类型，而不是集成、认证或 API 密钥。

OpenRouter 支持嵌入吗？

支持。嵌入通过 POST /api/v1/embeddings 运行，返回用于 RAG、语义搜索、推荐、聚类、重复检测和异常检测的向量。您可以在一个请求中批量处理多个输入，某些模型还接受文本和图像一起生成联合向量。

哪些模态使用聊天端点，哪些使用专用端点？

文本、图像输入、PDF、音频输入和视频输入都使用 /chat/completions，只是内容类型不同。图像生成（/images）、视频生成（/videos）、文本转语音（/audio/speech）、转录（/audio/transcriptions）和嵌入（/embeddings）使用专用端点，因为它们的调用形式不同：提示词到图像的请求、异步任务、原始音频字节，或返回向量而非补全结果。

有没有支持多模态输入的免费 AI API？

有。我们在 OpenRouter 提供免费套餐，无需信用卡。免费模型在较低的每日速率限制下运行，添加额度后限制会提高，这足以让你发送图像、生成嵌入，或在正式投入前测试其他模态。

我可以在一个嵌入请求中同时发送文本和图像吗？

可以，使用多模态嵌入模型即可。你把输入包装进一个包含 text 和 image_url 对象的内容数组中，模型会返回一个同时捕捉两者的联合向量。nvidia/llama-nemotron-embed-vl-1b-v2 就是一个这样的模型，当你希望文本和图像共享同一个检索空间时很有用。

提供商路由和故障转移也适用于嵌入和图像调用吗？

是的。相同的提供商路由控制（order、allow_fallbacks、成本/延迟 sort）适用于嵌入、图像、音频和聊天调用。如果某个提供商出错，调用会转移到下一个为该模型提供服务的提供商，失败的运行绝不会计费。