OpenRouter 模型能力声明 & 下游项目多模态识别分析

生成时间: 2026-06-02 · 分析范围: OpenRouter /v1/models 接口、oh-my-pi (packages/ai)、pi-mono (packages/ai)

1. OpenRouter 如何声明模型能力

1.1 核心结构：architecture 字段

OpenRouter 的 GET /v1/models 在每个模型条目中返回一个 architecture 对象，这是模型能力的主要声明方式：

{
  "architecture": {
    "modality":          "text+image+video->text",
    "input_modalities":  ["text", "image", "video"],
    "output_modalities": ["text"],
    "tokenizer":         "Qwen3",
    "instruct_type":     null
  }
}

当前 OpenRouter 目录（342 个模型）中存在 15 种独特的 architecture 组合：

1.2 辅助能力信号

除了 architecture，还有其他字段携带能力信息：

1.3 关键发现：ASR 模型在独立类别中，不在 /v1/models Chat 列表

但它不在 /v1/models 的 Chat 模型列表中出现——因为它属于 Transcription（语音转录）类别，与 Chat/Text 模型是不同的业务范畴。

OpenRouter 的模型分类体系实际上有多个输出类别：Text、Image、Embeddings、Audio、Video、Rerank、Speech、Transcription。当前 /v1/models 接口主要返回 Chat/Text 类模型，ASR 类的 Transcription 模型可能在其他端点或需要显式查询。

OpenRouter 网站搜索 "qwen3-asr" 能看到这个模型被归类在 "Transcription" 过滤器下（另外 341 个模型属于 Text 类别）。这说明 OpenRouter 有能力在多个 API 端点下承载不同类型的模型。

2. 当前项目 (oh-my-pi) 如何识别多模态

2.1 Model 类型定义

文件: packages/ai/src/types.ts L881-944

export interface Model<TApi extends Api = any> {
  id: string;
  name: string;
  api: TApi;
  provider: Provider;
  baseUrl: string;
  reasoning: boolean;
  input: ("text" | "image")[];  // ← 只支持 text 和 image!
  cost: { ... };
  contextWindow: number;
  maxTokens: number;
  thinking?: ThinkingConfig;   // 思考能力元数据
  compat?: OpenAICompat | AnthropicCompat;
}

2.2 OpenRouter 模型发现流程

文件: packages/ai/src/provider-models/openai-compat.ts L1349-1401

运行时调用 openrouterModelManagerOptions() → fetchOpenAICompatibleModels()，逐模型映射：

// L1371-1381: 图像支持的判定
const modality = String(entry.architecture?.modality ?? "");
return {
  ...defaults,
  reasoning: params.includes("reasoning"),
  input: modality.includes("image") ? ["text", "image"] : ["text"],
  // ↑ 仅检查 modality 字符串是否包含 "image"
  // 完全不检查 audio / video / file
};

判定规则:

• ✅ 视觉 (image): 检查 architecture.modality 是否包含 "image"
• ✅ 推理 (reasoning): 检查 supported_parameters 是否包含 "reasoning"
• ❌ 音频 (audio): 不检查
• ❌ 视频 (video): 不检查
• ❌ 文件 (file): 不检查

2.3 其他 provider 的通用识别方式

通过 toInputCapabilities() (L50-56) 处理的 providers（models.dev 数据源、ZenMux 等）：

function toInputCapabilities(value: unknown): ("text" | "image")[] {
  if (!Array.isArray(value)) return ["text"];
  const supportsImage = value.some(item => item === "image");
  return supportsImage ? ["text", "image"] : ["text"];
}

Ollama: 检查 capabilities.includes("vision") (L324-325)。

2.4 模型目录生成

文件: packages/ai/src/models.ts — 从 models.json 加载静态预生成目录，不做运行时动态发现。

OpenRouter 被配置为 allowUnauthenticated: true 的 catalog provider（见 descriptors.ts L217-221），可以在构建期拉取模型列表。

3. pi-mono 如何识别多模态

3.1 与 oh-my-pi 相同的模型类型

文件: packages/ai/src/types.ts L546-576

export interface Model<TApi extends Api> {
  id: string;
  name: string;
  api: TApi;
  provider: Provider;
  reasoning: boolean;
  input: ("text" | "image")[];  // ← 相同的两值联合类型
  // ...
}

3.2 静态模型目录生成

文件: packages/ai/scripts/generate-models.ts L281-337

pi-mono 在构建时调用 fetchOpenRouterModels() 拉取 OpenRouter 的 /v1/models，然后写入 models.generated.ts：

async function fetchOpenRouterModels(): Promise<Model<any>[]> {
  const response = await fetch("https://openrouter.ai/api/v1/models");
  const data = await response.json();
  
  for (const model of data.data) {
    // 仅包含支持 tools 的模型
    if (!model.supported_parameters?.includes("tools")) continue;
    
    const input: ("text" | "image")[] = ["text"];
    if (model.architecture?.modality?.includes("image")) {
      input.push("image");
    }  // ← 同样的 image-only 检查
    
    models.push({
      id: model.id,
      reasoning: model.supported_parameters?.includes("reasoning") || false,
      input,
      // ...
    });
  }
}

3.3 独立的图像生成系统

pi-mono 有一个完全独立的图像生成子系统：

ImagesModel 类型有 input 和 output 两个字段，但同样限 ("text" | "image")[]。

4. 关键差异与能力缺口

5. 你需要区分的三类模型 — 实际表现

5.1 千问 3 ASR Flash（语音识别）

调用方式（Python 示例）：

import requests, base64, json

with open("audio.wav", "rb") as f:
    base64_audio = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    url="https://openrouter.ai/api/v1/audio/transcriptions",
    headers={"Authorization": "Bearer $OPENROUTER_API_KEY"},
    data=json.dumps({
        "model": "qwen/qwen3-asr-flash-2026-02-10",
        "input_audio": {"data": base64_audio, "format": "wav"}
    })
)
print(response.json()["text"])

对下游应用的影响：这是一个完全不同的 API 契约。无法通过检查 /v1/models 的 architecture 字段发现它。下游需要：

• 调用 /v1/audio/transcriptions 而非 /v1/chat/completions
• 发送 base64 音频数据而非 JSON messages
• 按音频秒计价而非按 token 计价

5.2 千问 3.6（多模态视觉模型）

5.3 MiniMax M2.7 / M3

区分正确：纯文本 vs 多模态可以依据 modality.includes("image") 准确判断。

5.4 下游应用的建议区分方案

如果你的下游应用需要精确区分三类模型：

function classifyModel(entry) {
  const m = entry.architecture?.modality ?? "";
  const inputs = entry.architecture?.input_modalities ?? [];
  
  return {
    isPureText:    inputs.length === 1 && inputs[0] === "text",
    hasVision:     m.includes("image") || inputs.includes("image"),
    hasAudio:     m.includes("audio") || inputs.includes("audio"),
    hasVideo:     m.includes("video") || inputs.includes("video"),
    hasFile:     m.includes("file")  || inputs.includes("file"),
    hasReasoning: entry.supported_parameters?.includes("reasoning"),
  };
}

分析完成。相关文件路径：
~/GitHub/oh-my-pi/packages/ai/src/types.ts (Model 类型定义)
~/GitHub/oh-my-pi/packages/ai/src/provider-models/openai-compat.ts (OpenRouter 发现 → L1371)
~/GitHub/pi-mono/packages/ai/scripts/generate-models.ts (静态目录生成 → L281)
~/GitHub/pi-mono/packages/ai/src/types.ts (pi-mono Model 类型)