API 说明API reference

简介Introduction

以太把多家上游收成一个地址。OpenAI SDK 把 base_url 设为 https://api.ytai.site/v1。Anthropic SDK 把 base_url 设为 https://api.ytai.site，它会自己接上 /v1/messages。Æther puts many upstreams behind one address. Set an OpenAI SDK base_url to https://api.ytai.site/v1. Set an Anthropic SDK base_url to https://api.ytai.site; the SDK appends /v1/messages itself.

聊天接口与常见 OpenAI、Anthropic 客户端兼容。流式响应用标准 SSE。网关先按估算预扣额度，结束后按实际用量结算；上游失败会退回这次预扣。Chat routes match common OpenAI and Anthropic clients. Streaming is standard SSE. The gateway pre-charges an estimate, then settles on actual usage. If the upstream call fails, that pre-charge is returned.

每条响应都带 X-Oneapi-Request-Id。出错时，message 末尾也会写上同一个 request id。Every response carries X-Oneapi-Request-Id. On errors, the same request id is appended to message.

curl https://api.ytai.site/v1/chat/completions \
  -H "Authorization: Bearer $AETHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",
    base_url="https://api.ytai.site/v1",
)

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-...",
    base_url="https://api.ytai.site",
)

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)

鉴权Authentication

在控制台创建密钥。完整密钥只在创建时显示一次，请当时复制。之后请求带上它，不要改前缀。Create a key in the console. The full key is shown only once, so copy it then. Send that value unchanged.

多数接口使用 Authorization: Bearer。/v1/messages 和 /v1/models 也接受 x-api-key。Gemini 路径 /v1beta 接受 x-goog-api-key，或查询参数 key。Most routes take Authorization: Bearer. /v1/messages and /v1/models also accept x-api-key. Gemini routes under /v1beta accept x-goog-api-key, or the key query parameter.

每把密钥可以单独限制模型、剩余额度、IP 和过期时间。限制以控制台里这把密钥的设置为准。Each key can limit models, remaining quota, IP, and expiry. Those limits are whatever you set on that key in the console.

# 下面任意一种即可# Any one of these works
Authorization: Bearer sk-...
x-api-key: sk-...          # /v1/messages、/v1/models
x-goog-api-key: sk-...     # /v1beta

{
  "error": {
    "message": "无效的令牌 (request id: …)Invalid token (request id: …)",
    "type": "new_api_error",
    "code": ""
  }
}

错误与限额Errors and limits

失败时 HTTP 状态码和 JSON 一起看。type 固定为 new_api_error，code 标原因，message 给人读，并带 request id。Read the HTTP status together with the JSON. type is always new_api_error. code names the cause. message is for people, and it includes the request id.

状态Status

{
  "error": {
    "message": "用户额度不足 (request id: …)Insufficient quota (request id: …)",
    "type": "new_api_error",
    "code": "insufficient_user_quota"
  }
}

对话补全Chat completions

最常用的 OpenAI 兼容入口。兼容旧客户端时也可以打 POST /v1/completions。设 stream: true 时，内容按 SSE 分块返回，用量在结束前的 usage 块里。The OpenAI-compatible route most clients use. Older clients can call POST /v1/completions. With stream: true, content arrives as SSE chunks, and usage is in the chunk before the stream ends.

参数Parameters

curl https://api.ytai.site/v1/chat/completions \
  -H "Authorization: Bearer $AETHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": false
  }'

client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "choices": [{
    "message": { "role": "assistant", "content": "Hello." }
  }],
  "usage": { "prompt_tokens": 8, "completion_tokens": 2 }
}

Messages

Anthropic Messages 形态。密钥放在 Authorization 或 x-api-key 都可以。官方 SDK 会额外带上 anthropic-version，原样转发即可。Anthropic Messages shape. The key may be Authorization or x-api-key. Official SDKs also send anthropic-version; forward it as-is.

参数Parameters

curl https://api.ytai.site/v1/messages \
  -H "x-api-key: $AETHER_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

client = Anthropic(
    api_key="sk-...",
    base_url="https://api.ytai.site",
)

Responses

OpenAI Responses 形态。需要压缩上下文时走 POST /v1/responses/compact，请求体与对应官方接口一致。OpenAI Responses shape. To compact context, call POST /v1/responses/compact with the body the official API expects.

参数Parameters

curl https://api.ytai.site/v1/responses \
  -H "Authorization: Bearer $AETHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "input": "Hello"
  }'

模型列表Models

返回这把密钥当前能调用的模型。带 x-api-key 且同时带 anthropic-version 时，列表按 Anthropic 的形态返回。单个模型是 GET /v1/models/{model}。Lists the models this key can call. When the request sends both x-api-key and anthropic-version, the list uses the Anthropic shape. One model is GET /v1/models/{model}.

Gemini 原生路径不在 /v1 下面，地址是 https://api.ytai.site/v1beta/models/{model}:generateContent，密钥用 x-goog-api-key 或 ?key=。The native Gemini path is not under /v1. It is https://api.ytai.site/v1beta/models/{model}:generateContent, with the key in x-goog-api-key or ?key=.

curl https://api.ytai.site/v1/models \
  -H "Authorization: Bearer $AETHER_API_KEY"

curl https://api.ytai.site/v1beta/models/gemini-2.5-flash:generateContent \
  -H "x-goog-api-key: $AETHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Hello"}]}]
  }'