阶跃星辰 API 接入说明与能力概览

2026-07-24

阶跃星辰（StepFun）由前 Mistral、Google Brain 研究员创立，专注于多模态大模型研发。旗舰模型 Step-2 在中文推理、数学和多模态任务上表现出色，API 遵循 OpenAI 兼容协议，支持对话、视觉理解和 Embedding，是技术背景深厚的国产新兴选手。

如果你是从 OpenAI 或者 Claude 迁移过来做国产化替换，阶跃星辰是少数几家把 SDK 兼容做得比较干净的厂商——业务代码几乎不用改，换掉 base_url 和 api_key 两行就能跑通。但”能跑通”和”跑得稳”是两回事，本文重点铺开的是你实际会踩的坑：鉴权失败怎么查、限流怎么退避、上下文超限怎么排查，照着往下走一遍基本能定位大部分问题。

注册与获取 API Key

访问 platform.stepfun.com 注册账号；
进入控制台 → API Keys → 创建新密钥；
复制并妥善保存密钥；
控制台提供余额查看与充值入口，新用户有免费额度赠送。

这里有个容易被忽略的细节：新账号默认拿到的是测试额度，跟充值余额是两本账，计费面板上分开展示。如果调用时报了额度不足类的错误，但控制台余额明明还有钱，先别急着怀疑充值没到账——大概率是测试额度已经用完，而充值余额还没绑定到你实际调用的模型分组上。阶跃星辰部分模型（比如长上下文的 step-1-128k）需要在控制台里单独勾选开通才会计入可调用范围，不是注册完就默认全开。另外密钥创建之后只显示一次，务必当场存到密钥管理工具或 .env 文件里，刷新页面就再也看不到明文了，只能重新生成一个新的作废旧的。

接入示例：OpenAI 兼容调用

from openai import OpenAI

client = OpenAI(
    api_key="your-stepfun-api-key",
    base_url="https://api.stepfun.com/v1",
)

response = client.chat.completions.create(
    model="step-2-16k",                      # 旗舰对话模型
    messages=[
        {"role": "system", "content": "你是一个专业的数学解题助手"},
        {"role": "user", "content": "解方程：2x² + 5x - 3 = 0"},
    ],
)
print(response.choices[0].message.content)

上面这段代码里真正起作用的只有 base_url 这一行——OpenAI 的官方 SDK 底层就是拼 HTTP 请求，把 Authorization 头填成你的 key、把域名指向阶跃星辰的网关，其余的序列化、重试、超时全套逻辑都复用 SDK 自带的实现，这也是为什么”兼容 OpenAI 协议”的厂商能让你零成本迁移。但要注意 SDK 默认超时时间通常是几十秒，如果你的 prompt 很长、或者模型正在推理复杂数学题（比如上面这个二次方程只是示例，实际业务里可能是几千字的证明推导），默认超时可能不够用，建议显式传 timeout=60（在 OpenAI(...) 构造函数里加这个参数），否则长请求容易被客户端主动掐断，报出 httpx.ReadTimeout，看起来像服务端问题，其实是本地超时设置太保守。

流式输出：

stream = client.chat.completions.create(
    model="step-2-16k",
    messages=[{"role": "user", "content": "解释强化学习中的 PPO 算法"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

流式模式下每个 chunk 只装了增量的一小段文字，不是完整回答，所以要用 delta.content 而不是 message.content——这是新手最容易写错的地方，直接照搬非流式的取值方式会拿到 None 或者报 AttributeError。flush=True 也不是可有可无的装饰，Python 的标准输出默认是行缓冲，如果不强制刷新，你会看到文字堆积到一整段之后才突然全部冒出来，而不是逐字打印的效果，前端如果要做打字机动画，这行必须留着。真实生产环境里，流式接口还有一个坑：网络抖动时连接可能中途断开但不报异常，只是 stream 提前耗尽，建议给整个循环包一层计时器，超过预期时长没收完就判定为异常，主动重连或降级为非流式重试，别指望 SDK 会帮你兜底这种半途而废的情况。

多模态（图文理解）示例：

response = client.chat.completions.create(
    model="step-1v-8k",                      # 视觉理解模型
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "image_url", "image_url": {"url": "https://example.com/chart.png"}},
                {"type": "text", "text": "请分析这张图表的趋势"},
            ],
        }
    ],
)

多模态调用有个实操细节：image_url 既可以传公网可访问的图片链接，也可以传 base64 编码后的 data URI（形如 data:image/png;base64,xxxx）。如果你的图片是用户上传的私有文件、没有公网地址，就必须走 base64 这条路，注意编码前先确认图片体积——多数视觉模型对单张图有大小限制，超大截图建议先做压缩或裁剪再传，否则会收到请求体过大的错误，而不是一个”看不懂图片”的语义化提示，排查起来容易走弯路。

Function Calling（工具调用）示例：

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询指定城市的实时天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称，如：北京"},
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="step-2-16k",
    messages=[{"role": "user", "content": "北京今天天气怎么样"}],
    tools=tools,
    tool_choice="auto",
)
message = response.choices[0].message
if message.tool_calls:
    print(message.tool_calls[0].function.name)      # get_weather
    print(message.tool_calls[0].function.arguments)  # {"city": "北京"}

模型不会真的帮你查天气，它只是判断”这个问题需要调用哪个工具、参数是什么”，把结构化的调用意图返回给你，实际发请求查天气 API 是你自己代码里的事——很多人第一次用 Function Calling 会误以为模型能自己完成外部调用，结果发现 tool_calls 返回了却没有下文，其实是漏了拿到 arguments 之后自己执行函数、再把结果拼成 role: tool 的消息追加回对话历史这一步，少了这一步整个多轮工具调用链路就断在半路。

Embedding（文本向量化）示例：

embedding = client.embeddings.create(
    model="step-1-embedding",
    input=["国产大模型的API接入方式", "如何选择合适的AI模型"],
)
vector = embedding.data[0].embedding
print(len(vector))  # 向量维度，用于确认与向量库的 schema 是否匹配

Embedding 接口最容易翻车的地方不在调用本身，而在向量维度对不上。如果你把阶跃星辰的向量存进 Milvus、Pgvector 或者 Faiss 这类向量库，建表时的维度必须和这里打印出来的 len(vector) 完全一致，维度不匹配在写入阶段就会直接报错拒绝插入。更隐蔽的坑是”换模型不换维度”：如果你之前用别家模型生成的向量已经入库，后来切换到阶跃星辰的 Embedding 模型，新旧向量维度即便凑巧一致，语义空间也完全不通用，相似度检索出来的结果会牛头不对马嘴，正确做法是换向量模型就要整库重新生成 Embedding，不能新旧混用。

Step 主要模型对比

模型	上下文	定位	适用场景
`step-2-16k`	16k tokens	旗舰文本模型	复杂推理、数学、代码
`step-1-32k`	32k tokens	长上下文通用	文档分析、多轮长对话
`step-1-128k`	128k tokens	超长上下文	大型文档、代码仓库
`step-1v-8k`	8k tokens	多模态视觉	图文理解、图表分析
`step-1v-32k`	32k tokens	多模态长上下文	长文档+图片混合分析
`step-1x-medium`	-	代码专项	代码生成、调试优化

选择建议：文本推理任务优先 step-2-16k；需要处理长文档时选 step-1-128k；有图片输入时用 step-1v 系列。

不过光看上下文长度选型是不够的，长上下文不等于长记忆效果好——同样是 128k 窗口，模型在”塞满”和”塞一半”时的回答质量并不是线性下降的，越接近上限，模型对早期信息的召回准确度往往会打折扣（这是所有长上下文模型的通病，不是阶跃星辰独有）。实操建议：如果你的文档长度经常在 3-5 万字浮动，别图省事直接无脑上 step-1-128k，先用 step-1-32k 跑一遍看效果是否够用，同样的问题回答质量够用就没必要为多出来的上下文长度多付费——多数厂商长上下文模型单价会比标准版更高，这笔账值得自己实测再定。

常见报错排查

调阶跃星辰接口踩到报错，别急着怀疑服务不稳定，八成是下面几种情况之一：

报错现象	常见根因	排查方向
`401 Unauthorized` / `Incorrect API key`	key 复制少了字符，或用了别的厂商的 key	重新从控制台复制一遍，确认没有多余空格或换行符
`429 Too Many Requests`	触发了并发数或每分钟请求数限流	加指数退避重试，或检查是否有多个进程共用同一个 key 高频调用
`insufficient_quota` / 额度不足	测试额度用完，充值余额未绑定到对应模型	去控制台确认该模型是否已单独开通、余额是否分组正确
`context_length_exceeded`	输入 + 历史对话 + 期望输出总量超过模型上下文上限	换更大上下文的模型，或对历史对话做摘要压缩再拼接
`httpx.ReadTimeout`	客户端超时设置过短，长请求还没返回就被掐断	显式调大 `timeout` 参数，长文本/复杂推理场景尤其要留够余量
图片相关请求体过大	base64 图片编码后体积超过接口限制	传图前先压缩分辨率或裁剪，控制在接口允许的大小以内

其中 context_length_exceeded 是最容易被忽视的一类——很多人只算了当前这一条 user 消息的长度，却忘了多轮对话场景里 messages 数组是把历史全部消息一起打包发过去的，加上 system 提示词、加上模型预期要生成的输出长度，三者加起来才是真实占用。如果你在做长对话机器人，建议自己维护一个 token 计数器（可以用本站的 Token 计数器先估算一版），当历史对话累计接近模型上下文上限的 70%-80% 时就主动做摘要压缩或者截断最早的几轮，而不是等报错了才手忙脚乱去改代码。

并发调用与重试退避：

import time
import random
from openai import OpenAI, RateLimitError, APITimeoutError

client = OpenAI(api_key="your-stepfun-api-key", base_url="https://api.stepfun.com/v1")

def call_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(model="step-2-16k", messages=messages)
        except (RateLimitError, APITimeoutError) as e:
            if attempt == max_retries - 1:
                raise
            wait = (2 ** attempt) + random.uniform(0, 1)  # 指数退避 + 随机抖动
            print(f"第 {attempt + 1} 次调用失败（{type(e).__name__}），{wait:.1f}s 后重试")
            time.sleep(wait)

这段退避逻辑里 random.uniform(0, 1) 这个随机抖动不是凑数的，是有讲究的——如果你的服务是批量并发调用（比如同时给 100 个用户处理请求），一旦触发限流，如果所有失败请求都严格按 2 ** attempt 秒重试，会导致大量请求在同一时刻扎堆重发，反而加重限流，抖动的作用就是把重试时间错开，避免”重试雪崩”。生产环境里这类重试封装建议统一收敛成一个装饰器或中间件，而不是每个业务函数里各写一份，否则退避策略不一致，出问题了很难统一调优。

价格定性

截至 2026-06，以官方公示为准：

阶跃星辰定价处于国产中等偏低区间，旗舰模型有一定性价比优势；
多模态视觉模型通常高于纯文本版；
新用户赠送免费额度，便于测试各模型效果；
支持预付费充值模式。

具体单价以阶跃星辰价格页为准，也可用价格对比工具横向比较。

常见问题

Step-2 和 Step-1 有什么区别？ Step-2 是更新一代旗舰，在推理能力和中文理解上超过 Step-1；Step-1 系列上下文窗口更大（最高 128k），适合长文档场景。两代模型在功能上互补，可按需选用。

阶跃星辰支持 Function Calling 吗？ Step-2 和 Step-1 系列均支持 OpenAI 格式的 tools 参数，可接入 LangChain、AutoGen 等主流 Agent 框架。

Step 模型的数学能力和 DeepSeek-R1 比怎么样？ 两者在数学推理（MATH、AIME 等基准）上均有优秀表现，Step-2 在中文数学问题上有本土化优化。建议针对自己的实际业务场景做 A/B 测试，而非仅看榜单数据。

调用总是超时或者响应很慢，是网络问题还是模型问题？ 先分清是”连接建立慢”还是”生成内容慢”。如果是国内服务器调用国内厂商 API，连接耗时通常很短，慢主要慢在生成阶段——尤其是长上下文、复杂推理类请求，模型需要处理的 token 数越多，生成时间自然越长，这不是网络问题。真正因为网络导致的慢，通常表现为请求发出去很久都没有任何字节返回（包括流式模式下第一个 chunk 都迟迟不来），这种情况才值得去检查本地网络环境或者服务商是否有故障公告。区分清楚这两种情况，能帮你少走很多排查弯路，别一遇到慢就怀疑是代理或者防火墙的锅。

免费额度用完之后忘记关闭调用，会不会产生意外扣费？ 会。免费额度和付费余额在很多厂商的计费逻辑里是自动衔接的，额度耗尽后如果账户已绑定支付方式或者有充值余额，调用会直接从余额里扣费，不会主动停下来提醒你。如果只是测试阶段不想产生真实费用，建议在测试脚本里加一层调用次数上限的硬编码限制，或者干脆先不充值、跑完免费额度就先停手观察一下计费面板，确认理解清楚计费规则之后再放开手脚跑批量任务。

分类导航：国产模型专题

实用工具：价格对比工具 · Token 计数器