EN 登录 开始使用
开发文档

整套 API，
一页就写得完。

一智连天下使用 OpenAI 的请求格式。如果你调用过 OpenAI 兼容接口，下面的内容会非常眼熟——这正是我们想要的效果。

接口地址与鉴权

密钥以 Bearer Token 方式传递。不要放进 URL 查询参数，也不要打包进前端代码。

auth
Base URL   https://api.1ai.cloud/v1
Header     Authorization: Bearer $ONEAI_API_KEY
Header     Content-Type: application/json

对话补全

几乎所有场景都用这个接口。model 可填 模型目录里的任意 id。

POST /v1/chat/completions
curl https://api.1ai.cloud/v1/chat/completions \
  -H "Authorization: Bearer $ONEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "system", "content": "回答请简短。"},
      {"role": "user",   "content": "用一句话打个招呼。"}
    ],
    "temperature": 0.7,
    "stream": false
  }'

流式返回

设置 stream: true 即可接收 SSE 事件流。流以 data: [DONE] 结束，与 OpenAI SDK 的预期完全一致。

stream.py
stream = client.chat.completions.create(
    model="glm-5.2",
    messages=[{"role": "user", "content": "从一数到五。"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

查询可用模型

返回当前密钥可以路由到的全部模型。可以直接当作 CI 里的健康检查。

GET /v1/models
curl https://api.1ai.cloud/v1/models \
  -H "Authorization: Bearer $ONEAI_API_KEY"

降级与故障切换

传入一串有序的备选模型。当主模型返回限流、超时或 5xx 时， 请求会在同一次调用内自动落到下一个。

fallbacks.json
{
  "model": "claude-sonnet-5",
  "fallbacks": ["gpt-5.4", "glm-5.2", "kimi-k3"],
  "messages": [{"role": "user", "content": "..."}]
}

错误码

状态码如何处理
401密钥缺失、格式错误或已吊销。检查 Authorization 头。
402余额不足，请在控制台充值。
404模型 id 不存在。调用 GET /v1/models 查看当前密钥可用的模型。
429上游限流。请退避重试，或声明降级列表让调用自动改道。
5xx上游故障。可安全地退避重试；配置降级列表后平台会替你处理。

实践建议

  • 按环境分别签发密钥。吊销一把泄露的测试密钥，不应该影响到生产流量。
  • 让系统提示词与工具定义在多轮之间保持逐字节一致——这是缓存命中价能生效的前提。
  • 在客户端显式设置超时。多数 SDK 的默认超时都比用户愿意等的时间长得多。
  • 如果可复现性比「自动用上最新版本」更重要，请锁定具体模型 id，而不是使用别名。
需要这里没写到的能力——批量任务、向量嵌入、专属区域，或一次数据处理评估？ ， 我们会给具体答复，而不是一份宣传册。