Back to Details

openrouter-generations

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

openrouter-generations

OpenRouter生成任务查询

Retrieve detailed metadata and stored content for individual OpenRouter generations. Use this skill when you need to inspect a specific request — its cost, latency, token usage, provider routing, or the actual prompt/completion text.
检索单个OpenRouter生成任务的详细元数据和存储内容。当你需要检查特定请求（包括成本、延迟、token使用量、服务商路由情况，或实际的提示词/补全文本）时，使用此技能。

Prerequisites

前提条件

  • Any valid OpenRouter API key (regular or management key). Get one at openrouter.ai/settings/keys.
  • Pass it via 
    --api-key <key>
    or set the 
    OPENROUTER_API_KEY
    environment variable
  • Generation IDs look like 
    gen-1234567890
    or 
    gen-aBcDeFgHiJkLmNoPqRsT
    .
  • 任何有效的OpenRouter API密钥（常规密钥或管理密钥）。可在openrouter.ai/settings/keys获取。
  • 通过
    --api-key <key>
    传入密钥，或设置
    OPENROUTER_API_KEY
    环境变量
  • 生成任务ID格式类似
    gen-1234567890
    或
    gen-aBcDeFgHiJkLmNoPqRsT
    。

First-Time Setup

首次设置

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

Endpoints

接口端点

EndpointMethodPurpose
/api/v1/generation
GETRequest metadata and usage (tokens, cost, latency, model, provider)
/api/v1/generation/content
GETStored prompt and completion text
Both take a single query parameter: 
id
(the generation ID).
Full API reference: openrouter.ai/docs/api/api-reference/generations/get-generation
端点请求方法用途
/api/v1/generation
GET请求元数据和使用情况（token数量、成本、延迟、模型、服务商）
/api/v1/generation/content
GET获取存储的提示词和补全文本
两个接口都接受一个查询参数：
id
（生成任务ID）。
完整API参考：openrouter.ai/docs/api/api-reference/generations/get-generation

Workflow

操作流程

1. Get generation metadata

1. 获取生成任务元数据

Retrieves everything about a generation except the actual prompt/completion text:
bash
cd <skill-path>/scripts && npx tsx get-generation.ts gen-1234567890
npx tsx get-generation.ts --id gen-1234567890 --json
What you get back:
  • Model & routing: 
    model
    , 
    provider_name
    , 
    router
    , 
    service_tier
  • Tokens: 
    tokens_prompt
    , 
    tokens_completion
    , 
    native_tokens_reasoning
    , 
    native_tokens_cached
  • Cost: 
    total_cost
    , 
    usage
    , 
    upstream_inference_cost
    , 
    cache_discount
  • Performance: 
    latency
    , 
    generation_time
    , 
    moderation_latency
  • Status: 
    finish_reason
    , 
    streamed
    , 
    cancelled
    , 
    is_byok
  • Context: 
    created_at
    , 
    app_id
    , 
    external_user
    , 
    session_id
    , 
    request_id
  • Provider chain: 
    provider_responses
    array showing fallback attempts with per-provider latency and status
检索生成任务的所有信息（不包含实际的提示词/补全文本）：
bash
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
  • Token统计：
    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. Get generation content

2. 获取生成任务内容

Retrieves the stored prompt and completion:
bash
cd <skill-path>/scripts && npx tsx get-generation-content.ts gen-1234567890
npx tsx get-generation-content.ts --id gen-1234567890 --json
What you get back:
  • Input: 
    prompt
    (raw text) and/or 
    messages
    (array of 
    {role, content}
    )
  • Output: 
    completion
    (the model's response) and 
    reasoning
    (chain-of-thought, if applicable)
Note: Content is only available if the generation was not made with Zero Data Retention (ZDR) enabled. If ZDR was on, this endpoint returns empty/null content.
检索存储的提示词和补全文本：
bash
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
    （思维链内容，如有）
注意：仅当生成任务未启用Zero Data Retention（ZDR，零数据保留）时，才能获取内容。如果启用了ZDR，此接口将返回空值或null。

Direct API Usage (curl)

直接API调用（curl）

Get metadata

获取元数据

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

Get content

获取内容

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

Response Schemas

响应格式

Metadata response (
/api/v1/generation
)

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

json
{
  "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
      }
    ]
  }
}
json
{
  "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
      }
    ]
  }
}

Content response (
/api/v1/generation/content
)

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

json
{
  "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
    }
  }
}
json
{
  "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
    }
  }
}

Common Use Cases

常见使用场景

Debug a failed generation

调试失败的生成任务

bash
undefined
bash
undefined

Check what happened — look at finish_reason, provider_responses, and cancelled

查看详情——检查finish_reason、provider_responses和cancelled字段

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

Look for:
- `finish_reason` = `"length"` means the model hit max tokens
- `finish_reason` = `"content_filter"` means content was filtered
- `cancelled` = `true` means the request was cancelled by the client
- `provider_responses` with multiple entries means fallbacks occurred
cd <skill-path>/scripts && npx tsx get-generation.ts gen-abc123 --json

重点关注：
- `finish_reason` = `"length"` 表示模型达到了最大token限制
- `finish_reason` = `"content_filter"` 表示内容被过滤
- `cancelled` = `true` 表示请求被客户端取消
- `provider_responses`包含多个条目表示发生了重试

Check cost of a specific request

检查特定请求的成本

bash
cd <skill-path>/scripts && npx tsx get-generation.ts gen-abc123
Check 
total_cost
(what you were charged) vs 
upstream_inference_cost
(what the provider charged OpenRouter).
bash
cd <skill-path>/scripts && npx tsx get-generation.ts gen-abc123
对比
total_cost
（你的实际付费金额）和
upstream_inference_cost
（服务商向OpenRouter收取的费用）。

Review what was actually sent/received

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

bash
cd <skill-path>/scripts && npx tsx get-generation-content.ts gen-abc123
Useful for debugging unexpected outputs — verify the actual prompt sent and completion received.
bash
cd <skill-path>/scripts && npx tsx get-generation-content.ts gen-abc123
用于调试不符合预期的输出——验证实际发送的提示词和接收的补全文本。

Trace a multi-generation session

追踪多生成任务会话

If you have a 
request_id
or 
session_id
from one generation, you can find related generations via the analytics query endpoint (see 
openrouter-analytics
skill).
如果你有某个生成任务的
request_id
或
session_id
，可以通过分析查询接口找到相关生成任务（参考
openrouter-analytics
技能）。

Error Handling

错误处理

StatusMeaning
401Invalid or missing API key
403You don't have access to this generation (belongs to another user)
404Generation ID not found
429Rate limited — wait and retry
500Server error — retry
502Upstream failure — retry
状态码含义
401API密钥无效或缺失
403你无权访问此生成任务（属于其他用户）
404生成任务ID不存在
429请求频率超限——请等待后重试
500服务器错误——请重试
502上游服务故障——请重试

Key Fields Reference

关键字段参考

Metadata fields

元数据字段

FieldTypeDescription
id
stringGeneration ID (
gen-...
)
model
stringModel permaslug (e.g., 
openai/gpt-4o
)
provider_name
string|nullProvider that served the request
api_type
stringOne of: 
completions
, 
embeddings
, 
rerank
, 
tts
, 
stt
, 
video
tokens_prompt
int|nullPrompt token count
tokens_completion
int|nullCompletion token count
native_tokens_reasoning
int|nullReasoning/thinking tokens
native_tokens_cached
int|nullCached input tokens
total_cost
numberTotal cost in USD
usage
numberUsage amount in USD
upstream_inference_cost
number|nullProvider's cost in USD
cache_discount
number|nullDiscount from caching
latency
number|nullTotal latency in ms
generation_time
number|nullModel generation time in ms
moderation_latency
number|nullModeration check time in ms
finish_reason
string|nullWhy generation stopped (
stop
, 
length
, 
content_filter
, etc.)
native_finish_reason
string|nullRaw finish reason from provider
streamed
bool|nullWhether response was streamed
is_byok
boolWhether user's own provider key was used
cancelled
bool|nullWhether request was cancelled
app_id
int|nullOAuth app ID
external_user
string|nullExternal user identifier (X-External-User header)
session_id
string|nullSession grouping ID
request_id
string|nullRequest grouping ID (all gens from one API call)
router
string|nullRouter used (e.g., 
openrouter/auto
)
service_tier
string|nullProvider service tier
web_search_engine
string|nullSearch engine used (e.g., 
exa
, 
firecrawl
)
num_search_results
int|nullNumber of search results included
provider_responses
array|nullProvider attempt chain with per-provider latency/status
字段类型描述
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|nullOAuth应用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服务商调用链，包含每个服务商的延迟和状态

Content fields

内容字段

FieldTypeDescription
data.input.prompt
string|nullRaw prompt text
data.input.messages
array|nullMessages array (
[{role, content}]
)
data.output.completion
string|nullModel's completion text
data.output.reasoning
string|nullChain-of-thought reasoning
字段类型描述
data.input.prompt
string|null原始提示词文本
data.input.messages
array|null消息数组（
[{role, content}]
格式）
data.output.completion
string|null模型的补全文本
data.output.reasoning
string|null思维链推理内容