Lovely RouterDocs
Get a key
API reference

Models endpoints

Reference for the LLM endpoints in Anthropic, OpenAI and Gemini format, with the Lovely Router headers each one accepts and returns.

The model endpoints are the vendors' own APIs, served at https://lovelyrouter.com. Request and response bodies follow the vendor schema and pass through unchanged, so this page lists the parameters you use most and links to the vendor reference for the rest. Behavior common to all of them is described in How the gateway works.

Every endpoint accepts the API key as Authorization: Bearer, x-api-key, x-goog-api-key or a ?key= query parameter. Errors are returned in the format of the API you called; see Errors.

Response headers

x-lovely-request-idstring

Id of the call, for example req_6f1c0b9e2d4a47a1b8c3d5e7. Shown in Logs. Present on successful responses and on 429 capacity and 502 errors.

x-lovely-groupstring

The channel group that served the call.

x-lovely-channelstring

The group's channel label, URL-encoded.

x-lovely-queued-msinteger

Milliseconds the request waited for capacity. Only present when it waited.

retry-afterinteger

Seconds to wait. Sent with 429 responses caused by key limits or busy capacity.

Create a message#

POST/v1/messages

Generates a response from a model using the Anthropic Messages API. Set stream to receive server-sent events. Thinking, tools, images and prompt caching pass through as Anthropic documents them. Guide: Anthropic Messages.

Headers

x-api-keystringRequired

Your Lovely Router key. Authorization: Bearer works too.

anthropic-versionstringDefault 2023-06-01

Forwarded to the model.

anthropic-betastring

Forwarded as sent.

x-lovely-groupstring

Channel group for this request, such as claude-value. Ignored when the key is bound to a group.

x-session-idstring

Stable id for the conversation, used to route every turn to the channel that holds its cache.

Body parameters

modelstringRequired

Model id from GET /v1/models, such as claude-sonnet-5.5. Other spellings like claude-sonnet-5-5 resolve to the same model.

messagesarrayRequired

The conversation so far, alternating user and assistant turns.

max_tokensintegerRequired

Maximum number of tokens to generate.

systemstring or array

System prompt. Text blocks accept cache_control.

streambooleanDefault false

Stream the response as server-sent events.

thinkingobject

Extended thinking settings for the model.

output_configobject

Output settings such as effort and format.

toolsarray

Tools the model may call.

tool_choiceobject

How the model chooses tools.

metadataobject

Request metadata.

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
  }
}

Count message tokens#

POST/v1/messages/count_tokens

Estimates the input tokens of a message request without running it. Free, and available with a zero balance. The count is approximate: use it for context-window checks and budgeting; the charge for a real call comes from its usage. Anthropic's token counting guide.

Headers

x-api-keystringRequired

Your Lovely Router key. Authorization: Bearer works too.

x-lovely-groupstring

Channel group to check the model against. Ignored when the key is bound to a group.

Body parameters

modelstringRequired

Model id, as for POST /v1/messages.

messagesarrayRequired

The messages to count.

systemstring or array

System prompt to include in the count.

toolsarray

Tool definitions to include in the count.

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
}

Create a chat completion#

POST/v1/chat/completions

Generates a response using the OpenAI Chat Completions API. Every model in GET /v1/models accepts this format. Streaming requests always get stream_options.include_usage: true, so the last chunk carries usage. Guide: OpenAI Chat Completions.

Headers

AuthorizationstringRequired

Bearer followed by your Lovely Router key.

openai-betastring

Forwarded as sent.

x-lovely-groupstring

Channel group for this request, such as gpt-value. Ignored when the key is bound to a group.

x-session-idstring

Stable id for the conversation, used to route every turn to the channel that holds its cache.

Body parameters

modelstringRequired

Model id from GET /v1/models, such as gpt-6.1-sol.

messagesarrayRequired

The conversation so far: system or developer, user, assistant and tool messages.

streambooleanDefault false

Stream the response as server-sent events, ending with data: [DONE].

max_completion_tokensinteger

Upper bound on generated tokens, including reasoning tokens.

reasoning_effortstring

How much a reasoning model thinks. Values depend on the model.

toolsarray

Functions the model may call.

tool_choicestring or object

How the model chooses tools.

response_formatobject

Request JSON output or a JSON Schema.

prompt_cache_keystring

Improves cache hit rates. Also used as the conversation id for routing.

userstring

End-user id. Used as the conversation id for routing when nothing more specific is sent.

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}
  }
}

Create a response#

POST/v1/responses

Generates a response using the OpenAI Responses API, the API Codex CLI uses. Served for GPT models only; other models return 404. Responses aren't stored: send the whole conversation in input. Guide: Responses API.

Headers

AuthorizationstringRequired

Bearer followed by your Lovely Router key.

openai-betastring

Forwarded as sent.

x-lovely-groupstring

Channel group for this request, such as gpt-value. Ignored when the key is bound to a group.

x-session-idstring

Stable id for the conversation, used to route every turn to the channel that holds its cache.

Body parameters

modelstringRequired

A GPT model id from GET /v1/models, such as gpt-6.1-sol.

inputstring or arrayRequired

The prompt, or the conversation as a list of input items.

instructionsstring

System instructions. The response echoes what you sent, or null.

streambooleanDefault false

Stream typed server-sent events, ending with response.completed (which carries usage).

max_output_tokensinteger

Upper bound on generated tokens, including reasoning tokens.

reasoningobject

Reasoning settings such as effort. Values depend on the model.

toolsarray

Functions and other tools the model may call.

storeboolean

Send false: responses aren't kept for later retrieval.

prompt_cache_keystring

Improves cache hit rates. Also used as the conversation id for routing.

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
  }'

Generate content#

POST/v1beta/models/{model}:generateContent

Generates a response using the Gemini API. Guide: Gemini.

Path parameters

modelstringRequired

Model id, such as gemini-3.1-pro. Google spellings like gemini-3.1-pro-preview resolve to the same model.

Headers

x-goog-api-keystringRequired

Your Lovely Router key. Authorization: Bearer or a ?key= query parameter work too.

x-lovely-groupstring

Channel group for this request, such as gemini-value. Ignored when the key is bound to a group.

x-session-idstring

Stable id for the conversation, used to route every turn to the channel that holds its cache.

Body parameters

contentsarrayRequired

The conversation so far, as user and model turns made of parts.

systemInstructionobject

System instruction, as a content object with text parts.

generationConfigobject

Output settings: maxOutputTokens, temperature, responseMimeType, thinkingConfig and more.

toolsarray

Function declarations and other tools.

toolConfigobject

How the model chooses functions.

safetySettingsarray

Per-category safety thresholds.

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

Stream generated content#

POST/v1beta/models/{model}:streamGenerateContent

Same request as generateContent, returned as a stream. Add alt=sse to receive server-sent events, one partial response per event; the SDKs do this for you. Without it, the response is a single streamed JSON array. See Streaming.

Query parameters

altstring

Set to sse for server-sent events. Recommended.

The path parameter, headers and body are the same as for Generate content.

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}}

Count Gemini tokens#

POST/v1beta/models/{model}:countTokens

Estimates the tokens in contents without running the model. Free, and available with a zero balance. The count is approximate. Gemini reference.

Body parameters

contentsarrayRequired

The content to count, in the same shape as for generateContent.

The path parameter and headers are the same as for Generate content.

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
}

List models#

GET/v1/models

Lists every model you can call now, with context size, list prices and the channel groups that serve it. No API key is needed. The shape works with models.list() in both the OpenAI and Anthropic SDKs. Field meanings are in Models & pricing.

Response fields

dataarray

One object per model.

has_moreboolean

Always false: the whole list is returned at once.

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

List models in Gemini format#

GET/v1beta/models

Lists the models available through the Gemini endpoints, in the Gemini API's shape. No API key is needed. The Google Gen AI SDKs call it from models.list(). Prices are only in 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"]
    }
  ]
}
← Previous
Introduction
API reference
Next →
Tools endpoints
API reference