快速开始
把 SDK 的地址改成 阶跃,请求照你用的协议原样发。
在控制台建一个 API 令牌,按下面任意一种写法带上。
python
from openai import OpenAI
client = OpenAI(
base_url="https://your-site.example/v1",
api_key="sk-…",
)
reply = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello"}],
)流式
shell
curl "https://your-site.example/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse" \
-H "x-goog-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents": [{"role": "user", "parts": [{"text": "Hello"}]}]}'
curl "https://your-site.example/v1beta/models/gemini-2.5-pro:streamGenerateContent?key=$API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents": [{"role": "user", "parts": [{"text": "Hello"}]}]}'- Gemini 的每个路径把 /v1beta 换成 /v1 或 /v1alpha 也能用。
- 部分旧 SDK(Go 的 gax-go/v2、旧版 Python 的 google-api-core)会悄悄丢掉 JSON 数组最后的 {"error": …} 元素。流提前结束时,用 X-Amber-Trace-Id 和 GET /v1/requests/{trace_id} 查这次请求。
网关自己产生的错误,用你调用的那个协议的错误格式;上游厂商返回的错误原样转给你。
在请求头 X-Amber-Trace-Id 里带上你自己的 Trace ID,事后用 GET /v1/requests/{trace_id} 查这次请求的处理结果、用量和金额。
shell
curl https://your-site.example/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "X-Amber-Trace-Id: order-1001" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'
curl https://your-site.example/v1/requests/order-1001 \
-H "Authorization: Bearer $API_KEY"- Trace ID 1–128 个字符,只能是字母、数字和 . _ : -;不合规的请求返回 400 trace_id_invalid。调用模型的 /v1 接口、异步任务的提交和取消都认;Responses 的 WebSocket 在握手时带,连接上的每个 response.create 都用它。
- 带了 Trace ID 的响应原样带回响应头 X-Amber-Trace-Id;没带的用响应头 X-Request-Id 里的请求 ID 查(WebSocket 是握手时的,异步任务是提交时返回的任务 ID)。
- 同一个 Trace ID 可以重复用(例如超时后重试):查询时按开始时间从早到晚全部列出,最多 100 个(最近的)。
- 查询用同一个 API 令牌鉴权,只返回这个账户的请求;Trace ID 逐字匹配,大小写不同就是不同的 Trace ID;先按你的 Trace ID 找,没有一个请求带它时才按请求 ID 或任务 ID 找。返回 {"items": [...]},没有就是空数组。每一项的字段和控制台使用日志的详情一样,另有 trace_id、outcome、timeout、phase。
- 能查多久和控制台的使用日志一样,按你账户的日志保留天数。
- API 令牌无效、余额不足等在门口就被拦下的请求,响应里已经有错误,不保证查得到。
处理结果 outcome
超时说明 timeout
用量和计费字段
- 用量不知道时给 null,不记成 0:处理中的请求、对账补回的记录。
- 用量是 0 就是真的 0。
- 是否计费看 charge:"0" 是没计费,大于 0 是计费了;原因看 billing.charge_reason。
- 上游没有报全用量时,网关按估算收费:照样给数字,usage_source 是 local 或 mixed,charge_reason 是 estimated_usage 或 client_cancelled_precommit。
收费原因 charge_reason
- 每个 API 令牌可以设每分钟请求数上限,在新建或编辑 API 令牌时设。
- 账户可以有每分钟请求数和并发数上限,由运营方设置。
- 超过上限返回 429 rate_limit_exceeded。网关不带 Retry-After:请自己退避后重试。