阶跃星辰 StepFun 一次性免费赠额说明与 Step 系列 API 接入教程

阶跃星辰提供与 OpenAI 兼容的 HTTP 接口，常见 base_url 形态为 https://api.stepfun.com/v1，实际地址请以控制台「API 文档 / 接口地址」页面的显示为准。模型名可在控制台的「模型列表」中获取，常见标识包括 step-2-16k、step-1-32k、step-1-8k 以及视觉模型 step-1v-8k 等，具体可用列表与上下文长度同样以控制台为准。

一、准备密钥并写入环境变量

先在控制台的「API Key 管理」中新建密钥并立即复制保存，密钥通常只完整显示一次。把它写入环境变量，避免硬编码进代码仓库。

export STEPFUN_API_KEY="sk-xxxxxxxxxxxxxxxx"

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

下面的请求体里，model 指定模型，messages 按角色传入对话内容，temperature 控制随机性，max_tokens 限制输出长度。整段可直接复制到终端运行。

curl https://api.stepfun.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEPFUN_API_KEY" \
  -d '{
    "model": "step-2-16k",
    "messages": [
      {"role": "system", "content": "你是一个简洁的技术助手"},
      {"role": "user", "content": "用一句话说明什么是对话补全接口"}
    ],
    "temperature": 0.7,
    "max_tokens": 512
  }'

三、用 Python SDK 调用

因为接口与 OpenAI 协议兼容，可以直接复用官方 SDK，只需替换 base_url 与 model。返回值取 choices[0].message.content 作为正文，usage 字段可用于统计 token 消耗。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["STEPFUN_API_KEY"],
    base_url="https://api.stepfun.com/v1",
)

resp = client.chat.completions.create(
    model="step-2-16k",
    messages=[{"role": "user", "content": "写一句产品简介"}],
    temperature=0.7,
    max_tokens=512,
)
print(resp.choices[0].message.content)

需要流式输出时，在请求中加入 stream: true，并按 SSE 逐块解析返回的增量内容。

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

1. 先看状态码：401 多为密钥错误、失效或请求头缺失；402、403 常见于额度用尽、账户状态异常或模型未开通；429 是触发频率或并发限制；5xx 多为服务端波动。
2. 回控制台「用量与账单」核对剩余额度与到期时间，确认赠额是否已过有效期或已被用完。
3. 核对 base_url 是否带 /v1、模型名是否与控制台列表完全一致，大小写与连字符写错都会返回模型不存在。
4. 缩小请求体，只用单条短消息测试，排除超长上下文或 max_tokens 过大导致的问题；429 时降低并发、加指数退避重试。
5. 仍无法定位时，检查服务端出口 IP 与网络代理设置，并对照控制台文档页的错误码说明逐条比对。