1. Overview
Jizhi API provides developers with Anthropic Messages API (/v1/messages) compatible proxy access. Simply send your requests to our gateway and replace your authentication key with the sk- key created in the "User Center - API Keys" to use Claude models directly without modifying your existing code.
The currently available models are subject to the Model Square (e.g., claude-sonnet-5, claude-opus-5, claude-sonnet-4-6, claude-opus-4-8, etc.). A complete list and unit prices can be queried at any time via GET /v1/models.
2. API Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /v1/messages | Proxy forwarding entry; request body follows Anthropic /v1/messages payload |
| GET | /v1/models | Model and unit price list (no authentication required) |
Gateway URL: https://www.relay-api.com. Please fill in the request path exactly as shown in the table above.
3. Authentication
Create a key in "User Center → API Keys" in the format sk-xxxxxxxx. Include it in your calls using either of the following methods:
- Authorization header:
Authorization: Bearer sk-your-key(Recommended, compatible with most SDKs) - x-api-key header:
x-api-key: sk-your-key
Invalid, disabled, or insufficient balance keys will return 401 / 403; please verify your key status and account balance.
4. Quick Start (curl)
4.1 Non-streaming Chat
curl -X POST https://www.relay-api.com/v1/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-your-key" \
-d '{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Introduce yourself in one sentence"}
]
}'4.2 System Prompts and Multi-turn Conversation
curl -X POST https://www.relay-api.com/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: sk-your-key" \
-d '{
"model": "claude-opus-5",
"max_tokens": 2048,
"system": "You are a rigorous technical documentation engineer.",
"messages": [
{"role": "user", "content": "What is the authentication header for the Claude Messages API?"},
{"role": "assistant", "content": "Use x-api-key or Authorization: Bearer to carry your key."},
{"role": "user", "content": "Give me another example of a streaming request."}
],
"metadata": {"request_id": "demo-001"}
}'metadata.request_id will be written to usage logs, making it easy to reconcile accounts in "User Center → Usage Details".
5. Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Model slug, e.g., claude-sonnet-5 |
| max_tokens | int | Yes | Maximum output tokens, recommended 1~64000 |
| messages | array | Yes | Conversation messages, elements are {role, content}, role options: user / assistant |
| system | string | No | System prompt |
| temperature | number | No | Sampling temperature, default 1.0, range 0~1 |
| top_p | number | No | Nucleus sampling, default 0.999 |
| stream | bool | No | Whether to return streaming response, default false |
| stop_sequences | array | No | Stop sequences |
| metadata.request_id | string | No | Custom request ID for reconciliation |
6. Response Structure
Non-streaming requests return the standard Anthropic Messages structure:
{
"id": "msg_01ABCDEFG",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-5",
"content": [
{"type": "text", "text": "Hello! I am Claude."}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 12,
"output_tokens": 18,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0
}
}| Field | Description |
|---|---|
| id | Unique message ID |
| content[].type | Content block type, text / thinking, etc. |
| content[].text | Text content |
| stop_reason | Stop reason: end_turn / max_tokens / stop_sequence |
| usage.input_tokens | Input token count (basis for billing) |
| usage.output_tokens | Output token count (basis for billing) |
| usage.cache_read_input_tokens | Cache hit input tokens (charged at cache read rate) |
| usage.cache_creation_input_tokens | Tokens written to cache (charged at cache write rate) |
7. Streaming Output
When "stream": true is added to the request body, the server returns responses in blocks via SSE (Server-Sent Events). The event types are identical to Anthropic:
event: message_start
data: {"type": "message_start", "message": {"id": "msg_...", "model": "claude-sonnet-5"}}
event: content_block_delta
data: {"type": "content_block_delta", "delta": {"type": "text_delta", "text": "Hello"}}
event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn"}, "usage": {"output_tokens": 18}}
event: message_stop
data: {"type": "message_stop"}The client should parse JSON based on the data: line, ignoring event: and blank lines. Receiving message_stop indicates the stream has ended. Billing is settled on the server side based on the total usage of the request, independent of the streaming process.
8. Common Error Codes
| HTTP Status | Meaning | Recommended Action |
|---|---|---|
| 400 | Invalid request parameters (missing model/max_tokens, model not enabled, etc.) | Correct the request body based on the error message |
| 401 | Missing or invalid API key | Check Authorization / x-api-key header |
| 403 | Key disabled, insufficient balance, or unauthorized for this model/route | Top up, check key status, or adjust permissions |
| 404 | Requested model does not exist | Check available models via GET /v1/models |
| 429 | Too many requests or rate limit triggered | Retry with exponential backoff |
| 500 | Internal server error | Retry later; contact support if persistent |
Error response bodies are standardized to {"code": status_code, "message": "error description", "data": null} structure.
9. Usage and Balance
- Each call is billed in real-time based on token usage × model unit price × route multiplier. See
GET /v1/modelsfor prices and routes. - View call records (model, tokens, cost, status) in "User Center → API Usage" after logging in.
- If your balance is insufficient, the call will return 403; service will resume immediately after a top-up.
Base URL Note: This site accepts both /v1beta/models/... and /v1beta/v1beta/models/... (as well as /v1/... and /v1/v1/...). Whether the client appends /v1 or /v1beta does not affect the call; you can use the domain root or the address with /v1beta as the Base URL. Please find and copy the Model ID from the top right corner of the "Tokens" page in the console.