AI21 API 调用实操：密钥申请与 Python 请求示例
AI21 API 的调用流程并不复杂：先在 AI21 Studio 创建 API Key，然后用 HTTP 请求或官方 SDK 向 https://api.ai21.com/studio/v1/ 下的端点发送 JSON 数据，请求头带上 Authorization: Bearer <你的API Key> 即可。
下面按零基础也能跟着做的顺序，把准备、调用、排错和验证一次讲清。
申请密钥与确认调用前提
开始前需要准备两样东西：一个可登录的 AI21 Studio 账号，以及一个已启用的 API Key。
- 访问 AI21 Studio 官网并登录账号（如果没有账号需先注册）。
- 在控制台左侧菜单找到 API Key 或 API Keys 页面。
- 点击 Create API Key，为密钥起一个便于识别的名称，例如
my-first-key。 - 创建后立即复制密钥并保存到安全位置，页面关闭后通常无法再次完整查看。
密钥不要直接写进代码提交到 Git 仓库。
建议用环境变量管理：
export AI21_API_KEY="你的API Key"Windows 命令提示符可用 set AI21_API_KEY=你的API Key，
PowerShell 用 $env:。
AI21_API_KEY="你的API Key"
用 Python 发起第一次请求
AI21 提供 REST 接口，用 requests 库就能调用。
先安装依赖：
pip install requests下面是一个调用文本补全端点的最小示例（端点路径和模型名请以 AI21 Studio 文档当前展示为准）：
import os
import requests
api_key = os.environ["AI21_API_KEY"]
url = "https://api.ai21.com/studio/v1/j2-ultra/complete"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
payload = {
"prompt": "用一句话解释什么是 API：",
"maxTokens": 50,
"temperature": 0.7
}
resp = requests.post(url, headers=headers, json=payload, timeout=30)
print(resp.status_code)
print(resp.json())把脚本保存为 ai21_test.py，运行 python ai21_test.py。
如果返回状态码 200 且响应 JSON 中包含生成的文本字段，说明密钥和网络都正常。
调用时注意三点：
- 请求头必须带
Authorization，格式是Bearer加一个空格再加密钥。 Content-Type设为application/json，否则服务端可能无法解析请求体。- 模型名要准确，不同模型对应不同端点，写错模型名会返回 404 或参数错误。
常见报错怎么排查
调用失败时先看 HTTP 状态码，再对照响应体里的 detail 字段。
以下是几个高频问题：
401 Unauthorized：密钥无效或格式不对。
检查环境变量是否真的被读取，可以在脚本里临时打印 api_key[:6] 确认前缀，但不要打印完整密钥。
也确认请求头里 Bearer 后面有空格。
404 Not Found：端点路径或模型名拼写错误。
对照 AI21 Studio 文档检查 URL 中的模型名，注意大小写和连字符。
429 Too Many Requests：触发速率限制。
降低请求频率，或在代码中加入指数退避重试，例如首次等待 2 秒，之后每次翻倍。
超时或连接失败：先确认服务器能访问外网，用 curl -I https://api.ai21.com 测试连通性。
如果服务器在国内，检查 DNS 和出口网络是否正常。
验证调用是否真正生效
不要只看脚本没报错就认为成功。
建议做一次可复现的验证：
- 在脚本中打印
resp.status_code和resp.json()的键名。 - 换一个不同的
prompt再运行一次，确认返回内容随输入变化。 - 故意把密钥改错一位，确认返回
401，以此证明鉴权逻辑确实在起作用。
如果以上三步都符合预期，说明 AI21 API 的密钥配置和请求链路已经跑通。
后续接入业务系统时，把密钥放到服务端环境变量或密钥管理服务中，不要暴露在前端代码里。
实际使用中的几个避坑点
- 不要把密钥硬编码在代码里，尤其是会提交到公开仓库的项目。
- 控制单次请求的
maxTokens，生成内容越长消耗越多，调试阶段先用小值。 - 给请求设置超时，避免网络异常时脚本长时间挂起。
- 区分免费额度和计费额度，AI21 Studio 的配额和计费规则可能变化，调用前在控制台确认当前用量。
- 保留错误日志，记录状态码和响应体，方便后续排查是密钥问题、参数问题还是网络问题。
按上面的步骤完成密钥创建、Python 请求和报错对照，就能把 AI21 API 接入到自己的脚本或服务里。
遇到异常时，优先检查鉴权头和端点路径这两处，大部分调用失败都出在这里。
