API リファレンス

モデルのエンドポイント

Anthropic・OpenAI・Gemini 形式の LLM エンドポイントのリファレンスです。各エンドポイントが受け付ける Lovely Router のヘッダーと、返すヘッダーも掲載しています。

モデルのエンドポイントは、各ベンダー自身の API を https://lovelyrouter.com で提供するものです。リクエストとレスポンスのボディはベンダーのスキーマに従い、変更されずにそのまま受け渡されます。そのため、このページではよく使うパラメータだけを取り上げ、それ以外はベンダーのリファレンスへのリンクで案内します。すべてのエンドポイントに共通する動作はゲートウェイの仕組みで説明しています。

どのエンドポイントも、API キーを Authorization: Bearer、x-api-key、x-goog-api-key、?key= クエリパラメータのいずれでも受け付けます。エラーは呼び出した API の形式で返されます。詳しくはエラーを参照してください。

レスポンスヘッダー

x-lovely-request-idstring

呼び出しの ID です（例：req_6f1c0b9e2d4a47a1b8c3d5e7）。ログに表示されます。成功したレスポンスと、容量不足による 429 エラーおよび 502 エラーに含まれます。

x-lovely-groupstring

呼び出しを処理したチャネルグループ。

x-lovely-channelstring

グループ内のチャネルのラベル。URL エンコードされています。

x-lovely-queued-msinteger

リクエストが容量の空きを待ったミリ秒数。待機した場合にのみ含まれます。

retry-afterinteger

待機すべき秒数。キーの制限または容量の混雑による 429 レスポンスで送られます。

メッセージを作成する#

POST/v1/messages

Anthropic Messages API を使って、モデルからレスポンスを生成します。stream を設定すると、サーバー送信イベントで受け取れます。思考、ツール、画像、プロンプトキャッシュは、Anthropic のドキュメントどおりにそのまま受け渡されます。ガイド：Anthropic Messages

ヘッダー

x-api-keystring必須

Lovely Router のキー。Authorization: Bearer でも送れます。

anthropic-versionstringデフォルト 2023-06-01

モデルに転送されます。

anthropic-betastring

送信した値のまま転送されます。

x-lovely-groupstring

このリクエストで使うチャネルグループ（例：claude-value）。キーがグループに紐付けられている場合は無視されます。

x-session-idstring

会話ごとに固定の ID。すべてのターンを、その会話のキャッシュを持つチャネルにルーティングするために使います。

ボディパラメータ

modelstring必須

GET /v1/models のモデル ID（例：claude-sonnet-5.5）。claude-sonnet-5-5 のような別の表記も同じモデルとして解決されます。

messagesarray必須

これまでの会話。user と assistant のターンを交互に並べます。

max_tokensinteger必須

生成するトークン数の上限。

systemstring or array

システムプロンプト。テキストブロックには cache_control を指定できます。

streambooleanデフォルト false

レスポンスをサーバー送信イベントでストリーミングします。

thinkingobject

モデルの拡張思考の設定。

output_configobject

effort や format などの出力設定。

toolsarray

モデルが呼び出せるツール。

tool_choiceobject

モデルがツールを選ぶ方法。

metadataobject

リクエストのメタデータ。

Shell

curl https://lovelyrouter.com/v1/messages \
  -H "x-api-key: $LOVELY_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5.5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'

Response

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [
    {"type": "text", "text": "Hello! How can I help you today?"}
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 10,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "output_tokens": 12
  }
}

メッセージのトークン数を数える#

POST/v1/messages/count_tokens

メッセージリクエストを実行せずに、入力トークン数を見積もります。無料で、残高が 0 でも利用できます。カウントは概算です。コンテキストウィンドウの確認や予算の見積もりに使ってください。実際の呼び出しの料金は、その呼び出しの usage に基づいて計算されます。Anthropic のトークンカウントガイド

ヘッダー

x-api-keystring必須

Lovely Router のキー。Authorization: Bearer でも送れます。

x-lovely-groupstring

モデルを照合するチャネルグループ。キーがグループに紐付けられている場合は無視されます。

ボディパラメータ

modelstring必須

モデル ID。POST /v1/messages と同じです。

messagesarray必須

カウントするメッセージ。

systemstring or array

カウントに含めるシステムプロンプト。

toolsarray

カウントに含めるツール定義。

Shell

curl https://lovelyrouter.com/v1/messages/count_tokens \
  -H "x-api-key: $LOVELY_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5.5",
       "messages": [{"role": "user", "content": "Hello, Claude"}]}'

Response

{
  "input_tokens": 24
}

チャット補完を作成する#

POST/v1/chat/completions

OpenAI Chat Completions API を使ってレスポンスを生成します。GET /v1/models のすべてのモデルがこの形式に対応しています。ストリーミングのリクエストには常に stream_options.include_usage: true が設定されるため、最後のチャンクに usage が含まれます。ガイド：OpenAI Chat Completions

ヘッダー

Authorizationstring必須

Bearer に続けて Lovely Router のキーを指定します。

openai-betastring

送信した値のまま転送されます。

x-lovely-groupstring

このリクエストで使うチャネルグループ（例：gpt-value）。キーがグループに紐付けられている場合は無視されます。

x-session-idstring

会話ごとに固定の ID。すべてのターンを、その会話のキャッシュを持つチャネルにルーティングするために使います。

ボディパラメータ

modelstring必須

GET /v1/models のモデル ID（例：gpt-6.1-sol）。

messagesarray必須

これまでの会話。system または developer、user、assistant、tool のメッセージで構成します。

streambooleanデフォルト false

レスポンスをサーバー送信イベントでストリーミングします。最後は data: [DONE] で終わります。

max_completion_tokensinteger

生成するトークン数の上限。推論トークンも含みます。

reasoning_effortstring

推論モデルがどの程度考えるか。指定できる値はモデルによって異なります。

toolsarray

モデルが呼び出せる関数。

tool_choicestring or object

モデルがツールを選ぶ方法。

response_formatobject

JSON 出力、または JSON Schema に沿った出力を要求します。

prompt_cache_keystring

キャッシュのヒット率を高めます。ルーティング用の会話 ID としても使われます。

userstring

エンドユーザーの ID。より具体的な値が送られていない場合、ルーティング用の会話 ID として使われます。

Shell

curl https://lovelyrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Response

{
  "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG",
  "object": "chat.completion",
  "created": 1791700000,
  "model": "gpt-6.1-sol",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Hello! How can I help?"},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 0}
  }
}

レスポンスを作成する#

POST/v1/responses

OpenAI Responses API を使ってレスポンスを生成します。Codex CLI が使う API です。GPT のモデルにのみ提供され、それ以外のモデルは 404 を返します。レスポンスは保存されないため、会話全体を input で送ってください。ガイド：Responses API

ヘッダー

Authorizationstring必須

Bearer に続けて Lovely Router のキーを指定します。

openai-betastring

送信した値のまま転送されます。

x-lovely-groupstring

このリクエストで使うチャネルグループ（例：gpt-value）。キーがグループに紐付けられている場合は無視されます。

x-session-idstring

会話ごとに固定の ID。すべてのターンを、その会話のキャッシュを持つチャネルにルーティングするために使います。

ボディパラメータ

modelstring必須

GET /v1/models の GPT のモデル ID（例：gpt-6.1-sol）。

inputstring or array必須

プロンプト、または入力アイテムのリストとして表した会話。

instructionsstring

システム指示。レスポンスには送信した値がそのまま返ります（送信しなかった場合は null）。

streambooleanデフォルト false

型付きのサーバー送信イベントでストリーミングします。最後は response.completed（usage を含みます）で終わります。

max_output_tokensinteger

生成するトークン数の上限。推論トークンも含みます。

reasoningobject

effort などの推論の設定。指定できる値はモデルによって異なります。

toolsarray

モデルが呼び出せる関数やその他のツール。

storeboolean

false を送信してください。レスポンスは後から取得できるようには保存されません。

prompt_cache_keystring

キャッシュのヒット率を高めます。ルーティング用の会話 ID としても使われます。

Shell

curl https://lovelyrouter.com/v1/responses \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "input": "Hello!",
    "store": false
  }'

コンテンツを生成する#

POST/v1beta/models/{model}:generateContent

Gemini API を使ってレスポンスを生成します。ガイド：Gemini

パスパラメータ

modelstring必須

モデル ID（例：gemini-3.1-pro）。gemini-3.1-pro-preview のような Google の表記も同じモデルとして解決されます。

ヘッダー

x-goog-api-keystring必須

Lovely Router のキー。Authorization: Bearer や ?key= クエリパラメータでも送れます。

x-lovely-groupstring

このリクエストで使うチャネルグループ（例：gemini-value）。キーがグループに紐付けられている場合は無視されます。

x-session-idstring

会話ごとに固定の ID。すべてのターンを、その会話のキャッシュを持つチャネルにルーティングするために使います。

ボディパラメータ

contentsarray必須

これまでの会話。parts で構成される user と model のターンとして指定します。

systemInstructionobject

システム指示。テキストパートを持つコンテンツオブジェクトとして指定します。

generationConfigobject

出力設定。maxOutputTokens、temperature、responseMimeType、thinkingConfig などを指定します。

toolsarray

関数宣言やその他のツール。

toolConfigobject

モデルが関数を選ぶ方法。

safetySettingsarray

カテゴリごとの安全性のしきい値。

Shell

curl "https://lovelyrouter.com/v1beta/models/gemini-3.1-pro:generateContent" \
  -H "x-goog-api-key: $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Hello!"}]}]}'

Response

{
  "candidates": [
    {
      "content": {"role": "model", "parts": [{"text": "Hello! How can I help?"}]},
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 7,
    "thoughtsTokenCount": 96,
    "totalTokenCount": 106
  },
  "responseId": "mFHoaNC1Lo3HqtsP"
}

生成コンテンツをストリーミングする#

POST/v1beta/models/{model}:streamGenerateContent

generateContent と同じリクエストで、レスポンスをストリームとして返します。alt=sse を付けると、1 イベントにつき 1 つの部分レスポンスをサーバー送信イベントで受け取れます。SDK はこれを自動で付けます。付けない場合、レスポンスはストリーミングされる 1 つの JSON 配列になります。ストリーミングを参照してください。

クエリパラメータ

altstring

sse に設定すると、サーバー送信イベントで受け取れます。推奨です。

パスパラメータ、ヘッダー、ボディはコンテンツを生成すると同じです。

Shell

curl -N "https://lovelyrouter.com/v1beta/models/gemini-3-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Count to three."}]}]}'

Response

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"One, two,"}]}}],"usageMetadata":{"promptTokenCount":5,"candidatesTokenCount":4,"totalTokenCount":9}}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":" three."}]},"finishReason":"STOP"}],"usageMetadata":{"promptTokenCount":5,"candidatesTokenCount":7,"totalTokenCount":12}}

Gemini のトークン数を数える#

POST/v1beta/models/{model}:countTokens

モデルを実行せずに、contents のトークン数を見積もります。無料で、残高が 0 でも利用できます。カウントは概算です。Gemini のリファレンス

ボディパラメータ

contentsarray必須

カウントするコンテンツ。generateContent と同じ形式で指定します。

パスパラメータとヘッダーはコンテンツを生成すると同じです。

Shell

curl "https://lovelyrouter.com/v1beta/models/gemini-3.1-pro:countTokens" \
  -H "x-goog-api-key: $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Hello, Gemini"}]}]}'

Response

{
  "totalTokens": 18
}

モデルを一覧表示する#

GET/v1/models

現在呼び出せるすべてのモデルを、コンテキストサイズ、定価、提供元のチャネルグループとともに一覧表示します。API キーは不要です。レスポンスの形式は、OpenAI と Anthropic の両方の SDK の models.list() で扱えます。各フィールドの意味はモデルと料金を参照してください。

レスポンスのフィールド

dataarray

モデルごとに 1 つのオブジェクト。

has_moreboolean

常に false です。一覧全体が一度に返されます。

Shell

curl https://lovelyrouter.com/v1/models

Response

{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet-5.5",
      "object": "model",
      "type": "model",
      "display_name": "Claude Sonnet 5.5",
      "created": 1700000000,
      "created_at": "2025-01-01T00:00:00Z",
      "owned_by": "Anthropic",
      "context_length": 1000000,
      "pricing": {
        "input": 2,
        "output": 10,
        "cache_read": 0.1,
        "cache_write": 2.5,
        "unit": "USD per 1M tokens"
      },
      "groups": ["claude-value"]
    }
  ],
  "has_more": false,
  "first_id": "claude-fable-5.1",
  "last_id": "gpt-5.6-luna"
}

Gemini 形式でモデルを一覧表示する#

GET/v1beta/models

Gemini のエンドポイントで利用できるモデルを、Gemini API の形式で一覧表示します。API キーは不要です。Google Gen AI SDK は models.list() からこのエンドポイントを呼び出します。価格は GET /v1/models にのみ含まれます。

cURL

curl https://lovelyrouter.com/v1beta/models

Response

{
  "models": [
    {
      "name": "models/gemini-3.1-pro",
      "displayName": "Gemini 3.1 Pro",
      "inputTokenLimit": 1048576,
      "supportedGenerationMethods": ["generateContent", "streamGenerateContent", "countTokens"]
    }
  ]
}