Upstage 免费额度：注册一次性送 $10，可试用 Solar 对话与文档解析

Upstage 提供 OpenAI 兼容的 REST 接口，把 base_url 设为 https://api.upstage.ai/v1 后，可以直接复用官方 OpenAI SDK。常用模型有 solar-pro（能力更强）与 solar-mini（更快、更省额度），嵌入模型为 solar-embedding-1-large；完整模型名单以控制台或官方文档的模型列表为准。

第一步：把密钥写进环境变量

不要在代码里硬编码密钥，先在终端中设置：

export UPSTAGE_API_KEY="在此填入控制台生成的密钥"

第二步：发起一次对话补全请求

关键参数说明：model 指定模型名；messages 是对话数组，每项包含 role（user、assistant、system）与 content；temperature 控制随机性，取值越低输出越稳定；max_tokens 限制回复长度，用来控制单次消耗；需要流式输出时把 stream 设为 true。

curl https://api.upstage.ai/v1/chat/completions \
  -H "Authorization: Bearer $UPSTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "solar-pro",
    "messages": [
      {"role": "user", "content": "用一句话解释什么是向量检索"}
    ],
    "temperature": 0.3,
    "max_tokens": 256
  }'

Python 项目可以直接复用 OpenAI SDK，只需替换 base_url 与密钥：

from openai import OpenAI

client = OpenAI(
    api_key="在此填入控制台生成的密钥",
    base_url="https://api.upstage.ai/v1",
)

resp = client.chat.completions.create(
    model="solar-mini",
    messages=[{"role": "user", "content": "写一条一句话产品文案"}],
    temperature=0.7,
    max_tokens=200,
)
print(resp.choices[0].message.content)

第三步：调用嵌入与文档解析

做检索增强时，用嵌入接口把文本转成向量，请求体只需要 model 与 input 两个字段：

curl https://api.upstage.ai/v1/embeddings \
  -H "Authorization: Bearer $UPSTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "solar-embedding-1-large", "input": "文档解析测试文本"}'

文档解析走单独端点 https://api.upstage.ai/v1/document-digitization，上传 PDF 或图片后返回结构化文本与版面信息，适合替代自建 OCR 流水线；也可先在控制台的 Studio 里用文档代理验证效果，再改成接口调用。

第四步：额度耗尽与限流的典型表现与排查顺序

建议按下面的顺序排查，避免一上来就怀疑模型问题：

1. 返回 401：检查请求头是否为 Bearer 加空格再加密钥，密钥是否在复制时被截断或混入空格。
2. 返回 429：多为触发速率限制或赠送额度用尽，先读响应体里的 error 字段区分原因，再回控制台用量页面核对余额与到期时间。
3. 返回 404 或提示模型不存在：核对 base_url 是否漏了 /v1，以及 model 名称拼写是否与控制台列表一致。
4. 确认是额度不足后充值，或先用 solar-mini 与更小的 max_tokens 降低单次消耗，把长文档解析放到独立批处理里跑。