AI21 Labs 免费 API 注册领取一次性赠额，OpenAI 格式兼容接入

AI21 Studio 提供 OpenAI 兼容的对话补全接口，因此可以直接复用 OpenAI SDK，只需替换 base_url、API Key 与模型名。

一、base_url 与模型名

兼容接口的 base_url 形如 https://api.ai21.com/studio/v1，对话补全的完整路径为 /chat/completions。可用模型名（例如 jamba-large-1.7、jamba-mini-1.7 等）会随平台更新而变化，请以官网文档的模型列表或控制台中的模型下拉框为准，不要照抄过期型号。

二、用 curl 发起一次对话补全

先把 API Key 放进环境变量，避免明文出现在命令历史里：

export AI21_API_KEY="你的 AI21 API Key"

然后发送请求，关键参数说明：model 指定模型名；messages 为对话数组，role 取 system / user / assistant，content 为文本；max_tokens 控制回复长度上限；temperature 与 top_p 控制随机性；stream 设为 true 可流式返回。

curl https://api.ai21.com/studio/v1/chat/completions \
  -H "Authorization: Bearer $AI21_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"jamba-large-1.7","messages":[{"role":"user","content":"你好，用一句话介绍你自己"}],"max_tokens":256,"temperature":0.7,"stream":false}'

三、用 OpenAI SDK 调用

安装 openai 后，把 base_url 指向 AI21 的兼容地址即可，其余写法与调用 OpenAI 一致：

from openai import OpenAI

client = OpenAI(
    api_key="你的 AI21 API Key",
    base_url="https://api.ai21.com/studio/v1",
)

resp = client.chat.completions.create(
    model="jamba-large-1.7",
    messages=[{"role": "user", "content": "你好，用一句话介绍你自己"}],
    max_tokens=256,
    temperature=0.7,
)

print(resp.choices[0].message.content)

四、额度耗尽与限流的典型表现

• 401 / 403：Key 无效、被删除或复制时带了多余空格，检查请求头是否为 Authorization: Bearer 你的Key。
• 402 或余额不足类提示：一次性赠送额度已用尽，需要到控制台充值后才能继续调用。
• 429：请求过于频繁触发限流，或额度耗尽后的统一返回，先看响应体里的错误信息再判断。
• 404 / 模型不存在：模型名写错或已下线，也可能是 base_url 多写或少写了 /v1。

排查顺序建议：先确认环境变量里的 Key 是否正确 → 核对 base_url 与完整请求路径 → 用最小请求体（只留 model 和一条 messages）重试 → 到控制台查看剩余额度与用量曲线 → 确认是否触发频率限制后加重试与退避。