IBM watsonx.ai 免费 Lite 计划每月 30 万 tokens 领取与调用

watsonx.ai 的调用方式与常见的 OpenAI 风格接口不完全相同，鉴权走 IBM Cloud 的 IAM 令牌，请求地址中包含版本号与区域信息。调用前需要先获取 API key 与项目 ID（Project ID），两者都可以在控制台的服务凭证与项目设置中找到。

获取地址与凭证

API 端点形如 https://<region>.ml.cloud.ibm.com/ml/v1/text/generation?version=2023-05-29，其中区域常见为 us-south 或 eu-de，具体以控制台服务凭证中给出的 URL 为准。调用需要两个关键标识：project_id（在项目设置中复制）与临时访问令牌（由 API key 换取）。

第一步：用 API key 换取 IAM 令牌

令牌有效期有限，过期后需要重新获取。可以先在环境变量中保存 API key，再用下面的命令换取令牌：

export IBM_API_KEY="你的API密钥"
curl -s -X POST "https://iam.cloud.ibm.com/identity/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -d "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
  -d "apikey=${IBM_API_KEY}"

返回结果中的 access_token 字段即为后续请求使用的 Bearer 令牌，expires_in 表示有效期秒数。

第二步：发起一次文本生成调用

把上一步的令牌写入环境变量后，即可调用文本生成接口。下面是最小可运行示例：

export IBM_TOKEN="上一步获取的access_token"
export IBM_PROJECT_ID="你的项目ID"

curl -s -X POST "https://us-south.ml.cloud.ibm.com/ml/v1/text/generation?version=2023-05-29" \
  -H "Authorization: Bearer ${IBM_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "model_id": "ibm/granite-3-8b-instruct",
    "project_id": "'"${IBM_PROJECT_ID}"'",
    "input": "用一句话解释什么是向量数据库",
    "parameters": {
      "max_new_tokens": 200,
      "temperature": 0.7,
      "top_p": 0.9,
      "repetition_penalty": 1.05
    }
  }'

关键参数说明：model_id 指定模型，主推 Granite 系列，例如 ibm/granite-3-8b-instruct；平台也托管 Llama 与 Mistral 系列，具体可用列表请在控制台的模型目录中查看，模型名会随版本更新。 input 是提示文本，纯文本生成接口不带对话角色结构，需要对话格式时请改用聊天接口。 max_new_tokens 控制输出长度，直接影响 token 消耗；temperature 与 top_p 控制随机性；repetition_penalty 用于抑制重复。

第三步：额度耗尽与限流的排查顺序

典型表现有三种：返回 401 表示令牌无效或已过期，重新换取即可；返回 403 多为 API key 权限不足或项目未关联服务实例；返回 429 则多为超出速率限制或当月额度用尽。排查建议按以下顺序进行。

• 先确认令牌是否过期，令牌有效期较短，长时间运行的服务需要做自动刷新。
• 再确认 project_id 与 API 端点所属区域是否匹配，跨区域调用会直接失败。
• 然后到控制台的用量页面核对本月已消耗 tokens 与剩余额度，确认是否触及 Lite 计划上限，具体数值以控制台实际显示为准。
• 若额度已用尽，通常需要等到下个月额度刷新，或升级到付费计划；不要依赖额度结转。
• 最后检查单次请求的 max_new_tokens 是否设置过大，长输出会显著加快额度消耗。

生产环境建议把令牌获取、重试与用量记录封装在服务端，避免在浏览器等前端环境中暴露 API key。