Amber
模型文档联系我们
登录免费注册
Amber
模型文档联系我们用户协议隐私政策

运营主体:(待配置)。服务或账户问题请联系 (待配置)。

© 阶跃

本页目录接口地址鉴权示例Gemini错误码按 Trace ID 查询限速

快速开始

接口地址

把 SDK 的地址改成 阶跃,请求照你用的协议原样发。

协议地址路径
OpenAIhttps://your-site.example/v1/chat/completions/responses
OpenAI(Google 路径)https://your-site.example/v1beta/openai/chat/completions/images/generations/models
Anthropichttps://your-site.example/v1/messages
Geminihttps://your-site.example/v1beta/models/{model}:generateContent/v1beta/models/{model}:streamGenerateContent/v1beta/models/{model}:streamGenerateContent?alt=sse

鉴权

在控制台建一个 API 令牌,按下面任意一种写法带上。

写法谁用它
Authorization: Bearer <API_KEY>OpenAI SDK、curl
x-api-key: <API_KEY>Anthropic SDK
x-goog-api-key: <API_KEY>Gemini SDK
?key=<API_KEY>Gemini,放在查询参数里

示例

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"}],
)

Gemini

流式

请求Content-Type用法
POST /v1beta/models/{model}:streamGenerateContent?alt=ssetext/event-stream推荐。每一块是一个 data: 事件;新版 google-genai、@google/genai 默认用它。
POST /v1beta/models/{model}:streamGenerateContentapplication/json兼容。每一块是一个 JSON 数组的元素,写 alt=json、$alt=json 也是这种;旧版 google-generativeai(transport="rest")、Go SDK、Vertex AI 的 curl 脚本用它。
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} 查这次请求。

错误码

网关自己产生的错误,用你调用的那个协议的错误格式;上游厂商返回的错误原样转给你。

码HTTP怎么办
invalid_request400改请求体或参数;param 指出是哪个字段。
unsupported_feature400这个模型或线路不支持请求里的某项功能。去掉它,或换一个模型。
invalid_api_key401检查 API 令牌:可能写错、停用、吊销或过期了。
insufficient_balance402充值,或调高这个 API 令牌的额度。
forbidden403API 令牌的分组或模型白名单不含这个模型,或者请求的 IP 不在白名单里。
model_not_found404到「模型」里核对模型名。
request_too_large413把请求改小。
rate_limit_exceeded429这个 API 令牌、账户或地址的请求太多。放慢,按退避重试。
upstream_saturated429这个模型的上游渠道都满了。稍后再试。
no_available_channel503现在没有渠道能提供这个模型。稍后再试,或换一个分组。
upstream_error502上游重试之后仍然失败;状态码是上游的(连不上时是 502)。重新发一次请求。
upstream_timeout504上游没有及时开始回应。重试,或把请求改小。
service_unavailable503服务暂时不可用。稍后再试。
internal_error500重试;一直出现就联系我们。

按 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

取值含义
in_progress还没结束。phase 是 admitted(在选渠道,或在等上游的第一个输出)或 streaming(在输出);用量和金额是 null。
succeeded正常结束。
failed上游报错,或网关出错;error_code 是错误码。
rejected没有发给上游就拒绝了,例如限流、过载、请求写错了。
caller_disconnected调用方先断开了连接(网关分不出是调用方超时还是主动取消),或长时间不读取响应;异步任务被取消也是这个。
server_timeout网关的时限到了;timeout 写明是哪一个时限、多少秒。
upstream_disconnected上游连接中途断了。
null对账补回的记录(结算还在、日志丢失后补的):处理结果和用量不知道,金额照结算。

超时说明 timeout

取值含义
connect连接上游超时。
first_event流式:发出请求后,等第一个输出超时。
stream_idle流式:开始输出后,连续没有数据超时。
body_idle非流式:等上游响应时,连续没有数据超时。
task_deadline异步任务:提交后 24 小时没有结果。

用量和计费字段

字段含义
in_tokens输入 token,不含缓存读和缓存写。输入合计 = in_tokens + cache_read + cache_write。
cache_read从缓存读取的输入 token。
cache_write写入缓存的输入 token,各档合计(下面三行)。
usage.cache_write_5m, usage.cache_write_1hAnthropic 的两档缓存写:5 分钟、1 小时。
usage.extra.cache_write_30m_tokens, usage.extra.cache_write_12h_tokensOpenAI 的两档缓存写:30 分钟、12 小时。
usage.extra.cache_write_other_tokens上游没有说明档位的缓存写。
out_tokens输出 token,不含推理。
reasoning推理(思考)token,单独计算,不含在 out_tokens 里。
images_in, images_out, audio_in_ms, characters图像接口的输入、生成张数,输入音频的毫秒数,语音合成的字符数;不是这类请求时是 0。
usage.extra各厂商特有的计费项(例如联网搜索的次数),名字和价格里的变量一样。
usage_source用量来自哪里:upstream 是上游报的,local 是网关估算的,mixed 是两者都有。
charge实扣金额,十进制字符串。"0" 表示没有计费,大于 0 表示计费了。
billing.charge_reason为什么这样收费,见下表。
  • 用量不知道时给 null,不记成 0:处理中的请求、对账补回的记录。
  • 用量是 0 就是真的 0。
  • 是否计费看 charge:"0" 是没计费,大于 0 是计费了;原因看 billing.charge_reason。
  • 上游没有报全用量时,网关按估算收费:照样给数字,usage_source 是 local 或 mixed,charge_reason 是 estimated_usage 或 client_cancelled_precommit。

收费原因 charge_reason

取值含义
upstream_usage按上游报的用量收费。
estimated_usage上游没有报全用量,缺的部分按网关的估算收费。
recomputed_usage上游报的用量不可信(全是 0,或输入是 0),网关重新计算后收费。
corrected_usage流式累计的用量最后变小了,按修正后的用量收费。
request_metered按请求计量收费(例如语音合成按字符)。
client_cancelled_precommit调用方在第一个输出之前断开:只收输入(估算)。
client_gone_drained调用方断开后,网关把上游读到了结束,按上游的用量收费。
upstream_moderation_fee上游的审核拦下了请求(xAI)、上游照收违规费:按违规费收一笔(并进标价再乘倍率),上游的错误原样交给调用方,没有用量。
no_usage_pending_estimate上游没有报用量,正在估算;结算后换成 estimated_usage。
not_charged_precommit_failure没有收费:输出之前就失败了。
gateway_rejected没有收费:被网关拒绝。
not_charged_cancelled没有收费:调用方在上游回应之前断开了。
check_truncated没有收费:上游的输出没有通过检查,交付已停止。
unfinished_no_content_waived没有收费:流式响应没有任何有效内容,也没有正常结束就中断了。
quote_failed计费在核对中。
settlement_failed计费在核对中。
recovered对账补回的记录:金额照结算,用量不知道。
""(空串)异步任务:按任务结算,金额见 /v1/tasks/{id}。

限速

  • 每个 API 令牌可以设每分钟请求数上限,在新建或编辑 API 令牌时设。
  • 账户可以有每分钟请求数和并发数上限,由运营方设置。
  • 超过上限返回 429 rate_limit_exceeded。网关不带 Retry-After:请自己退避后重试。