openrouter-generations

openrouter-generations

获取单个 OpenRouter 生成的详细元数据和存储内容。需要检查特定请求的费用、延迟、令牌用量、服务商路由或实际提示词／补全文本时，请使用此技能。

前提条件

• 任意有效的 OpenRouter API 密钥（普通密钥或管理密钥）。请前往 openrouter.ai/settings/keys 获取。
• 通过 --api-key <key> 传入密钥，或设置 OPENROUTER_API_KEY 环境变量
• 生成 ID 格式如 gen-1234567890 或 gen-aBcDeFgHiJkLmNoPqRsT。

首次设置

cd <skill-path>/scripts && npm install

端点

端点	方法	用途
/api/v1/generation	GET	请求元数据和用量（令牌、费用、延迟、模型、服务商）
/api/v1/generation/content	GET	存储的提示词和补全文本

两个端点都接受一个查询参数：id（生成 ID）。

完整 API 参考：openrouter.ai/docs/api/api-reference/generations/get-generation

工作流

1. 获取生成元数据

获取生成的所有信息，但不包括实际提示词／补全文本：

cd <skill-path>/scripts && npx tsx get-generation.ts gen-1234567890
npx tsx get-generation.ts --id gen-1234567890 --json

返回内容：

• 模型与路由：model、provider_name、router、service_tier
• 令牌：tokens_prompt、tokens_completion、native_tokens_reasoning、native_tokens_cached
• 费用：total_cost、usage、upstream_inference_cost、cache_discount
• 性能：latency、generation_time、moderation_latency
• 状态：finish_reason、streamed、cancelled、is_byok
• 上下文：created_at、app_id、external_user、session_id、request_id
• 服务商链：provider_responses 数组，显示回退尝试及各服务商的延迟和状态

2. 获取生成内容

获取存储的提示词和补全内容：

cd <skill-path>/scripts && npx tsx get-generation-content.ts gen-1234567890
npx tsx get-generation-content.ts --id gen-1234567890 --json

返回内容：

• 输入：prompt（原始文本）和／或 messages（{role, content} 数组）
• 输出：completion（模型的响应）和 reasoning（如适用，则为思维链）

**注意：**仅当生成请求未启用零数据保留（ZDR）时，才会提供内容。如果启用了 ZDR，此端点会返回空内容或 null。

直接使用 API（curl）

获取元数据

curl -G https://openrouter.ai/api/v1/generation \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d id=gen-1234567890

获取内容

curl -G https://openrouter.ai/api/v1/generation/content \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d id=gen-1234567890

响应架构

元数据响应（/api/v1/generation）

{
  "data": {
    "id": "gen-3bhGkxlo4XFrqiabUM7NDtwDzWwG",
    "api_type": "completions",
    "model": "openai/gpt-4o",
    "provider_name": "OpenAI",
    "created_at": "2024-07-15T23:33:19.433273+00:00",
    "tokens_prompt": 10,
    "tokens_completion": 25,
    "native_tokens_reasoning": 5,
    "native_tokens_cached": 3,
    "total_cost": 0.0015,
    "usage": 0.0015,
    "upstream_inference_cost": 0.0012,
    "latency": 1250,
    "generation_time": 1200,
    "finish_reason": "stop",
    "streamed": true,
    "is_byok": false,
    "cancelled": false,
    "router": "openrouter/auto",
    "service_tier": "priority",
    "provider_responses": [
      {
        "provider_name": "OpenAI",
        "model_permaslug": "openai/gpt-4o",
        "status": 200,
        "latency": 1200,
        "is_byok": false
      }
    ]
  }
}

内容响应（/api/v1/generation/content）

{
  "data": {
    "input": {
      "prompt": "What is the meaning of life?",
      "messages": [
        {
          "content": "What is the meaning of life?",
          "role": "user"
        }
      ]
    },
    "output": {
      "completion": "The meaning of life is a philosophical question...",
      "reasoning": null
    }
  }
}

常见用例

调试失败的生成

# Check what happened — look at finish_reason, provider_responses, and cancelled
cd <skill-path>/scripts && npx tsx get-generation.ts gen-abc123 --json

请检查：

• finish_reason = "length" 表示模型达到最大令牌数
• finish_reason = "content_filter" 表示内容被过滤
• cancelled = true 表示请求已被客户端取消
• provider_responses 中包含多条记录表示发生了回退

检查特定请求的费用

cd <skill-path>/scripts && npx tsx get-generation.ts gen-abc123

检查 total_cost（向你收取的费用）与 upstream_inference_cost（服务商向 OpenRouter 收取的费用）。

查看实际发送／接收的内容

cd <skill-path>/scripts && npx tsx get-generation-content.ts gen-abc123

这有助于调试意外输出——核实实际发送的提示词和收到的补全内容。

跟踪多代次会话

如果你有某次生成的 request_id 或 session_id，可以通过分析查询端点查找相关生成（参见 openrouter-analytics 技能）。

错误处理

状态	含义
401	API 密钥无效或缺失
403	你无权访问此生成（属于其他用户）
404	未找到生成 ID
429	请求过于频繁——请等待后重试
500	服务器错误——请重试
502	上游故障——请重试

关键字段参考

元数据字段

字段	类型	描述
id	string	生成 ID（gen-...）
model	string	模型永久标识符（例如，openai/gpt-4o）
provider_name	string|null	提供该请求服务的提供商
api_type	string	以下之一：completions、embeddings、rerank、tts、stt、video
tokens_prompt	int|null	提示词 token 数量
tokens_completion	int|null	补全 token 数量
native_tokens_reasoning	int|null	推理／思考 token 数量
native_tokens_cached	int|null	缓存的输入 token 数量
total_cost	number	总费用（美元）
usage	number	使用费用（美元）
upstream_inference_cost	number|null	提供商的费用（美元）
cache_discount	number|null	缓存折扣
latency	number|null	总延迟（毫秒）
generation_time	number|null	模型生成时间（毫秒）
moderation_latency	number|null	内容审核检查时间（毫秒）
finish_reason	string|null	生成停止的原因（stop、length、content_filter 等）
native_finish_reason	string|null	提供商返回的原始结束原因
streamed	bool|null	响应是否以流式方式传输
is_byok	bool	是否使用了用户自己的提供商密钥
cancelled	bool|null	请求是否已取消
app_id	int|null	OAuth 应用 ID
external_user	string|null	外部用户标识符（X-External-User 标头）
session_id	string|null	会话分组 ID
request_id	string|null	请求分组 ID（一次 API 调用中的所有生成记录）
router	string|null	使用的路由器（例如，openrouter/auto）
service_tier	string|null	提供商服务层级
web_search_engine	string|null	使用的搜索引擎（例如，exa、firecrawl）
num_search_results	int|null	包含的搜索结果数量
provider_responses	array|null	提供商尝试链，包含各提供商的延迟／状态

内容字段

字段	类型	描述
data.input.prompt	string|null	原始提示词文本
data.input.messages	array|null	消息数组（[{role, content}]）
data.output.completion	string|null	模型的补全文本
data.output.reasoning	string|null	思维链推理