API Reference - Hostlinku Docs

Base URL: https://api.hostlinku.com. All gateway endpoints are located under /v1 and accept the Hostlinku API key (sk-…) via the Authorization: Bearer or x-api-key header.

Rate Limiting

To maintain service quality for all users, the gateway enforces the following limits per API key:

Limit Type	Quota	Description
RPM (Requests/Minute)	600 req/min	Per API key, shared across all models
RPD (Requests/Day)	Unlimited	Limited by account balance & credit limit per API key
TPM (Tokens/Minute)	Unrestricted	`max_tokens` must be ≤ the model’s output limit (rejected as `400` if exceeded)

Rate limit details:

60-second window per API key; requests from all models are counted together.
Requests rejected by the limiter do not affect the balance (no credit is reserved).
Console and public endpoints (/api/*) are limited to 120 requests per minute per IP; authentication endpoints 30 attempts / 15 minutes per IP.

When you reach the limit:

Returns an HTTP 429 Too Many Requests error.
The Retry-After header specifies the recommended number of seconds before retrying.
The RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset headers (IETF format) indicate the current RPM quota.

Anthropic Messages API Format

POST /v1/messages Call the model using the native Anthropic format. The request header must include x-api-key: YOUR_API_KEY (or Authorization: Bearer). Compatible with the Anthropic SDK, Claude Code, Cursor, and Cline—simply set ANTHROPIC_BASE_URL=https://api.hostlinku.com. Complete documentation: Anthropic Messages.

Request Body Parameters

Parameter	Type	Description	Required
`model`	string	Hostlinku model slug, e.g., `claude-sonnet-4-6`	true
`messages`	array	Array of conversation messages (`role`: `user`	`assistant`)	true
`max_tokens`	integer	Maximum number of output tokens	true
`system`	string \| array	System prompt (block arrays support `cache_control`)	false
`stream`	boolean	SSE streaming, default `false`	false
`tools`, `tool_choice`, `thinking`, `temperature`, `top_p`, `top_k`, `stop_sequences`, `metadata`	—	As specified by Anthropic	false

Example Request

curl --request POST \
  --url https://api.hostlinku.com/v1/messages \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'anthropic-version: 2023-06-01' \
  --data '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": "You are a professional coding assistant",
    "messages": [
      { "role": "user", "content": "Write a quicksort in Python" }
    ]
  }'

Response Example

{
  "id": "msg_mv5ujf05qf6ayfbx",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    { "type": "text", "text": "def quicksort(arr):\n    if len(arr) <= 1:\n        return arr\n    ..." }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 14,
    "output_tokens": 86,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "cache_creation": { "ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0 }
  },
  "hostlinku": { "cost": 0.0013, "currency": "🪙", "serviceMode": "performance", "latencyMs": 2410 }
}

Output Streaming

curl -N --request POST \
  --url https://api.hostlinku.com/v1/messages \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'accept: text/event-stream' \
  --data '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": [{ "type": "text", "text": "Hello" }] }],
    "stream": true
  }'

Responses are sent per segment in SSE format:

event: message_start
data: {"type":"message_start","message":{"id":"msg_…","type":"message","role":"assistant","model":"claude-sonnet-4-6","content":[],"stop_reason":null,"usage":{"input_tokens":10,"output_tokens":1}}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":10,"output_tokens":5}}

event: message_stop
data: {"type":"message_stop"}

OpenAI Protocol (Chat Completions API)

POST /v1/chat/completions Call any model using the OpenAI Chat Completions format. The request header must include Authorization: Bearer YOUR_API_KEY. The OpenAI SDK simply needs to be configured with base_url="https://api.hostlinku.com/v1". Full documentation: Chat Completions.

Request Body Parameters

Parameter	Type	Description	Required
`model`	string	Hostlinku model slug, e.g., `gpt-5-5`	true
`messages`	array	Array of conversation messages (`system`	`user`	`assistant`	`tool`)	true
`max_tokens`	integer	Maximum number of output tokens	false
`stream`	boolean	SSE streaming, default `false`	false
`temperature`, `top_p`, `tools`, `tool_choice`, `response_format`, `reasoning_effort`, `thinking`	—	As per OpenAI specifications (+ the “thinking” extension)	false

Example Request

curl https://api.hostlinku.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "gpt-5-5",
    "messages": [
      { "role": "user", "content": "Write a quicksort in Python" }
    ],
    "stream": false
  }'

Example Response

{
  "id": "cmpl_mv5strfqh3zktr",
  "object": "chat.completion",
  "created": 1770000000,
  "model": "gpt-5-5",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "def quicksort(arr):\n    if len(arr) <= 1:\n        return arr\n    ..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 86, "total_tokens": 98 },
  "hostlinku": { "cost": 0.0009, "currency": "🪙", "serviceMode": "performance", "latencyMs": 1890 }
}

Output Streaming

curl -N https://api.hostlinku.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "gpt-5-5",
    "messages": [{ "role": "user", "content": "Hello" }],
    "stream": true
  }'

data: {"id":"cmpl_…","object":"chat.completion.chunk","model":"gpt-5-5","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}

data: {"id":"cmpl_…","object":"chat.completion.chunk","model":"gpt-5-5","choices":[{"index":0,"delta":{"content":"Hello"}}]}

data: {"id":"cmpl_…","object":"chat.completion.chunk","model":"gpt-5-5","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":5,"completion_tokens":12,"total_tokens":17}}

data: [DONE]

OpenAI Responses API Format

POST /v1/responses The format used by Codex CLI, OpenAI Agents SDK, and client.responses.create(). The request header includes Authorization: Bearer YOUR_API_KEY; the base URL is https://api.hostlinku.com/v1. Stateless: store is always false, previous_response_id results in a 400 error — send the full history in input. Complete documentation: Responses API.

Request Body Parameters

Parameter	Type	Description	Required
`model`	string	Hostlinku model slug, e.g., `gpt-5-5`	true
`input`	string \| array	Text, or an array of items: `message` / `function_call` / `function_call_output` / `reasoning`	true
`instructions`	string	System prompt	false
`max_output_tokens`	integer	Maximum number of output tokens	false
`stream`	boolean	SSE streaming (`event: response.*`), default `false`	false
`tools`, `tool_choice`, `reasoning`, `include`, `text`, `temperature`, `top_p`, `metadata`	—	As specified in the OpenAI Responses documentation	false

Example Request

curl https://api.hostlinku.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "gpt-5-5",
    "instructions": "Be concise.",
    "input": "Write a quicksort in Python",
    "max_output_tokens": 512
  }'

Example Response

{
  "id": "resp_mv5xpsggbnpc4x7g",
  "object": "response",
  "created_at": 1791850828,
  "status": "completed",
  "model": "gpt-5-5",
  "output": [
    { "id": "rs_…", "type": "reasoning", "summary": [], "encrypted_content": "…" },
    { "id": "msg_…", "type": "message", "status": "completed", "role": "assistant",
      "content": [{ "type": "output_text", "text": "def quicksort(arr): …", "annotations": [] }] }
  ],
  "usage": { "input_tokens": 20, "output_tokens": 95, "total_tokens": 115,
             "input_tokens_details": { "cached_tokens": 0 }, "output_tokens_details": { "reasoning_tokens": 12 } },
  "previous_response_id": null,
  "store": false,
  "hostlinku": { "cost": 0.0011, "currency": "🪙", "serviceMode": "performance", "latencyMs": 1420 }
}

Output Streaming

event: response.created
data: {"type":"response.created","sequence_number":0,"response":{"id":"resp_…","status":"in_progress","model":"gpt-5-5","output":[]}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","sequence_number":4,"item_id":"msg_…","output_index":0,"content_index":0,"delta":"def quicksort"}

event: response.completed
data: {"type":"response.completed","sequence_number":8,"response":{"id":"resp_…","status":"completed","output":[…],"usage":{"input_tokens":20,"output_tokens":95,"total_tokens":115}}}

Error Codes

The envelope error follows the protocol of the called endpoint: /v1/chat/completions → { "status": "error", "error": { "code", "message" } }; /v1/messages → { "type": "error", "error": { "type", "message" } }; /v1/responses → { "error": { "message", "type", "param", "code" } }.

HTTP Status Code	Description	Example Error Message
400	Invalid body, `max_tokens` exceeds the model’s output limit, or the model is not available with this Service Mode API key.	`max_tokens (20000) exceeds the output limit of the 'claude-haiku-4-5' model (16000).`
401	The API key was not provided, is invalid, has been revoked, or has expired.	`The API key is invalid or has been revoked.`
402	Insufficient balance to cover the estimated cost of the request, or the API key’s credit limit has been reached.	`Insufficient balance.`
403	Account suspended / access denied.	`You do not have access to this resource.`
404	The model slug is not in the catalog.	`Model 'xxx' not found.`
413	The request body exceeds the maximum size.	`Payload is too large.`
422	Body validation failed (only `/v1/chat/completions`; `/v1/messages` and `/v1/responses` return a 400).	`Invalid request body.`
429	Rate limit exceeded.	`Rate limit exceeded. Upgrade to a plan with a higher limit.`
503	Model/upstream is currently unavailable — it is safe to retry with backoff.	`The model is currently unavailable. Please try again later.`

Error messages never contain the identity or raw text of the upstream provider. A complete list of OpenAI-format codes is available at Error.

429 Response Headers

Response Header	Description
`Retry-After`	Recommended wait time before retrying (seconds)
`RateLimit-Limit`	RPM Limit
`RateLimit-Remaining`	Remaining requests in the current window
`RateLimit-Reset`	Seconds until the next window begins

Query Available Models

GET /v1/models Returns the available models for the Service Mode API key being used, along with the price per 1M tokens in that mode.

Example Request

curl --request GET \
  --url https://api.hostlinku.com/v1/models \
  --header 'Authorization: Bearer YOUR_API_KEY'

Response Example

{
  "object": "list",
  "service_mode": "performance",
  "data": [
    {
      "id": "claude-haiku-4-5",
      "object": "model",
      "created": 1760000000,
      "owned_by": "hostlinku",
      "context_window": 200000,
      "capabilities": ["text", "tool-calling", "json-mode", "streaming", "long-context"],
      "service_mode": "performance",
      "pricing": { "input": 0.8, "output": 4, "cache_read": 0.08, "cache_write": 1, "unit": "1M_tokens", "currency": "🪙" }
    },
    {
      "id": "claude-sonnet-4-6",
      "object": "model",
      "created": 1760000000,
      "owned_by": "hostlinku",
      "context_window": 1000000,
      "capabilities": ["text", "vision", "tool-calling", "json-mode", "streaming", "reasoning", "long-context"],
      "service_mode": "performance",
      "pricing": { "input": 2.4, "output": 12, "cache_read": 0.24, "cache_write": 3, "unit": "1M_tokens", "currency": "🪙" }
    }
  ]
}

​Rate Limiting

​Anthropic Messages API Format

​Request Body Parameters

​Example Request

​Response Example

​Output Streaming

​OpenAI Protocol (Chat Completions API)

​Request Body Parameters

​Example Request

​Example Response

​Output Streaming

​OpenAI Responses API Format

​Request Body Parameters

​Example Request

​Example Response

​Output Streaming

​Error Codes

​429 Response Headers

​Query Available Models

​Example Request

​Response Example

Rate Limiting

Anthropic Messages API Format

Request Body Parameters

Example Request

Response Example

Output Streaming

OpenAI Protocol (Chat Completions API)

Request Body Parameters

Example Request

Example Response

Output Streaming

OpenAI Responses API Format

Request Body Parameters

Example Request

Example Response

Output Streaming

Error Codes

429 Response Headers

Query Available Models

Example Request

Response Example