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（該当する場合は思考の連鎖）

注： コンテンツを取得できるのは、生成時に Zero Data Retention（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	モデルの permaslug（例：openai/gpt-4o）
provider_name	string|null	リクエストを処理したプロバイダー
api_type	string	次のいずれか：completions、embeddings、rerank、tts、stt、video
tokens_prompt	int|null	プロンプトのトークン数
tokens_completion	int|null	生成されたテキストのトークン数
native_tokens_reasoning	int|null	推論／思考トークン数
native_tokens_cached	int|null	キャッシュされた入力トークン数
total_cost	number	合計費用（USD）
usage	number	使用量（USD）
upstream_inference_cost	number|null	プロバイダーの費用（USD）
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（1 回の 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	思考の連鎖による推論