Clarifai 平台注册免费领取一次性 5 美元额度，可调多模态模型

接入方式与调用要点

Clarifai 提供 OpenAI 兼容的接口，base_url 形态为 https://api.clarifai.com/v2/ext/openai/v1，因此可以直接用 OpenAI SDK 或任意兼容客户端调用，只需把地址和密钥换掉。模型名（如 gpt-oss-120b、Claude 系列、Llama 系列以及各类视觉与 embeddings 模型）以控制台模型详情页里 Use Model 标签给出的调用示例为准，不同模型的命名前缀可能不同。

先把密钥和地址写进环境变量，避免硬编码到代码里：

export CLARIFAI_API_KEY="你的 API Key"
export CLARIFAI_BASE_URL="https://api.clarifai.com/v2/ext/openai/v1"

用 curl 发一次最小的对话补全请求，先确认链路是否通：

curl "$CLARIFAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $CLARIFAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-oss-120b",
    "messages": [
      {"role": "user", "content": "用一句话解释什么是向量检索"}
    ],
    "max_tokens": 256,
    "temperature": 0.7
  }'

关键参数说明：model 必填，写控制台里的模型标识；messages 是对话数组，元素包含 role（user、assistant、system）与 content；max_tokens 控制单次输出上限，试用期建议设小一些以节省额度；temperature 控制随机性，取值 0 到 2；需要流式输出时加 "stream": true，返回会变成逐块的 data 事件。

同样的请求用 Python SDK 写法如下：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CLARIFAI_API_KEY"],
    base_url=os.environ["CLARIFAI_BASE_URL"],
)

resp = client.chat.completions.create(
    model="gpt-oss-120b",
    messages=[{"role": "user", "content": "用一句话解释什么是向量检索"}],
    max_tokens=256,
    temperature=0.7,
)
print(resp.choices[0].message.content)

额度耗尽与限流的排查顺序

• 返回 401：先查 Authorization 头是否为 Bearer 加密钥的格式，再确认 Key 是否被删除或复制时带了空格。
• 返回 404 或模型不存在：多半是模型名写错或该模型未对当前账号开放，回控制台模型页复制完整标识。
• 返回 402 或余额不足：说明 5 美元试用额度已用完或已过期，到 Billing 页面核对余额与到期时间，需要继续使用就得自行充值。
• 返回 429：触发了速率限制，按响应头里的等待时间做指数退避重试，不要立即死循环。
• 超时或连接失败：确认请求地址没有多写或漏写 /v2/ext/openai/v1 前缀，并检查本地网络能否访问该域名。排查时始终从密钥、base_url、模型名这三项逐一核对，绝大多数报错都出在这里。