> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API 文档

> Syon API 接入指南：OpenAI / Anthropic / Gemini 兼容协议

Syon supports multiple compatible API formats, including **OpenAI**, **Google Gemini**, and **Anthropic**. Point the official SDK base URL to Syon and keep your application code unchanged. You can call Claude / Gemini / GPT and other model families through one gateway.

* **Base URL**: `https://api.syon.com`
* **Authentication**: API Key (`sk-...`)
* **Protocols**: Anthropic native format (`/v1/messages`), OpenAI-compatible format (`/v1/chat/completions`), OpenAI Responses API (`/v1/responses`, GPT models only), Gemini native format (`/v1beta/models/{model}:generateContent`), and image generation (`/v1/images`)

Replace `sk-xxxxxx` with your own key. Keep the key private and never commit it to a code repository.

***

## 1. Authentication

Choose the compatible format according to the model you use:

Different formats use different authentication headers. Choose the header according to the protocol:

| Protocol  | Header                                                   |
| --------- | -------------------------------------------------------- |
| Anthropic | `x-api-key: sk-xxxxxx` + `anthropic-version: 2023-06-01` |
| OpenAI    | `Authorization: Bearer sk-xxxxxx`                        |
| Gemini    | `Authorization: Bearer sk-xxxxxx`                        |

***

## 2. Available models

Fetch the complete model list in real time with `GET /v1/models`:

bash

```
curl https://api.syon.com/v1/models \
  -H "Authorization: Bearer sk-xxxxxx"
```

Currently available models (examples):

| Provider  | Model ID                                                                                                                                                                   |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Anthropic | `claude-fable-5-1`, `claude-opus-5`, `claude-fable-5`, `claude-sonnet-5`, `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5` |
| OpenAI    | `gpt-6-astra`,`gpt-5.6-sol`,`gpt-5.6-terra`,`gpt-5.6-luna`,`gpt-5.5`,`gpt-5.4`,`gpt-5.4-mini`,`gpt-image-2`                                                                |
| Google    | `gemini-3.8-flash`, `gemini-3.7-flash`, `gemini-3.6-flash`, `gemini-3.5-flash-lite`,`gemini-3.1-pro-preview`, `gemini-3.5-flash`, `gemini-3.1-flash-lite-preview`          |
| Kimi      | `kimi-k3`                                                                                                                                                                  |
| DeepSeek  | `deepseek-flash` (DeepSeek V4.1 Flash), `deepseek-v4-flash-vision-exp`, `deepseek-v4-pro`, `deepseek-v4-flash`                                                             |
| GLM       | `glm-5.3-flash`, `glm-5.3`, `glm-5.2`                                                                                                                                      |
| Grok      | `grok-4.6`                                                                                                                                                                 |

***

## 3. Anthropic native format

Endpoint: `POST /v1/messages`

### 3.1 Basic request

bash

```
curl https://api.syon.com/v1/messages \
  -H "x-api-key: sk-xxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Introduce yourself in one sentence"}
    ]
  }'
```

Example response:

json

```
{
  "id": "msg_01KxDE...",
  "type": "message",
  "role": "assistant",
  "model": "claude-fable-5-1",
  "content": [{"type": "text", "text": "I am Claude..."}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 159, "output_tokens": 34}
}
```

### 3.2 Streaming with SSE

Add `"stream": true`. The response is `text/event-stream`:

bash

```
curl https://api.syon.com/v1/messages \
  -H "x-api-key: sk-xxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "Write a short poem"}]
  }'
```

Event sequence: `message_start` ->`content_block_start` -> multiple `content_block_delta` events ->`content_block_stop` ->`message_delta` ->`message_stop`.

### 3.3 Python SDK with `anthropic`

python

```
from anthropic import Anthropic

client = Anthropic(
    api_key="sk-xxxxxx",
    base_url="https://api.syon.com",
)

resp = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.content[0].text)
```

***

## 4. OpenAI-compatible format

Endpoints: `POST /v1/chat/completions` (Chat Completions) and `POST /v1/responses` (Responses API, GPT models only)

### 4.1 Basic Chat Completions request

bash

```
curl https://api.syon.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

The response follows the standard OpenAI `chat.completion` structure:

json

```
{
  "object": "chat.completion",
  "model": "gpt-5.6-sol",
  "choices": [
    {"index": 0, "message": {"role": "assistant", "content": "Hello!"}, "finish_reason": "stop"}
  ],
  "usage": {"prompt_tokens": 214, "completion_tokens": 3, "total_tokens": 217}
}
```

### 4.2 Python SDK with `openai`

python

```
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxx",
    base_url="https://api.syon.com/v1",
)

resp = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)
```

### 4.3 Streaming

Add `"stream": true`. Syon returns standard OpenAI SSE chunks in the `data: {...}` format and ends with `data: [DONE]`.

### 4.4 Basic Responses API request

If your application already uses the OpenAI Responses API, call `/v1/responses` directly:

bash

```
curl https://api.syon.com/v1/responses \
  -H "Authorization: Bearer sk-xxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Introduce Syon in one sentence"
  }'
```

`/v1/responses` only supports GPT models. Requests for Claude / Gemini return 400. Use `/v1/messages` for Claude and the Gemini native format for Gemini.

### 4.5 Python SDK with `openai` Responses

python

```
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxx",
    base_url="https://api.syon.com/v1",
)

resp = client.responses.create(
    model="gpt-5.6-sol",
    input="Introduce Syon in one sentence",
)
print(resp.output_text)
```

### 4.6 Responses API streaming

Add `"stream": true` to receive standard OpenAI Responses API streaming events.

### 4.7 Fast mode

Syon's OpenAI-compatible endpoints support Fast mode (formerly Priority processing). Add this to your Chat Completions or Responses API request:

json

```
"service_tier": "fast"
```

Python example:

python

```
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxx",
    base_url="https://api.syon.com/v1",
)

resp = client.responses.create(
    model="gpt-5.6-sol",
    input="Analyze this requirement for me",
    service_tier="fast",
)
print(resp.output_text)
```

JavaScript example:

javascript

```
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-xxxxxx",
  baseURL: "https://api.syon.com/v1",
});

const resp = await client.responses.create({
  model: "gpt-5.6-sol",
  input: "Analyze this requirement for me",
  service_tier: "fast",
});
console.log(resp.output_text);
```

The legacy value still works:

json

```
"service_tier": "priority"
```

`fast` is the current recommended value; the legacy value `priority` still works and behaves identically. Both apply to all GPT-series models that support Fast mode. With Fast mode enabled, `gpt-5.6-sol` runs up to 2.5x faster than Standard. Fast mode is billed at 2x the standard rate. For GPT-5.6 and earlier models, the `service_tier` field in the response object may still return `"priority"` — this is expected.

***

## 5. Gemini native format

Endpoint: `POST /v1beta/models/{model}:generateContent`

### 5.1 Basic request

bash

```
curl https://api.syon.com/v1beta/models/gemini-3.5-flash:generateContent \
  -H "Authorization: Bearer sk-xxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Introduce yourself in one sentence"}]}
    ]
  }'
```

Example response:

json

```
{
  "candidates": [
    {
      "content": {"role": "model", "parts": [{"text": "I am Gemini..."}]},
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {"promptTokenCount": 12, "candidatesTokenCount": 22, "totalTokenCount": 34}
}
```

### 5.2 Streaming with SSE

Use `streamGenerateContent` and add `alt=sse`:

bash

```
curl "https://api.syon.com/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Write a short poem"}]}
    ]
  }'
```

### 5.3 Environment variables

If your tool or SDK supports a custom Gemini Base URL, configure it like this:

bash

```
export GOOGLE_GEMINI_BASE_URL="https://api.syon.com"
export GEMINI_API_KEY="sk-xxxxxx"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"
```

Different Gemini SDKs may use different field names for custom endpoints. Common names include `base_url`, `baseURL`, `apiEndpoint`, or environment variables. The core rule is: point the Base URL to `https://api.syon.com` and use your Syon API Key.

***

## 6. Image generation (GPT Image 2)

The image model `gpt-image-2` uses the separate `/v1/images` endpoints and authenticates with `Authorization: Bearer`.

### 6.1 Generate images

Endpoint: `POST /v1/images/generations`

bash

```
curl https://api.syon.com/v1/images/generations \
  -H "Authorization: Bearer sk-xxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "An orange cat typing on a keyboard, illustration style"
  }'
```

Example response. `data[0].b64_json` is the Base64-encoded image:

json

```
{
  "created": 1752345600,
  "data": [
    {"b64_json": "iVBORw0KGgo..."}
  ]
}
```

Set the timeout to 300 seconds. Image generation models can take longer to respond, and shorter timeouts may fail.

### 6.2 Edit images

Endpoint: `POST /v1/images/edits`

Upload the source image as `multipart/form-data` and provide an edit instruction:

bash

```
curl https://api.syon.com/v1/images/edits \
  -H "Authorization: Bearer sk-xxxxxx" \
  -F model="gpt-image-2" \
  -F image="@photo.png" \
  -F prompt="Replace the background with a starry sky"
```

This endpoint is compatible with the OpenAI Images API.

***

## 7. Connect agent tools

Claude Code uses the Anthropic protocol, Codex uses the OpenAI protocol, and Gemini CLI uses the Gemini protocol.

Just point the Base URL and API Key environment variables to Syon. You do not need to modify the tools themselves.

**Claude Code (Anthropic protocol):**

bash

```
export ANTHROPIC_BASE_URL="https://api.syon.com"
export ANTHROPIC_API_KEY="sk-xxxxxx"
```

**OpenAI protocol tools (Chat Completions / Responses API):**

bash

```
export OPENAI_BASE_URL="https://api.syon.com/v1"
export OPENAI_API_KEY="sk-xxxxxx"
```

**Gemini CLI:**

bash

```
export GOOGLE_GEMINI_BASE_URL="https://api.syon.com"
export GEMINI_API_KEY="sk-xxxxxx"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"
```

***

## 8. FAQ

**Getting 401 / authentication failed?**

First verify the protocol-to-header mapping: Anthropic uses `x-api-key`; OpenAI / Gemini use `Authorization: Bearer`; Gemini native endpoints also accept `x-goog-api-key`. Then confirm the key is complete, starts with `sk-`, has no extra spaces, and has not been deleted in the dashboard. Also check the `base_url` format: OpenAI SDKs need `/v1`; Anthropic SDKs do not.

**Calling Claude through the OpenAI format returns errors, costs more, or performs worse?**

**Use the Anthropic native protocol (`/v1/messages`) for Claude models whenever possible.** Claude Code and other agent tools must be configured with the Anthropic protocol. Calling Claude through the OpenAI-compatible format can lose prompt cache, thinking, and other capabilities, increasing cost and reducing quality. It is only suitable for simple chat scenarios. `/v1/responses` does not support Claude / Gemini and returns 400.

**Model unavailable?**

Use `GET /v1/models` to fetch the real-time model list first. Check the model ID spelling, use lowercase, and pay attention to `-` versus `.`. Also confirm the endpoint matches the model.

**Timeout or slow first token?**

Large models such as Opus / Fable can take several seconds to tens of seconds for the first token during reasoning. This does not mean the request failed. In production, set `"stream": true` for better perceived latency and increase the client read timeout. The server supports responses up to 600 seconds.

**Key security:**

Store keys in environment variables or a secret manager. Do not hardcode them, commit them to Git, or bundle them into a frontend / public client. If you suspect a key has leaked, delete it in the dashboard immediately and create a replacement.