# Credit 包订购及使用协议
Source: https://platform.stepfun.com/docs/zh/agreement/enterprise-credit-agreement



**最新版本生效日期：2026 年 8 月 10 日**

本《企业套餐订购及使用协议》（以下简称“**本协议**”）由购买和使用 StepFun 开放平台企业套餐的企业客户（以下简称“**您**”）与上海阶跃星辰智能科技股份有限公司（以下简称“**公司**”或“**我们**”）共同订立。

您已与我们另行签署订购企业套餐服务的框架合同或其他合作协议（以下简称“**框架合同**”）。本协议适用于您通过 StepFun 开放平台（以下简称“**平台**”）购买企业套餐服务，获得及使用 Credit 以及管理您的企业认证账户、项目、企业成员和 API Key 等相关活动（以下简称“**本服务**”）。

**您确认并保证，代表您注册并完成企业认证，管理企业认证账户的操作人员已获得您合法、充分且有效的授权，有权代表您签署本协议、购买企业套餐服务、支付费用、邀请和管理企业成员、配置项目及成员权限和 Credit 额度，并实施企业认证账户管理所需的其他操作。该等操作人员通过该等完成企业认证的账户实施的签署、购买、付款、确认、配置及授权等行为均视为您的行为，对您具有法律约束力。您不得以操作人员未经内部审批、超越内部权限或违反内部管理制度为由否认相关行为的效力。该等操作人员授权发生变更或终止的，您应及时完成权限变更或通知我们，否则由此产生的责任由您自行承担。**

**上述操作人员通过点击勾选或同意等方式确认本协议并提交购买订单，即视为您已阅读、理解并同意接受本协议的全部约定。本协议内容包括本协议正文以及平台已发布或后续依法更新并向您合理展示或通知的，与本服务相关的套餐说明、价格及计费规则、Credit 计量及消耗规则、功能说明和操作指引等（统称“服务规则”）。上述内容构成本协议不可分割的组成部分，与本协议具有同等法律效力。**

**请您在订购及使用本服务前，务必仔细阅读并充分理解本协议内容，特别是涉及免除或者减轻我们责任、排除或限制您的权利等与您有重大利害关系的条款。该等条款将以加粗等形式特别提示您注意，请您重点阅读。**

## 一、企业套餐的购买及服务

1. 您授权的操作人员在完成账户注册和企业认证后，可以在平台上选择输入购买金额，并按照页面展示的交易条件提交订单。**相关订单自我们收到全部款项后生效**，我们将按照订单展示的数量，将相应额度的 Credit 计入您的企业认证账户名下。**您应及时核实订单信息及对应的 Credit 到账情况，如有异议，应在付款后【三】个工作日内向我们提出。**

2. **您可购买的企业套餐金额及对应的 Credit 数量，以操作人员提交订单时平台页面展示的信息为准。不同购买金额及不同企业客户可能适用不同的阶梯折扣或其他优惠，具体以框架合同约定及订单提交时的页面展示为准。具体订单的购买金额、实际获得的 Credit 数量、有效期及支付状态等，以订单页面展示及平台系统记录为准。**

3. **您与我们签署的框架合同到期后，您可购买的企业套餐金额、适用的阶梯折扣及其他优惠等可能相应调整，具体以届时双方约定及平台页面展示为准。**

4. 您完成购买后，可获得对应的 Credit 用量，并使用企业项目管理、成员管理、权限及额度配置、API Key 管理、用量查询等配套功能，具体服务内容以平台实际提供及页面展示为准。**我们可根据产品升级、技术调整、运营安排或安全合规等原因对配套功能进行更新、优化或调整。如相关调整对您已购买的企业套餐的主要服务内容产生重大不利影响，我们将通过合理方式提前通知您。**

5. 您应通过我们指定的官方渠道完成支付。**因使用非官方渠道造成的支付失败、资金损失或其他风险，由您自行承担。同时，我们有权视情况暂停或终止相关服务、冻结账户余额或限制账号使用。因第三方支付平台故障导致的支付延迟或异常，我们将协助处理，但不对第三方原因造成的损失承担责任。**

## 二、服务使用规则

1. 您完成订单付款后，可获得相应数量的 Credit，Credit 仅作为平台计费单位，不属于货币、电子货币、虚拟货币、预付卡或其他具有法定支付功能的财产凭证。您调用平台任意模型 API 接口，使用相应模型服务时，用量将换算为 Credit 进行计算和扣减。**Credit 与相应模型用量的换算规则、有效期、扣减顺序以及不同模型的计费规则等以平台服务规则的说明为准。**

2. **除框架合同或本协议另有约定、我们存在计费错误或法律法规另有规定外，Credit 到账后不得兑换现金、转让至其他账户。有效期届满后，未使用的 Credit 将自动清零并失效，不得恢复、延期、兑换现金或要求退款，双方另有书面约定的除外。**

3. \*\*您应当自行关注 Credit 有效期并合理安排使用，Credit 不足时，我们有权暂停或终止向您提供服务。\*\*Credit 使用完毕后，应由您的操作人员提交订单并手动重新进行购买。除双方另有约定外，我们暂不提供自动扣款或自动续费服务。

4. 我们可能根据务合作、促销活动或客户服务安排向企业客户赠送一定数量的 Credit。赠送 Credit 的数量、使用范围、有效期、扣减顺序及其他限制，以订单页面、活动规则或平台展示为准。

5. 您授权的操作人员可以通过平台查询企业客户名下的 Credit 余额、组织用量、项目情况、成员情况及 API 调用数据等。其他企业成员仅能在其权限范围内查询相关数据。**平台展示的实时数据可能存在合理延迟，最终 Credit 用量以平台计费系统记录为准。您对调用量或 Credit 扣减存在异议的，应当在相关调用发生后【五】个工作日内提出，并提供必要的订单及调用信息以便我们进行核实。**

6. 您授权的操作人员可代表您邀请企业成员加入您的企业组织，\*\*操作人员和企业成员可以在平台创建和使用 API Key，所产生的 API 调用及 Credit 消耗均计入企业客户账户，从企业客户已购买的 Credit 用量中予以扣减。\*\*操作人员可以配置项目 Credit 上限以及项目内成员的 Credit 上限等，项目或成员达到额度上限后，相关 API 调用服务可能被限制或暂停。

## 三、服务使用规范

1. 您可通过平台账户或者其他我们允许的方式订购企业套餐，您订购的企业套餐仅限于您以及您授权的操作人员、企业成员使用，您应妥善保管账户、密码、API Key 等认证信息。**除我们另有明确许可外，您不得以任何形式将订购的服务全部或部分出售、转让、出借、出租、分许可、转授权或以其他方式提供给任何第三方使用**，否则，我们有权采取限制、暂停或终止服务等措施。

2. 您不得通过欺诈、虚假交易、利用系统漏洞、规避计费规则或其他违法违规、不正当方式获取或使用 Credit。**若发现上述情形，我们有权撤销或收回相关 Credit、要求您补足相应费用，并视情况限制、暂停或终止相关服务，由此造成的责任和损失由您自行承担。**

3. 您订购企业套餐后，将获得相应数量的 Credit。Credit 仅作为计算和扣减 API 服务用量的计量单位，不具有货币、储值或兑换价值。**API 服务的具体使用方式、可用模型、调用限制和其他使用要求，以平台另行展示的服务规则为准。您应当依法、合规、审慎使用 API 服务，并对您授权的操作人员、企业成员及您的最终用户的使用行为承担责任。**

4. **您自行负责对您的操作人员和企业成员进行内部授权、权限管理和使用监督。您应当及时移除离职、转岗或不再需要使用本服务的成员，并及时停用或删除相关 API Key。因企业客户内部授权瑕疵、权限配置不当、未及时移除成员、账户或 API Key 保管不善导致的 Credit 消耗、数据泄露或其他损失，由企业客户自行承担。**

5. **您在购买和使用本服务时，应遵守适用的法律法规、监管规定及国家标准，包括但不限于《中华人民共和国网络安全法》《中华人民共和国数据安全法》《中华人民共和国个人信息保护法》《生成式人工智能服务管理暂行办法》《互联网信息服务深度合成管理规定》《互联网信息服务算法推荐管理规定》《人工智能生成合成内容标识办法》等，并遵守平台发布的用户协议、隐私政策、服务规则及相关通知。您不得将本服务用于任何违法违规、违背公序良俗或侵害他人合法权益的活动。若您违反前述约定，我们有权视情形限制、暂停或终止相关服务，已支付费用原则上不予退还。**

## 四、暂停、中断与终止

1. **在下列任一情形下，我们可暂停、中止、限制或终止全部或部分企业套餐及 API 调用服务的使用：**

（1）Credit 额度不足或已全部失效；

（2）您违反本协议、服务规则、平台其他协议或适用法律法规；

（3）您的使用行为触发平台的安全、风控、反欺诈或反滥用机制；

（4）您存在未支付费用、支付失败、退款争议、拒付或账户异常；

（5）平台进行系统维护、升级、迁移、修复故障或资源调整且经事前合理通知；

（6）法律法规、监管要求、司法或行政机关要求；

（7）其他平台有合理理由认为需要采取措施的情形。

2. **服务暂停、中断或终止后，您可能无法继续访问或使用相关功能、历史记录、配置、任务状态等，在法律允许的范围内我们对此不承担责任。**

## 五、出口管制与经济制裁

**您在购买和使用本服务时，应遵守适用的出口管制、经济制裁及其他贸易合规法律法规，不得将本服务、Credit、API Key 或相关技术用于受限制的国家或地区、主体、最终用户或最终用途，亦不得以规避相关限制为目的进行转让、提供或使用。若我们有合理理由认为相关购买或使用行为可能违反前述规定，有权要求您提供必要的合规说明或证明，并可限制、暂停或终止相关服务。**

## 六、违约责任

1. **如您违反本协议、框架合同或平台服务规则，我们有权根据违约情形采取警告、限制账户权限、暂停 Credit 使用、撤销或收回不当取得的 Credit、要求补足费用、暂停或终止服务等措施。因您的违约行为导致服务被暂停或终止的，已支付费用原则上不予退还。**

2. **因您、您授权的操作人员或其他企业成员的操作、授权、权限配置、账户管理不当，或者通过违法违规、不正当方式获取或使用 Credit、API 服务，导致我们或任何第三方遭受损失、索赔、处罚或其他责任的，您应承担相应责任，并赔偿我们因此遭受的实际损失。**

3. **本协议未约定的违约责任及责任限制，按照框架合同、平台服务规则的约定执行。**

## 七、责任限制

**因不可抗力、第三方服务原因或其他非平台原因导致的服务中断、延迟、异常、数据丢失、调用失败、功能受限或其他损失，我们在法律允许的最大范围内不承担责任。前述第三方包括但不限于网络运营商、云服务商、支付机构、第三方应用/工具/插件提供方等。**

## 八、未成年人消费提醒

**本服务主要面向成年人提供。未成年人原则上不得购买或以其他方式消费本服务**。我们有权根据适用法律法规、监管要求或平台服务规则，对未成年人使用、购买或消费本服务采取限制、拒绝、暂停或其他管理措施。

## 九、协议更新

**我们有权根据产品变化、业务安排、法律法规、监管要求或运营需要对本协议进行更新。更新后的协议可通过页面公示、弹窗提示、站内通知、电子邮件或其他合理方式向您展示。协议更新后，如您继续使用本服务，视为您接受更新后的协议内容，如您不同意更新内容，可停止使用相关服务并及时与我们联系。**

## 十、其他

1. **本协议自您的操作人员代表您通过点击勾选或同意等方式确认本协议并提交订单时成立，并自我们收到相应订单全部款项之日起就该笔订单生效。**

2. 本协议未约定事项，按照框架合同及其他平台服务规则执行。

3. **本协议的法律适用及争议解决，按照框架合同约定执行。如您与我们未签署框架合同，或框架合同未对法律适用及争议解决作出约定，本协议的订立、生效、履行、解释及争议解决均适用中华人民共和国大陆地区法律。因本协议产生或与本协议有关的任何争议，双方应先行协商解决，协商不成的，任何一方均可向公司住所地有管辖权的人民法院提起诉讼。**


# 开放平台管理规则及公约
Source: https://platform.stepfun.com/docs/zh/agreement/management-rules-and-conventions



尊敬的用户：

依据《中华人民共和国网络安全法》、《中华人民共和国数据安全法》、《中华人民共和国个人信息保护法》、《互联网信息服务管理办法》、《生成式人工智能服务管理暂行办法》、《互联网用户账号信息管理规定》、《网络信息内容生态治理规定》、《网站平台受理处置涉企网络侵权信息举报工作规范》等法律、行政法规、规章的规定，对于您注册使用StepFun开放平台、AI Studio平台及相关服务（以下简称“**本服务**”）的行为，我们制定了如下管理规则和公约（以下简称“**本规则**”），请您仔细阅读并认真遵守，与我们共创一个文明的网络环境。

**一、我们倡导**

1\. 积极履行信息安全义务，遵守相关法律法规政策。不得使用本服务进行非法活动或发布违法内容，不得利用本服务侵犯他人正当权益或谋取不正当利益。

2\. 理解人工智能服务的局限性，它不具备情感、观点或自主意识，它所生成的内容可能不准确，请谨慎参考它所生成的内容，注意核实和验证您或第三方从本服务中获得的信息，特别是涉及重要决策和敏感问题的情况下。

3\. 尊重隐私并注意保护数据安全，遵守本规则、用户协议、隐私政策和相关规定，不要在使用本服务的过程中，输入、分享任何敏感个人信息或其他未经授权的信息。

4\. 积极分享您的反馈与建议，帮助我们共同改善本服务的功能和用户体验。如果您发现任何问题、错误或改进的机会，或遇到任何违反用户协议和/或本规则的行为，请及时与我们联系。

**二、我们禁止及不欢迎**

**（一）您在注册、使用账号信息及使用本服务的过程中，应当遵守法律法规，遵循公序良俗，诚实信用，不得损害国家安全、社会公共利益或者他人合法权益。禁止利用本服务进行任何形式危害国家及社会安全的行为，包括且不限于：**

1\. 假冒、仿冒、捏造政党、党政军机关、企事业单位、人民团体和社会组织的名称、标识等；

2\. 假冒、仿冒、捏造国家（地区）、国际组织的名称、标识等；

3\. 假冒、仿冒、捏造新闻网站、报刊社、广播电视机构、通讯社等新闻媒体的名称、标识等，或者擅自使用“新闻”、“报道”等具有新闻属性的名称、标识等；

4\. 假冒、仿冒、恶意关联国家行政区域、机构所在地、标志性建筑物等重要空间的地理名称、标识等；

5\. 以损害公共利益或者谋取不正当利益等为目的，故意夹带二维码、网址、邮箱、联系方式等，或者使用同音、谐音、相近的文字、数字、符号和字母等；

6\. 含有名不副实、夸大其词等可能使公众受骗或者产生误解的内容；

7\. 制作、复制、发布含有下列内容的违法信息：

（1） 反对宪法所确定的基本原则的；

（2） 危害国家安全，泄露国家秘密，颠覆国家政权，破坏国家统一的；

（3） 损害国家荣誉和利益的；

（4） 歪曲、丑化、亵渎、否定英雄烈士事迹和精神，以侮辱、诽谤或者其他方式侵害英雄烈士的姓名、肖像、名誉、荣誉的；

（5） 宣扬恐怖主义、极端主义或者煽动实施恐怖活动、极端主义活动的；

（6） 煽动民族仇恨、民族歧视，破坏民族团结的；

（7） 破坏国家宗教政策，宣扬邪教和封建迷信的；

（8） 散布谣言，扰乱经济秩序和社会秩序的；

（9） 散布淫秽、色情、赌博、暴力、凶杀、恐怖或者教唆犯罪的；

（10） 侮辱或者诽谤他人，侵害他人名誉、隐私和其他合法权益的；

（11） 法律、行政法规禁止的其他内容。

8\. 制作、复制、发布含有下列内容的不良信息：

（1） 使用夸张标题，内容与标题严重不符的；

（2） 炒作绯闻、丑闻、劣迹等的；

（3） 不当评述自然灾害、重大事故等灾难的；

（4） 带有性暗示、性挑逗等易使人产生性联想的；

（5） 展现血腥、惊悚、残忍等致人身心不适的；

（6） 煽动人群歧视、地域歧视等的；

（7） 宣扬低俗、庸俗、媚俗内容的；

（8） 可能引发未成年人模仿不安全行为和违反社会公德行为、诱导未成年人不良嗜好等的；

（9） 其他对网络生态造成不良影响的内容。

（二）您在使用本服务过程中，不得采用任何技术手段删除、篡改、隐匿生成内容中的标识。

三、您在使用本服务的过程中，不得实施侮辱、诽谤、威胁、散布谣言以及侵犯他人隐私等违法行为，不得制作、复制、发布混淆企业主体身份的仿冒性信息、影响公众公正评判的误导性信息、不符合企业客观实际的谣言性信息、贬损丑化企业或企业家的侮辱性信息、侵害企业家个人隐私的泄密性信息以及其他恶意干扰企业正常经营发展的信息，不得损害他人和其他企业主体的合法权益。如您使用本服务的过程中发现前述违法违规以及不良信息，您可以向我们投诉、举报。

四、**您申请注册相关账号信息，我们有权对您进行基于移动电话号码或身份证件号码等方式的真实身份信息认证，您不提供真实身份信息，或者冒用他人身份信息进行虚假注册的，我们有权不为您提供相关服务**。个人用户注册、使用账号信息，含有职业信息的，应当与个人真实职业信息相一致。机构用户注册、使用账号信息，应当与机构名称、标识等相一致，与机构性质、经营范围和所属行业类型等相符合。

五、**我们将采取措施适时核验存量账号信息，若发现您的账号信息不符合法律、行政法规、规章或本规则要求的，将暂停向您提供服务并通知您限期改正；拒不改正的，我们将终止向您提供服务。**

六、我们有权建立互联网用户账号信用管理体系，将您的账号信息相关信用评价作为账号信用管理的重要参考指标，并据以向您提供相应服务。

七、**如果您在注册、使用账号以及在您使用本服务的过程中，出现违反法律、行政法规、规章或本规则规定的行为，我们有权根据本规则及您签署的用户协议的约定采取预先警示、拒绝发布、立即停止传输信息、删除信息内容、短期禁止发布内容、限制账号部分或者全部功能直至终止提供服务、永久关闭账号等措施。**

八、本规则自公布之日起执行。我们也将随着产品生态的健康发展，不断完善与更新本规则。若您在使用本服务过程中发现任何您认为可能违反本规则的内容，可直接通过本服务相关页面展示的路径进行反馈，或通过[platform@stepfun.com](mailto:platform@stepfun.com)联系我们。


# Step Plan 付费服务协议
Source: https://platform.stepfun.com/docs/zh/agreement/step-plan



**最新版本生效日期：2026年5月25日**

欢迎您使用Step Plan付费服务（“**本服务**”）。本《Step Plan付费服务协议》（“**本协议**”）由您与上海阶跃星辰智能科技股份有限公司（以下简称“**公司**”或“**我们**”）、就您在StepFun开放平台（“**平台**”）中付费订阅相关AI模型服务时所订立。

**本协议项下的Step Plan付费服务相关约定，不仅包括本协议正文内容，还包括平台上已经发布或将来不时发布、更新的与该等服务有关的产品介绍、套餐说明、订阅说明、价格及计费规则、额度和速率限制规则、功能说明、开发文档、帮助中心内容、操作指引、公告、通知及其他规则文件（统称“服务规则”）。上述内容构成本协议不可分割的组成部分，与本协议具有同等法律效力。**

**请您在订阅本服务前，务必仔细阅读并充分理解本协议内容，特别是涉及免除或者减轻我们责任、排除或限制您的权利等与您有重大利害关系的条款。该等条款将以加粗等形式特别提示您注意，请您重点阅读。您通过勾选/点击确认、支付费用、开通或实际使用付费服务的，即视为您已阅读、理解并同意受本协议及全部服务规则的约束。**

**如您以企业用户身份或其他代表企业、机构的身份接受本协议，开通、订阅或使用本服务，您声明并保证您已获得该企业或机构的合法、充分且持续有效的授权，有权代表其接受本协议并作出与订阅、使用本服务相关的操作；如您不具备前述授权，我们有权拒绝或终止向相关账户提供服务，由此产生的责任及损失由您及/或相关企业、机构自行承担。**

本协议是《StepFun平台用户协议》《StepFun平台隐私政策》的重要组成部分；如本协议与前述文件约定不一致，就订阅付费服务相关事项以本协议为准。

## 1. 订阅内容与服务

1. 我们向用户提供不同档位的订阅套餐，各套餐在功能范围、可用模型、使用限额、速率限制、并发能力、上下文长度、工具调用权限等方面可能存在差异，具体以您订阅页面展示为准。**您注册、登录平台账户，在平台订阅页面选择具体套餐并完成支付，即视为您开通了相关付费服务，可使用订阅套餐中的相关权益**。您所获得的付费服务的有效期限及所包含的权益范围，以订阅页面展示的服务规则说明为准。请您在购买前充分了解相关服务规则并妥善保留相关凭证。

2. **您知悉并同意，我们可能基于产品演进、模型升级、系统维护、商业安排、成本变化、第三方政策调整、安全风控或合规要求等原因，对订阅套餐的名称、价格、计费方式、功能范围、支持模型/应用、限额规则、速率限制或其他服务内容进行调整。我们将就前述调整通过公告、通知或以其他合理方式向用户进行说明。如该等调整将对价格、核心功能或限额等产生重大不利影响，原则上将自后续计费周期起生效，但法律法规、监管要求或安全处置需要立即调整的除外。如您在调整生效后继续使用/未取消订阅套餐的，视为同意调整后的服务规则。**

3. **您理解并同意，不同模型或不同能力对应的资源消耗、响应速度、配额消耗和速率限制等可能存在差异，如您的已订阅套餐开始支持更高等级模型或高级功能，可能出现响应速度变化、配额消耗加快或适用更严格限制等情况，具体以平台届时展示的相关规则和说明为准。我们将在相关页面尽合理努力对前述差异作出说明，您可根据自身需求选择继续使用、调整使用方式或变更套餐。**

4. 在部分场景下，我们支持用户在现有订阅套餐基础上升级或更换订阅套餐。**我们支持的可更新的订阅套餐类型、费用与差价规则以及原套餐项下的权益处置规则等以届时平台相关页面的说明、操作指引或相关文档说明为准。**

## 2. 计费、订阅周期与自动续费

1. 付费服务通常按月度、年度或其他周期计费，具体以订阅页面展示为准。您应按照订阅页面展示的套餐价格、币种、税费规则和计费周期支付相应费用。

2. **在订阅周期届满前，您可在指定界面申请续期。如订阅套餐支持自动续费功能，则在当前订阅周期届满前，除非您已在平台指定页面取消续费，否则我们将按照您已选择的套餐及适用价格自动扣费续订下一周期。请您在订阅前，留意相关的续费规则说明。**

3. **我们可能基于不同订阅套餐的购买方式、用户账户状态、风控需要、库存安排或其他运营管理需要，对各订阅套餐可购买数量进行限制；用户在相应时段内可购买的数量以平台届时页面展示或系统实际允许的数量为准。**

4. **您授权平台或平台指定的支付服务商，按照您绑定的支付方式，根据订阅套餐价格、计费周期等收取相关费用。因余额不足、支付失败、账户异常或支付渠道限制等导致订阅或续费失败的，平台可暂停或终止向您提供相应付费服务。**

5. **您仅可通过我们指定的官方支付渠道完成支付，若您选择非官方支付渠道进行支付，可能导致付费失败，同时可能引发其他损失或风险，若因此造成您或任何第三方利益受损，由您自行处理并承担相应责任，我们不承担任何有关责任，同时我们保留中止或终止您的部分或全部权限、冻结您的账户余额、短期或永久封禁您的账号及/或限制、禁止您使用各项付费服务的权利。**

6. **除适用法律另有规定、公司另有明确承诺或双方另有约定外，已支付的订阅费用不予退还。已开始的计费周期不因您未实际使用、减少使用频率或提前取消而按比例退款，您在有效期内未使用的权益将在到期后自动失效。**

## 3. 付费服务使用规范

1. 您可通过平台账户或者其他我们允许的方式订阅付费服务，订阅的付费服务仅限开通和订阅该服务的账户自行使用，您应妥善保管账户、密码、API Key等认证信息。**除我们另有明确许可外，您不得以任何形式将订阅的付费服务全部或部分出售、转让、出借、出租、分许可、转授权或以其他方式提供给任何第三方使用**，否则，我们有权采取限制、暂停或终止服务等措施。

2. 您理解并确认，**为使用订阅套餐内的相应服务，可能需要您自行负责并完成必要的应用/插件/工具安装、接入、环境配置等操作，确保第三方应用/插件/工具持续可用**，具体可参考平台相关页面的文档说明。

3. 您订阅的付费服务仅限在我们支持或明确说明可适配的接入方式、使用环境、应用、工具或插件中使用（具体以平台页面说明为准）。**未经我们明确许可，您不得通过非官方、未授权或未经说明可适配的工具、插件、接口或其他方式接入、调用或使用订阅的付费服务，因此产生的服务异常、数据丢失、安全风险或其他后果，由您自行承担。**

4. **因您账户保管不善、密钥泄露、设备失窃或您安装、接入的第三方应用/插件/工具的原因导致的付费服务无法使用、资金损失、数据泄露、误操作、资源滥用或其他后果，由您及/或第三方自行承担。**

5. 您理解并同意，您订阅的付费服务可能设置一种或多种技术限制，包括但不限于：请求频率限制；一定周期内的使用限额；每分钟、每小时、每五小时、每日、每周或每月的消息数、请求数、token数、计算量或调用量、总计费金额限制；并发任务数、并发 Agent 数、并发工具调用数限制；上下文长度、输入大小、输出长度、附件大小或文件数量限制；特定模型、特定功能、特定集成方式或特定地区的额外限制等。**请您在订阅付费服务前，务必仔细阅读相关页面的服务规则说明，了解限制规则，自行决策是否订阅付费服务。当您达到适用限制时，我们可视情况采取以下措施：限制新请求、延迟处理、排队执行、暂停相关功能、切换至其他模型、降低服务等级、提示升级套餐或采取其他合理措施。**

6. **您理解并同意，我们可能根据系统负载、资源使用情况、产品策略、安全风控、反滥用机制或合规要求，动态调整速率限制和限额规则，但我们会尽最大努力保障您的合法权益不受损害。您不得通过脚本、代理、令牌轮换、批量注册、逆向接口、异常并发、规避排队机制或其他不正当方式绕过前述限制。**

7. **您在使用订阅的付费服务时，应当遵守《StepFun平台用户协议》《平台管理规则及公约》的相关约定，不得从事任何违反法律法规、监管要求、行业规范或公序良俗的活动。**

## 4. 暂停、中断与终止

1. **在下列任一情形下，我们可暂停、中止、限制或终止全部或部分订阅服务的使用：**

（1）您违反本协议、服务规则、平台其他协议或适用法律法规；

（2）您的使用行为触发平台的安全、风控、反欺诈或反滥用机制；

（3）您存在未支付费用、支付失败、退款争议、拒付或账户异常；

（4）平台进行系统维护、升级、迁移、修复故障或资源调整；

（5）法律法规、监管要求、司法或行政机关要求；

（6）其他平台有合理理由认为需要采取措施的情形。

2. **服务暂停、中断或终止后，您可能无法继续访问相关功能、历史记录、配置、任务状态等，我们对此不承担责任，但法律另有规定的除外。**

3. **您可在平台指定页面取消订阅，取消订阅通常仅影响下一计费周期，当前周期内已生效服务不因此而当然终止。**

## 5. 责任限制

**因不可抗力、第三方服务原因或其他非平台原因导致的服务中断、延迟、异常、数据丢失、调用失败、功能受限或其他损失，我们在法律允许的最大范围内不承担责任。前述第三方服务包括但不限于网络运营商、云服务商、支付机构、第三方应用/工具/插件提供方等。**

## 6. 活动与推广规则

**我们可能在特定推广期、促销期、测试期或其他活动期限内，就部分套餐提供与常规规则不同的价格、套餐内容、限额、功能、适用范围、购买条件或其他优惠安排，具体以届时活动页面、活动规则或相关说明为准。前述活动安排仅在对应活动期限内有效，不构成我们对相同或类似价格、权益、功能或服务条件的长期承诺。活动结束后，相关套餐的价格、套餐内容及适用规则以平台届时正式展示或适用的规则为准。**

## 7. 未成年人消费提醒

**本服务主要面向成年人提供。未成年人原则上不得订阅、购买或以其他方式消费本服务**；如未成年人确需使用本服务，应在其监护人同意并指导下进行。我们有权根据适用法律法规、监管要求或平台规则，对未成年人使用、购买或消费本服务采取限制、拒绝、暂停或其他管理措施。

## 8. 协议更新

**我们有权根据产品变化、业务安排、法律法规、监管要求或运营需要对本协议进行更新。更新后的协议可通过页面公示、弹窗提示、站内通知、电子邮件或其他合理方式向您展示。协议更新后，如您继续使用订阅服务，视为您接受更新后的协议内容；如您不同意更新内容，应停止使用相关服务并按平台规则取消订阅。**

## 9. 争议解决

**本协议根据中华人民共和国大陆地区法律法规制定，受中华人民共和国大陆地区法律法规管辖。因本协议而发生的任何争议应提交至公司住所地有管辖权的人民法院诉讼解决。**


# StepFun 开放平台隐私政策
Source: https://platform.stepfun.com/docs/zh/agreement/userprivacy



**最新版本生效日期：2026年9月28日**

欢迎您使用本平台！上海阶跃星辰智能科技股份有限公司（简称“我们”，注册地址为：上海市徐汇区云锦路701号30层）深知个人信息对您的重要性，您的信任对我们非常重要，我们将按照法律法规的规定并参照行业最佳实践保护您的个人信息及隐私安全。

本隐私政策适用于我们通过我们运营的StepFun开放平台、AI Studio平台等形式（本隐私政策中统称“**本平台**”）向您提供的产品和服务，如我们的某一终端、产品与/或服务单独设置了隐私政策的，单独的隐私政策优先于本隐私政策适用。我们制定本隐私政策并特别提示，希望您在使用本平台相关服务前仔细阅读并理解本隐私政策，以便做出适当的选择。**重要内容我们已用加粗形式提示，请特别关注。如涉及敏感个人信息的，我们将进一步通过加下划线的方式提示您关注；同时，提请您注意，敏感个人信息一旦泄露或者非法使用，可能对您的个人权益产生影响（例如人身财产安全受到危害），但我们会按照国家有关法律的规定，采取恰当的安全管理和技术措施维护您的敏感个人信息安全。**

**您通过勾选等方式主动确认本隐私政策后，即意味着您已阅读并理解我们的个人信息处理规则，在您使用本平台时，我们将按照本隐私政策的说明处理您的相关个人信息。**

请您注意，为了您能够正常使用本平台，您应当开启或授权网络权限，确保WLAN或移动网络的连接，此举可能产生流量费用，具体费用请咨询当地运营商。如您关闭或不允许我们使用网络权限，您将无法使用本平台。

**本隐私政策旨在帮助您了解以下内容：**

一、我们如何收集和使用相关信息

二、我们如何使用cookie等同类技术

三、我们如何共享、委托处理、转移、公开披露您的个人信息

四、我们如何存储个人信息

五、我们如何保护个人信息的安全

六、管理您的个人信息

七、未成年人条款

八、隐私政策的修订和通知

九、联系我们

十、法律适用及争议解决

十一、定义

## 一、我们如何收集和使用相关信息

我们会按照如下方式收集您在使用本平台时主动提供的，以及通过自动化手段收集您在使用功能或接受服务过程中产生的信息：

**1. 帮助您成为我们的用户**

当您首次使用本平台时，您可以通过**手机号码**创建账号以完成注册，成为我们的用户，我们会通过发送**验证码**的方式来验证您的身份是否有效。后续您可通过输入您注册时的手机号码，并在输入验证码后完成登录以使用本平台相关服务。如果您不提供手机号码及验证码用于注册、登录，我们可能无法为您提供相应服务。

您还可以在本平台绑定**您的电子邮箱**，设置您的**登录密码**，完成后，您可使用该等邮箱、登录密码登录本平台。

您使用本平台服务时，我们还会进一步收集并向您展示您的**头像、昵称**信息，以便向您提供更加个性化的账户服务体验。

**鉴于我们运营的StepFun开放平台及AI Studio平台使用同一套账户体系，您注册StepFun开放平台或AI Studio平台账户后，均可以使用该账户直接登录StepFun开放平台、AI Studio平台，并使用相应服务。**

**2. 实名认证服务**

为保障平台及账号安全、核验用户个人或企业身份，并防止恶意注册、不当获取平台权益或其他滥用行为，我们可能根据具体服务场景要求您完成个人实名认证或企业认证。当您进行个人实名认证时，我们需要收集您的**姓名、身份证号码信息**，并将上述信息提供给我们委托的实名认证服务合作方进行身份核验。**认证过程中，您将通过合作方提供的认证页面完成刷脸认证，合作方将直接收集您的人脸信息以及必要的设备及操作环境信息，并结合您的姓名、身份证号码进行身份核验，必要时合作方还可能进一步通过其合作的验证服务商或其他合法保存您身份信息的机构完成核验**。认证完成后，合作方将向我们返回**认证结果信息**；除非另有说明，**我们不会获取或留存合作方在认证过程中采集的人脸信息**。前述信息是为您提供个人实名认证服务的必要信息，如您拒绝我们或合作方收集，我们将无法对您的身份进行核验，进而可能影响您使用本平台提供的相应服务。

若您希望能认证成为企业用户的，还需要提供相应的企业信息，包括公司名称、统一社会信用代码、银行账户信息等，具体以认证页面展示为准。

**3. 智能对话、内容生成及AI助手服务**

您可通过本平台体验我们提供的模型和API能力，在您体验相应服务的过程中，为了向您提供智能对话、内容生成及AI助手服务，进行内容理解、数据分析，以更好地理解您的需求，答复您的问题，生成相关内容，执行您的任务指令，以及便于您对历史对话记录进行管理，我们会收集**您主动输入的信息（包括文字、语音、图片、视频、音频、文本、链接等多种形式）以及服务的输出信息、您的任务指令信息、您设置的模型及参数信息以及您提供的反馈信息**。我们会对上述信息进行分析、计算、搜索，以便于更好地理解您的需求和上下文语境，从而为您提供更具有相关性及更高精准度的信息内容、更准确地执行您的任务指令。在您使用 AI Studio服务时，我们还会记录并向您展示**您上传和模型生成的素材内容**（如图片、文档、表格、音频、网页），以便您可以查阅、管理及复用过往上传和生成的内容。

前述信息是为向您提供智能对话、内容生成及AI助手服务的必要信息，如您拒绝提供，您可能将无法使用我们提供的相应服务。

**4. 个性化能力**

本平台中的部分服务支持您进行个性化管理，例如，我们会根据与您的**对话记录**，总结并形成对您的**相关记忆**（如您的工作习惯、偏好），以便模型参考对您的相关记忆，向您输出更适合您、更符合您需求的回答。您可以随时根据本平台页面操作指引，查看、编辑或删除模型已保存的记忆，您也可以选择关闭记忆功能，我们将不会继续在与您对话时使用对您的相关记忆，您关闭记忆功能不会影响您继续使用我们的其他服务。您还可以进一步向我们提供您的**个人背景信息、您偏好的回复风格信息**，模型会参考该等信息，输出更适合您的回答，我们不会基于该等信息向您进行个性化推送。

**5. 管理服务使用情况**

为了帮助您管理使用本平台提供的相应服务的情况，我们会记录并向您展示**您在StepFun开放平台项下的API接口密钥信息以及创建时间、最近调用时间**；**您在本平台的服务订阅、使用记录及套餐兑换记录**。前述信息为帮助您管理服务相关使用情况的必要信息，如您拒绝我们收集相应信息的，可能导致无法向您展示您的服务使用情况。

**6. 套餐兑换、充值、支付与发票管理**

如您通过支付宝小程序购买套餐并跳转至StepFun开放平台进行兑换，为完成订单与平台账户匹配、套餐兑换及权益发放，我们会从相关购买/支付渠道收集并处理您的**订单信息以及您购买套餐时提供的手机号码、渠道来源标识信息**。上述信息可能由您主动提供、在您使用相关服务过程中产生，或者由支付宝小程序购买页面及支付宝在相关交易发生后向本平台传递。前述信息是为您完成套餐兑换并获得相应权益所必需的信息，如您拒绝提供，我们可能无法为您完成套餐兑换或发放相应权益。此外，我们在第三方购买/支付渠道收集处理您个人信息的具体情况，请以第三方购买/支付渠道界面载明的隐私政策、个人信息处理授权书等实际适用的个人信息处理规则为准。

您可通过充值的方式使用本平台提供的某些服务，为此我们会收集并向您展示**您的充值记录、账户资金及其使用情况。**

本平台相关服务可能需要您支付一定费用后方能使用，具体以本平台相关页面届时展示的信息为准。在您完成费用支付后，我们需要收集并记录您的**费用支付信息及服务使用情况**，以便根据您的付费情况向您开放相关服务。

您可按本平台规则申请开具发票，为此您需要向我们提供相应的**开票信息**。

上述信息为记录您的充值、费用支付情况以向您提供相关服务的必要信息，如您拒绝我们收集相应信息的，可能导致您无法使用相关服务。

**7. 向您进行消息通知**

您知悉并同意，我们可能会通过您在使用本平台的过程中所提供的**联系方式**，向您同时发送一种或多种类型的通知，例如服务使用情况提醒。但请您放心，如您不愿接受这些信息，您可以直接与我们联系进行退订。

**8. 客服服务**

您可以通过本平台中的问题反馈相关界面，填写并向我们提交您对本平台的意见和建议，我们会收集**您填写的反馈信息**。如您希望您的意见和建议得到及时回应，您可以选择留下您的**联系方式**，我们会通过您的联系方式与您进行沟通。

当您与我们联系进行客服咨询、投诉/举报、反馈意见和建议时，为便于与您联系、尽快帮助您解决问题或记录相关问题的处理方案及结果，我们可能会保存您与我们的**通信/通话记录及相关内容（包括账号信息、反馈信息、您为了证明相关事实提供的其他信息、您留下的联系方式）**。前述信息系为向您提供相应服务的必要信息，如您拒绝我们收集，可能导致您无法使用相应服务。

**9. 为您提供运营与安全运行保障**

我们致力于向您提供安全、可信的产品与使用环境，提供优质而可靠的服务与信息是我们的核心目标。为了维护我们服务的正常运行，保护您或其他用户或公众的合法利益免受损失，您在使用本平台时，我们会收集用户的设备信息与日志信息，包括：**您的硬件型号、操作系统版本号、设备标识符、IP地址、WLAN接入点（如SSID，BSSID）、基站、软件版本号、网络接入方式、类型、状态、网络质量数据、网络源地址和目标地址、网络源端口、操作时间和操作类型、使用、服务日志、搜索/分享/收藏记录、设备传感器数据（如加速度传感器）、总体使用情况、性能数据**。

**10. 征得授权同意的例外**

**请您理解，在下列情形中，根据法律法规及相关国家标准，我们收集和/或以其他方式处理（包括但不限于存储、使用、加工、传输、提供、公开、删除）您的个人信息不必事先征得您的授权同意：**

(1) 为订立、履行个人作为一方当事人的合同所必需，或者按照依法制定的劳动规章制度和依法签订的集体合同实施人力资源管理所必需；

(2) 为履行法定职责或者法定义务所必需；

(3) 为应对突发公共卫生事件，或者紧急情况下为保护自然人的生命健康和财产安全所必需；

(4) 为公共利益实施新闻报道、舆论监督等行为，在合理的范围内处理个人信息；

(5) 依照《中华人民共和国个人信息保护法》规定在合理的范围内处理个人自行公开或者其他已经合法公开的个人信息；

(6) 法律、行政法规规定的其他情形。

**11. 您个人信息的其他用途**

**(1) 我们通过技术手段对您使用本平台相关服务产生的个人信息进行匿名化处理后，可能会使用已经匿名化处理的信息，进行数据分析并可能予以商业化的利用。**

**(2) 我们可能会对本平台的使用情况进行统计，并可能会与公众或第三方共享这些统计信息，以展示本平台的整体使用趋势。但这些统计信息不包含您的任何身份识别信息。**

**(3) 我们在此特别提醒您，为给您带来更好的产品和服务体验，我们会持续努力改进我们的产品、服务及技术，随之我们可能会不时推出新的或优化后的功能，为此可能需要收集、使用新的个人信息或变更个人信息使用目的或方式。如发生上述情形，我们将通过更新本隐私政策、弹窗、页面提示等方式另行向您详细说明，并重新征得您的同意（根据法律法规规定无需取得您同意的除外）。在此过程中，如果您有任何疑问、意见或建议的，您可通过本隐私政策公布的联系方式与我们联系，我们会尽快为您做出解答。**

**12．如您在使用本平台过程中输入、上传的内容包含或涉及第三方的信息（包括但不限于个人信息），在输入这些信息之前，您需确保您的行为已经取得合法的授权，避免泄露他人个人信息，侵犯他人权利。**

**13. 权限说明**

在您使用本平台的某些功能或服务时，我们可能会申请调用您的系统权限，以基于该等权限为您提供相应服务。我们不会默认开启您的系统隐私权限，只有经过您的明示授权才会在为实现特定功能或服务时使用，您也可以撤回授权。特别需要指出的是，即使经过您的授权，我们获得了这些敏感权限，也不会在相关功能或服务不需要时而收集您的信息。

**当您使用我们的产品及服务时，具体各项业务功能可能涉及调用的系统权限情况如下：**

| | |
| - | - |
| **权限名称** | **使用场景、目的** |
| **麦克风** | 帮助用户完成语音输入、录音 |

## 二、我们如何使用cookie等同类技术

cookie和设备信息标识等同类技术是互联网中普遍使用的技术。当您使用本平台时，我们可能会使用相关技术向您的设备发送一个或多个cookie或匿名标识符，以收集、标识和存储您访问、使用本平台时的信息。我们承诺，不会将cookie用于本隐私政策所述目的之外的任何其他用途。我们使用cookie和同类技术主要为了实现以下功能或服务：

**1. 保障产品与服务的安全、高效运转**

我们可能会设置认证与保障安全性的cookie或匿名标识符，使我们确认您是否安全登录本平台，或者是否遇到盗用、欺诈及其他不法行为。这些技术还会帮助我们改进服务效率，提升登录和响应速度。

**2. 帮助您获得更轻松的访问体验**

使用此类技术可以帮助您省去重复您填写个人信息的步骤和流程。

**3. cookie的清除**

大多数浏览器均为用户提供了清除浏览器缓存数据的功能，您可以在浏览器设置功能中进行相应的数据清除操作。如您进行清除，可能因为这些修改，您可能无法使用依赖于cookie且由我们提供的服务或相应功能。

## 三、我们如何共享、委托处理、转移、公开披露您的个人信息

**1. 共享**

一般情况下，我们不会向其他任何公司、组织和个人提供您的个人信息，若我们需要向第三方共享您的个人信息的，我们将向您告知接收方的名称或者姓名、联系方式、处理目的、处理方式和个人信息的种类，并事先获得您的单独同意（根据法律法规规定无需取得您同意的情形除外）后对外提供您的个人信息，同时根据有关法律履行对外提供个人信息的其他义务。

**2. 委托处理**

我们可能委托授权合作伙伴处理您的个人信息，以便授权合作伙伴代表我们为您提供某些服务或履行职能。我们仅会出于本隐私政策声明的合法、正当、必要、特定、明确的目的委托其处理您的信息，授权合作伙伴只能接触到其履行职责所需信息。对于委托处理个人信息的场景，我们会与受托合作方根据法律规定签署相关处理协议，并对其个人信息使用活动进行监督。**我们将必要信息委托给支持我们业务的合作伙伴处理，这些支持包括受我们委托提供的产品代码和数据的服务器部署以及数据库存储服务、短信发送服务、内容安全审核服务、实名认证服务。**

**3. 转移**

随着我们业务的持续发展，我们将有可能进行合并、收购、资产转让，您的个人信息有可能因此而被转移。在发生前述变更时，我们将向您告知继受方的名称或者姓名和联系方式，并按照法律法规及不低于本隐私政策所载明的安全标准要求继受方继续履行个人信息处理者的义务，若继受方变更原先的处理目的、处理方式的，我们将要求继受方重新征得您的授权同意。

**4. 公开**

我们不会公开您的个人信息，除非遵循国家法律法规规定或者获得您的同意。我们公开您的个人信息会采用符合行业内标准的安全保护措施。

**5. 请您理解，根据法律法规的规定，若基于上述第一条第10款中列明的情形，我们需要共享、转移、公开或以其他方式处理您的个人信息的，无须征得您的同意。**

## 四、我们如何存储个人信息

**1. 存储地点**

**我们依照法律法规的规定，将在境内运营过程中收集和产生的您的个人信息存储于中华人民共和国境内。目前，我们不会将上述信息传输至境外，如果我们向境外传输，会严格遵守中国的相关法律、监管政策，并会遵循相关国家规定或者征求您的同意。**

**2. 存储期限**

**我们仅在为提供本平台相关服务之目的所必需的期间内保留您的个人信息**，例如：手机号码：当您使用手机号码注册登录时，我们需要持续保留您的手机号码，以便于向您提供正常的服务、应对您可能的查询和客诉并保障您的账号和系统安全。

如果您注销账户、主动删除个人信息或超出必要的期限后，我们将对您的个人信息进行删除或匿名化处理，但以下情况除外：

* 遵从法律法规有关信息留存的要求。
* 出于财务、审计、争议解决等目的需要合理延长期限的。

## 五、我们如何保护个人信息的安全

1\. 我们非常重视您个人信息的安全，将努力采取合理的安全措施（包括技术方面和管理方面）来保护您的个人信息，防止您提供的个人信息被不当使用或未经授权的情况下被访问、公开披露、使用、修改、损坏、丢失或泄漏。

2\. 我们会使用不低于行业同行的加密技术、匿名化处理及相关合理可行的手段保护您的个人信息，并使用安全保护机制防止您的个人信息遭到恶意攻击。

3\. 我们会建立专门的安全部门、安全管理制度、数据安全流程保障您的个人信息安全。我们采取严格的数据使用和访问制度，确保只有授权人员才可访问您的个人信息，并适时对数据和技术进行安全审计。

**4. 尽管已经采取了上述合理有效措施，并已经遵守了相关法律规定要求的标准，但请您理解，由于技术的限制以及可能存在的各种恶意手段，在互联网行业，即便竭尽所能加强安全措施，也不可能始终保证信息百分之百的安全，我们将尽力确保您提供给我们的个人信息的安全性。**

**5. 您知悉并理解，您接入我们的服务所用的系统和通讯网络，有可能因我们可控范围外的因素而出现问题。因此，我们强烈建议您采取积极措施保护个人信息的安全，包括但不限于不将自己的账号信息透露给他人。**

6\. 我们会制定应急处理预案，并在发生用户信息安全事件时立即启动应急预案，努力阻止这些安全事件的影响和后果扩大。一旦发生用户信息安全事件（泄露、丢失）后，我们将按照法律法规的要求，及时向您告知：安全事件的基本情况和可能的影响、我们已经采取或将要采取的处置措施、您可自主防范和降低风险的建议、对您的补救措施。我们将及时将事件相关情况以推送通知、邮件、信函、短信及相关形式告知您，难以逐一告知时，我们会采取合理、有效的方式发布公告。同时，我们还将按照相关监管部门要求，上报用户信息安全事件的处置情况。

**7. 您一旦离开本平台，浏览或使用其他网站、服务及内容资源，我们将没有能力和直接义务保护您在本平台之外的软件、网站提交的任何个人信息，无论您登录、浏览或使用上述软件、网站是否基于本平台的链接或引导。**

## 六、您如何管理个人信息

我们非常重视您对个人信息的管理，并尽全力保障您对于您个人信息的查阅、复制、转移、更正、补充、删除、撤回同意授权、注销账号、对账户信息的生前安排、解释说明、投诉举报等权利，以使您有能力保障您的隐私和信息安全。

**1. 访问您的个人信息**

您可以在本平台页面查看您的账号信息，并在本平台相关页面查阅您的服务订阅/使用情况、套餐兑换/核销记录、充值及支付记录信息。

如果您希望访问您在使用本平台过程中产生的其他个人信息，可以通过本隐私政策中提供的联系方式与我们联系。

**2. 复制、转移您的个人信息**

您可以在StepFun开放平台复制您的API接口密钥信息，您还可以通过本隐私政策中提供的联系方式联系我们要求复制我们收集存储的您的其他个人信息。

您有权通过本隐私政策中提供的联系方式联系我们要求将您的个人信息转移至您指定的个人信息处理者，符合国家网信部门规定条件的，我们会提供转移的途径。

**3. 更正您的个人信息**

您使用本平台时，可在设置界面自主设置您的头像、昵称信息。

若您发现我们处理的关于您的个人信息有错误时，您有权对错误或不完整的信息作出更正或更新，您可以通过本隐私政策中提供的联系方式随时与我们联系。为保障安全，我们可能在您行使更正权前对您的身份进行验证。

**4. 删除您的个人信息**

在以下情形中，我们会主动删除个人您的个人信息，您也可以通过本隐私政策中提供的联系方式联系我们提出删除个人信息的请求：

* 处理目的已实现、无法实现或者为实现处理目的不再必要；
* 停止提供产品或者服务，或者保存期限已届满；
* 个人撤回同意；
* 违反法律、行政法规或者违反约定处理个人信息；
* 法律、行政法规规定的其他情形。

法律、行政法规规定的保存期限未届满，或者删除个人信息从技术上难以实现的，我们会停止除存储和采取必要的安全保护措施之外的处理。

**5. 改变或撤回授权范围**

您也可以通过本隐私政策中提供的联系方式联系向我们提出撤回同意或改变您授权同意的范围的请求。当您撤回同意后，我们将不再处理相应的个人信息。但您撤回同意的决定，不会影响此前基于您的授权而开展的个人信息处理活动。

**6. 注销账号**

您可以通过本平台自主申请注销账号，您也可以通过本隐私政策中提供的联系方式与我们联系申请注销您的账号，我们将会在收到您的申请后及时进行处理，并在15个工作日或法律法规要求的时限内回复您的请求。在您注销账号前，我们可能需要验证您的个人身份、安全状态、设备信息等。您知悉并理解，注销账号是不可逆的行为，当您注销账号后，我们将删除有关您的相关信息或进行匿名化处理，但法律法规另有规定的除外。

**7. 近亲属的权利**

根据相关法律要求，您可以提前就您的个人信息进行安排，您可以通过本隐私政策公布的联系方式与我们联系告知我们您的安排；如无另行安排，您的近亲属可以基于其合法、正当利益，通过本隐私政策中提供的联系方式与我们联系，对您身后的相关个人信息依照相关法律规定和本隐私政策的约定，行使查阅、复制、更正、删除等权利。

**8. 解释说明**

如您对我们的个人信息处理规则存在任何疑问，可以通过本隐私政策中提供的联系方式联系我们，要求我们进行说明、解释。

**9. 响应个人信息权利行使请求**

如果您或其他有权主体对相关法律法规赋予的个人信息权利的行使，有任何主张、要求或者疑问，您可以通过本隐私政策中提供的联系方式与我们联系，我们将尽快审核所涉问题，并在验证您的用户身份后的15个工作日内或其他法律法规明确规定的时限内回复。

**10. 意见反馈和投诉举报**

如果您有任何意见或您认为您的个人信息权利可能受到侵害，或者发现侵害个人信息权利的线索，您可以通过本隐私政策中提供的联系方式与我们联系以进行意见反馈、投诉举报。

**11. 停止运营并向您告知**

如我们停止运营，我们将及时停止处理您个人信息的活动，将停止运营的通知以逐一送达或公告的形式通知您，并对所持有的您的个人信息进行删除或匿名化处理。

## 七、未成年人信息保护

本平台不面向未成年人，我们不会主动收集或处理未成年人的个人信息。如果您是未成年人，请勿注册、使用本平台或向我们提供任何个人信息。如我们发现因误操作或其他原因收集了未成年人的个人信息，我们将及时删除或进行匿名化处理。如果未成年人的父母或其他监护人发现未成年人向我们提供了个人信息，可以通过本隐私政策载明的联系方式与我们联系，我们将在核实相关情况后及时予以删除。

## 八、隐私政策的修订和通知

1\. 为了给您提供更好的服务，本平台中的相关服务将不时更新与变化，我们会适时对本隐私政策进行修订，这些修订构成本隐私政策的一部分并具有等同于本隐私政策的效力，未经您明确同意，我们不会削减您依据当前生效的本隐私政策所应享受的权利。

**2. 本隐私政策更新后，我们会在本平台相关页面发出更新版本，并在更新后的条款生效前通过官方网站公告或其他适当的方式提醒您更新的内容，以便您及时了解本隐私政策的最新版本。**

## 九、联系我们

1\. 本平台由上海阶跃星辰智能科技股份有限公司提供，如果您对个人信息保护问题有投诉、建议、疑问，您可以通过[platform@stepfun.com](mailto:platform@stepfun.com)与我们联系，我们核查并验证您的用户身份后会及时反馈您的投诉与举报。

2\. 如对本隐私政策内容有任何疑问、意见或建议，您可通过[platform@stepfun.com](mailto:platform@stepfun.com)与我们联系。

3\. 我们还设置了个人信息保护负责人，负责对个人信息处理活动以及采取的保护措施等进行监督。您可以通过[platform@stepfun.com](mailto:platform@stepfun.com)与我们的个人信息保护负责人联系。

**十 、法律适用及争议解决**

**本隐私政策的执行、解释及争议解决均应适用中华人民共和国大陆地区法律。您和我们就本隐私政策内容或其执行发生任何争议的，应友好协商解决。如无法协商解决争议时，您同意应将争议提交上海阶跃星辰智能科技股份有限公司住所地的人民法院诉讼解决。**

**十一 、定义**

1\. 个人信息：指以电子或者其他方式记录的与已识别或者可识别的自然人有关的各种信息，不包括匿名化处理后的信息。

2\. 敏感个人信息：指一旦泄露或者非法使用，容易导致自然人的人格尊严受到侵害或者人身、财产安全受到危害的个人信息，包括生物识别、宗教信仰、特定身份、医疗健康、金融账户、行踪轨迹等信息，以及不满十四周岁未成年人的个人信息。

3\. 儿童：指不满十四周岁的未成年人。

4\. 匿名化：指个人信息经过处理无法识别到特定自然人且不能复原的过程。


# StepFun 开放平台用户协议
Source: https://platform.stepfun.com/docs/zh/agreement/userservice



**最新版本生效日期：2026年9月28日**

尊敬的用户，欢迎使用本平台！本协议适用于上海阶跃星辰智能科技股份有限公司（以下称“我们”或“公司”）通过StepFun开放平台、AI Studio平台等形式（统称“**本平台**”）向您提供的产品和服务。本协议为本公司与使用本平台的用户（如为个人用户，则指您本人；如为企业用户，则包括企业用户以及代表企业用户使用本平台的个人，以下统称“**您**”或“**用户**”）签署的具有合同效力的文件。

在使用本平台前，请您务必仔细阅读并理解本协议。本协议将为您介绍您在使用本平台及相关服务时所享有的权利、履行的义务和责任。请您认真阅读、充分理解各条款内容，**特别是免除或限制责任、争议解决等可能对您权益造成重大影响的条款，同时我们已为您以粗体字的形式予以提示**。

**请您知悉，当您主动勾选或点击确认本协议、或实际使用本平台相关服务时，即表示您与我们已就本协议达成一致，本协议具有合同效力。如果您不同意本协议的任意内容，或者无法准确理解我们对本协议条款的解释，请停止使用本平台及相关服务。否则，即表示您已接受本协议所述的所有条款及其适用条件，同意受本协议约束。如您代表您所在企业签署本协议、使用本平台相关服务，您应确保具备所需的一切授权及许可以使您有权代表您所在企业签署本协议及使用本平台相关服务。**

**您在开通、订阅、购买、访问或使用本平台项下任何具体服务时，我们就该等服务已经发布或后续发布的相关服务协议、服务规则、操作指引、产品说明、页面提示、公告通知及其他相关文件（以下统称“服务规则”），均构成本协议不可分割的组成部分，与本协议具有同等法律效力。您在使用相应服务时，应同时遵守前述文件的相关约定。**

## 1 服务与账户使用

1.1 服务内容

1.1.1 服务内容包括我们通过本平台向用户提供的模型及API技术服务以及基于您体验我们提供的模型和API能力的目的，而向您提供的智能对话、内容生成及AI助手等服务（以下或称“**本服务**”），具体服务内容以各项服务规则说明为准。本平台主要面向企业客户和成年人个人用户，本服务可用于用户日常工作、生活、学习等场合，提供用户日常所需的知识学习、信息检索、内容消费、人机互动、任务执行等服务。

1.1.2 请您知悉，本公司仅作为中立的技术服务提供者，向您提供本平台上的各类产品和服务。**您的网站、应用、软件、平台等任何产品、服务及相关内容等，由您自行运营。除本协议另有约定或我们另有明确许可外，您不得以任何形式将本平台提供的服务全部或部分出售、转让、出借、出租、分许可、转授权或以其他方式提供给任何第三方使用，否则，我们有权采取限制、暂停或终止服务等措施。**

1.1.3 您应确保您使用本服务，或进一步对外提供服务，已经依照所有适用法律法规的规定获得了合法经营资质或政府审批等（并在本协议有效期内保持长期有效），并持续按照《中华人民共和国网络安全法》《中华人民共和国数据安全法》《中华人民共和国个人信息保护法》《生成式人工智能服务管理暂行办法》《互联网信息服务深度合成管理规定》《互联网信息服务算法推荐管理规定》等相关法律法规要求，履行相关审核、标识、评估、备案、信息安全管理等义务。**若您违反本协议任一项承诺与保证的，包括但不限于在本协议签订时不具备开展业务所需的全部资质许可或未履行相关手续，或者在本协议有效期内丧失全部或部分资质许可的，我们有权中止或者终止向您提供服务，并不承担任何责任。**

1.1.4 请您知悉并同意，我们对本平台的部分或全部功能可能会收取费用。届时，请您根据我们公布的收费信息或者依据我们之间签署的其他相关协议，支付相应的费用。**未按约定支付相应的服务费用的，我们有权单方面不经通知暂停或终止提供服务，并删除您在本平台上所有的非法律法规要求的全部数据等，由此给您或您的最终用户造成任何损失的，由您自行承担。具体付款的账户信息和开票的信息，您可通过联系我们进行确认。无论您的账号是否被关停、限制使用等，您均需足额支付已使用服务的费用，同时，如果您存在欠费的情况，还应按法律允许的最大的违约利率承担违约责任并承担我们追索欠费的取证费、律师费等全部相关支出。**

1.1.5 **请您知悉并同意，为技术升级、服务体系升级、或因经营策略调整或配合国家重大技术、法规政策等变化，我们不保证永久提供某种服务或产品，并有权单方面变更所提供服务、产品的形式、规格等任何方面（如升级迭代产品、服务的价格和计费模式）或推出新的产品或服务，在终止该种服务或进行此种变更前，我们将尽最大努力且以提前发布公告或邮件通知等方式通知您，并且您需按照变更后的条件履行相关义务。对于更新或升级的服务、产品，除非相关内容是必须选择的，否则您可以自行选择是否升级，如果您不升级的，您将无法使用升级后的服务。**

1.1.6 **本平台中的部分服务依托于生成式人工智能等技术，生成内容仅供您参考，您不应将相关服务输出的内容作为专业建议、商业用途或用于其他目的。若涉及对您或者相关方可能会产生重大影响的情形（例如与医疗、财务、投资、保险、法律等有关的场景或目的），建议您咨询相关专业人士。相关服务的输出内容不应成为您进一步作为或不作为的依据，本平台中生成的相关内容为人工智能模型概率生成，不确保真实性，您须自行进行核实，特别是针对其中包含的数字、时间以及各类事实性描述等内容。您根据输出的内容所作出的任何判断或者据此作出的后续相关操作行为，所带来的后果和责任均由您自行承担，包括因对输出的内容的真实性、准确性、可靠性、不侵权或满足特定目的的依赖而产生的风险。**

1.2 账户使用

1.2.1 您需要按照本平台页面提示注册账号，并可能需根据具体服务场景完成个人实名认证、企业认证。实名认证的适用用户范围、适用服务或功能、认证方式、认证次数、同一身份可关联的账号数量及相关使用条件等，以平台届时展示的页面说明、服务规则或其他提示为准。

1.2.2 为保障平台及账号安全，核验用户个人或企业身份，并防止恶意注册、重复领取或不当获取平台权益以及其他滥用行为，**如您未完成或未通过相应认证，我们可能根据相关服务规则限制您使用相应的服务、功能或权益。完成认证后，我们可能基于认证结果识别和管理同一用户，并对相关账号、服务、额度、权益或使用资格等进行统一管理或限制**，包括对同一身份可关联的账号数量、一定时间内的认证次数等设置合理限制，以及防止通过多个账号重复获取权益、规避平台规则或实施其他滥用行为等。具体以平台届时相关页面说明、服务规则或其他提示为准。我们可能根据业务发展、安全管理或合规要求调整认证的适用范围及相关规则，并通过平台页面、站内通知或其他合理方式向您说明。

1.2.3 **请您妥善保管账号及密码、API Key等认证信息，因保管不善、违规共享或授权不当造成的风险、损失及责任，由您自行承担**。若用户账号或账号下行为出现纠纷时，由用户承担全部责任。

1.2.4 **仅限于您本人使用账号及密码，您不得以任何形式将账户转让、出借、出租或提供给其他第三方使用。**

1.2.5 若您发现任何非法使用用户账号的情况，应立即通知我们，我们将给予最大限度地配合和处理。**但对于用户因账号、密码、密钥或其他认证信息泄露造成的各种损失，由您自行承担法律责任。**

1.2.6 **若您违反适用的法律法规，或出现本协议约定情形的，我们有权终止向您提供服务并收回您的账户**。您也可以向我们提出注销账户请求，经我们审核同意，由我们注销该注册用户，用户即解除与我们的合作关系。但账户被收回或者注销后，我们仍有权：1）保留相关行为记录，但涉及个人信息的除外（如有）；2）对用户在使用本平台过程中存在违法行为或违反本协议的行为，行使本协议所约定的权利。

## 2 您的权利与使用限制

2.1 您的权利

2.1.1 您有权依据本协议的约定使用本平台及相关服务，我们亦有权根据技术和业务的发展增加或减少本服务内容。

2.1.2 您充分理解并同意，依据本协议，我们授予您一项可撤销的、不可转让的、非独占地合法使用本平台及相关服务的权利。您可以将本服务用于个人学习和研究、内部运营，也可以将本服务集成到您的产品中，向您的最终用户提供服务，具体的服务方式以我们实际提供的为准。

2.1.3 在法律允许的范围，您或您的最终用户基于本服务输入的文字、图片、音频、视频等内容（输入内容）的全部权利均仅归您或原作者所有，输入内容均不会因上传、发布等行为发生知识产权等权利的转移。**若您或您的最终用户输入他人享有知识产权等合法权利的内容，应当取得合法授权，确保不得侵害他人合法权利。**

2.2 使用限制

2.2.1 **您在使用本平台及相关服务时，应遵守法律法规、本协议及相关服务规则，并按照诚实信用、合法正当、合理必要的原则使用本平台及相关服务，不得实施任何可能影响本平台正常运营秩序、损害公司或第三方合法权益、规避本平台管理措施或超出本平台许可范围使用服务的行为。您应根据自身业务场景、技术能力和合规义务，合理控制调用频率、资源消耗、输出使用方式及风险后果，并对使用本平台相关服务的行为及结果承担责任。**

2.2.2 **为保障平台安全、服务稳定、交易秩序、资源公平分配及合规运营，我们有权基于自身风险控制判断，结合您的账户状态、调用行为、交易情况、投诉举报、异常指标、技术特征、业务场景或其他合理因素，对您的账户采取相应管理措施，包括但不限于限流、限制功能、限制调用频次、限制购买、暂停提供部分或全部服务、暂时冻结账号权限、要求补充材料、要求整改、终止服务或封禁账号。前述措施可在我们认为必要时即时采取，如情况允许，我们可视具体情形通知用户。**

2.2.3 **您应遵守所有适用的法律法规，遵守本协议、使用文档等相关协议、规则的约定，您不得以任何违法、侵害他人权利的方式使用本平台及相关服务，包括但不限于：**

1\) 对本平台进行渗透，以窃取模型、数据等资产或反汇编、反编译、翻译或以其他方式试图发现本服务的模型、算法和系统的源代码或底层组件或参数；

2\) 使用任何自动化或编程方法从本平台中提取数据或输出，包括爬虫、抓取、收集或提取数据；

3\) 未经授权，使用本服务和/或本服务的输出内容来研发与本平台相竞争的模型或服务，包括开发或训练任何人工智能或机器学习算法或模型等；

4\) 使用任何技术手段重现或复制本平台或相关服务；

5\) 删除、修改、遮掩或以其他任何方式替换本平台及相关服务中可能包含的我们相关的商业名称、商标、服务标记、域名或其合作伙伴其他明显的标志，删除本平台及相关服务中包含的任何版权声明、商标声明或其他所有权声明等；

6\) 使用本服务侵犯任何人权利（权益）或从事任何违反法律法规的行为，包括但不限于进行网络犯罪、生成虚假信息、侵犯第三方权益（包括但不限于著作权、专利权、商标权、肖像权等）、商业秘密等，利用算法、数据、平台等优势实施不公平竞争；

7\) 向我们发送或输入任何含有木马、病毒、恶意软件或任何其他有可能影响本平台及相关服务安全及稳定性的内容；

8\) 对本平台及相关服务采取任何攻击手段，包括但不限于诱导性的提问，或利用本平台及相关服务的功能去攻击其它服务、机构或侵入、干扰、破坏或限制本平台正常运行；

9\) 企图规避本平台的安全设置或网络系统，登录未经明确授权的服务器或账号，或采用运行端口扫描等方式窥探其他网络的安全措施；

10\) 利用或针对本平台相关服务从事诈骗、欺诈、误导或欺骗性活动；

11\) 其他任何违反法律法规规定或损害本平台及相关服务的行为。

2.2.4 **我们会根据《人工智能生成合成内容标识办法》及配套标准等监管规定，对AI生成合成的内容添加显式标识，并在生成合成内容的文件元数据中添加隐式标识。标识的具体样式和添加方式，根据产品场景有所不同。其中，显式标识的具体标识方法和样式例如在产品交互场景界面底部等适当位置或展示内容附近显示“AI生成”或类似提示文字。用户通过互联网传播相关内容时，应保持标识的准确性、完整性，任何组织和个人不得恶意删除、篡改、伪造、隐匿相关内容标识。**

2.2.5 您在从事与本平台服务相关的所有行为（包括但不限于访问浏览、利用、转载、宣传介绍）时，必须以善意且谨慎的态度行事；不得利用本平台及相关服务从事危害国家安全和社会公共利益、扰乱经济秩序和社会秩序、侵犯他人合法权益等法律、行政法规禁止的活动；**您不得利用本服务上传、生成或传播以下违反法律法规、政治相关、侵害他人合法权益的内容：**

1\) 反对宪法所确定的基本原则的；

2\) 危害国家安全，泄露国家秘密，颠覆国家政权，破坏国家统一的；

3\) 损害国家荣誉和利益的；

4\) 歪曲、丑化、亵渎、否定英雄烈士事迹和精神，以侮辱、诽谤或者其他方式侵害英雄烈士的姓名、肖像、名誉、荣誉的；

5\) 宣扬恐怖主义、极端主义或者煽动实施恐怖活动、极端主义活动的；

6\) 煽动民族仇恨、民族歧视，破坏民族团结的；

7\) 破坏国家宗教政策，宣扬邪教和封建迷信的；

8\) 散布谣言，扰乱经济秩序和社会秩序的；

9\) 散布淫秽、色情、赌博、暴力、凶杀、恐怖或者教唆犯罪的；

10\) 侮辱或者诽谤他人，侵害他人名誉、隐私、肖像、知识产权、商业秘密和其他合法权益的；

11\) 含有虚假、有害、胁迫、骚扰、侵害、中伤、粗俗、猥亵或其他道德上令人反感的内容；

12\) 中国法律、法规、规章、条例以及任何具有法律效力之规范所限制或禁止的其他内容。

2.2.6 **您使用本服务向公众提供服务时，还应当履行下列义务：**

1\) 遵守法律、行政法规，尊重社会公德和伦理道德，履行网络安全主体责任，保护个人信息、商业秘密等；

2\) 在您的产品上线前依照法律法规的规定开展安全评估、算法备案等工作；

3\) 对大模型生成内容的安全性、合法性、合规性等进行有效管理和控制，自行建立包括但不限于内容审核、用户管理、数据安全、监测预警和应急处置等制度或机制；

4\) 采取合理措施，包括与您的最终用户订立合法有效的协议等，确保本协议的约定同样适用于您的最终用户；

5\) 加强数据安全管理，采取必要措施保障数据安全，采取技术措施添加不影响用户使用的标识，并依照法律、行政法规和国家有关规定保存日志信息。在生成或者编辑的信息内容的合理位置、区域进行显著标识，向公众提示人工智能生成合成情况。

6\) 可适用的所有法律法规规定的其他义务。

2.2.7 **请您知悉，如我们发现您违反本协议的约定或利用本平台及相关服务从事违法犯罪活动的，我们有权依据自己的合理判断不经通知，采取警示、限制功能、暂停或者终止服务、封禁账号、删除相关内容等处置措施，保存有关记录，并向有关主管部门报告。由此而导致或产生的法律责任或第三方主张的任何索赔、要求或损失，您应当自行承担责任。因此给我们造成任何损失的，您也应当一并赔偿（包括我们维权所支出的诉讼费、公证费、公告费、律师费等费用）。**

2.2.8 您在使用本服务，或基于本服务进一步对外提供服务的，应当自行负责对您使用的计算机信息系统、设备等采取必要的、有效的安全保护措施并提供技术支持，**因您未采取相应措施导致您自身或任何第三方权益受损的，由您自行承担责任**。

2.2.9 **为确保服务安全性及合规性，您不应将本服务用于金融数据相关大模型技术合作（如将服务应用于向银行、证券公司、保险公司、信托投资公司和基金管理公司等金融机构提供数据分析、投资研究、投资顾问或投资者教育等服务）。如您就金融数据相关的技术合作有进一步需求，请通过[feedback@api.stepfun.com](mailto:feedback@api.stepfun.com)联系我们。**

2.2.10 **除上述约定外，您在使用本产品及相关服务的过程中，还应遵循公司制定的《平台管理规则及公约》的相关内容。**

## 3 服务的暂停、中断或终止

3.1 我们将全力保障在现有技术上维护本平台及相关服务的正常运行，并努力提升和改进技术，使用户的使用活动得以顺利进行；**但我们有权基于业务调整或风险管控的需要，暂停、中断或终止向您提供本平台相关服务**。

3.2 为保证服务的安全性和稳定性，我们可能进行设备更换等重大调整，因此**本平台相关服务可能在合理期间内中断或暂停，您知悉并同意该等情况下我们无须向您承担任何责任，我们会尽合理努力提前向您通知该等调整事宜，您应当予以配合。**

3.3 **我们有权对用户是否涉嫌违反本协议的约定予以认定，并有权根据认定结果中止、终止对用户的使用许可或采取其他依本协议约定可采取的限制措施。**

3.4 **若您的最终用户对本服务的相关使用行为违反法律法规规定或违反本协议任何约定的，我们有权基于自身判断要求您停止向该最终用户提供服务，或者暂停或终止向您提供本平台相关服务，而不承担任何责任。**

3.5 **我们有权根据自身安全管控规则对您使用本平台服务的行为进行合理监控，若您的使用行为违反法律法规的规定；或触发本平台安全、风控、反欺诈或反滥用机制；或存在其他账户异常情形，我们有权暂停、中断或终止向您提供服务，或对您使用的服务进行限制，对此我们不承担任何责任，但法律另有规定的除外。**

3.6 **若我们按照适用法律规定终止提供服务，或出现本协议约定的服务终止情形的，对于您存储在我们服务中的数据等任何信息（如有），在法律法规允许的范围内，我们有权在服务终止后或在我们与您另行约定的保留期限（如有）届满后，删除上述信息，请您自行提前保存、迁移相关数据信息。**

## 4 责任范围与免责声明

4.1 **我们仅在本协议中列明的责任承担范围内承担相应责任。**

4.2 **您对自己使用本平台及相关服务的一切行为及由此产生的一切结果负责，包括但不限于您所提供的任何服务、发表的任何内容、以及由此产生的任何后果。您应承担因使用本平台及相关服务而引起的所有风险，本平台及相关服务中提供的内容，应仅供您参考，不构成任何建议或承诺，我们不承担您因使用本平台及相关服务给您或任何第三方产生的任何损害或责任。**

4.3 **若您基于本服务进一步向您的最终用户提供服务的，您应当对最终用户对服务的使用行为负责，确保每个最终用户对服务的使用遵守本协议的约定，包括但不限于确保最终用户基于本服务上传、发布或者传输的内容合法合规，不存在任何违法或不良信息、不侵害任何第三方的知识产权等合法权益、不侵犯任何第三方的个人信息权益等。**

4.4 **在法律允许的情况下，我们对于与本协议有关或由本协议引起的任何间接的、惩罚性的、特殊的、派生的损失（包括业务损失、收益损失、利润损失或其他经济利益的损失），不论是如何产生的，也不论是由对本协议的违约（包括违反保证）还是由侵权造成的，均不负有任何责任。**

4.5 **您理解并同意，本平台是按照现有技术和条件所能达到的现状提供的。我们尽最大努力确保服务的连贯性和安全性，但并不能保证其所提供的服务毫无瑕疵，也无法随时预见和防范法律、技术以及其他风险。不论在何种情况下，我们均不对由于网络连接故障，电力故障，罢工，劳动争议，暴乱，起义，骚乱，火灾，洪水，风暴，爆炸，不可抗力，战争，政府行为，国际、国内法院的命令，黑客攻击，互联网病毒，网络运营商技术调整，政府临时管制或任何其他不能合理控制的原因而造成的本平台不能访问、服务中断、信息及数据的泄露、延误、停滞或错误，不能提供或延迟提供服务而承担责任。**

4.6 **您理解并同意，当本平台提供的内容包含来自第三方插件、第三方网站的内容时，我们并不对这些内容的有效性负责，且不保证从这些途径获取的任何内容、产品、服务或其他材料的真实性、合法性、安全性。您应慎重辨别这些内容的合法性、准确性、真实性、适用性、完整性和安全性，并采取谨慎的预防措施。如您不确定这些内容是否合法、准确、真实、实用、完整和安全，建议您先咨询专业人士。在法律允许的范围内，我们不承担您使用任何第三方信息或链接所引致的任何人身和财产损失（包括但不限于因下载而感染电脑病毒、名誉或商誉诽谤、版权或知识产权等权利的损失）。**

4.7 **您在使用本平台过程中，您可能会授权本平台访问、调用某些第三方工具。请您知悉，这些第三方工具不受我们控制，我们不对第三方工具的内容及其所提供的服务的准确性、完整性或合法性承担任何责任。您应自行判断第三方工具的真实性和可靠性，并自行承担指示本平台访问、调用第三方工具所产生的后果。我们建议您仅选择使用您信任的第三方工具。**

## 5 知识产权

5.1 **除本协议另有明确约定外，与本平台相关的一切著作权、商标权、专利权、商业秘密等知识产权均受法律法规保护，由我们及其关联方享有完整的知识产权、所有权等合法权利。用户有权依照本协议约定合法使用本平台及本平台相关内容。**

5.2 **对于您使用本平台提供的相关生成式人工智能服务而输出的内容，在适用法律允许的范围内，输出的内容的知识产权及产生的其他财产权益（如有）归属于您或适用法律规定的权利人。**

5.3 您理解并且同意，**对于您发布上传或传输的内容，您授予我们一项免费且无需标注个人身份的、在法律允许范围内合理且最大程度的许可使用（包括但不限于存储、使用、复制、修订、编辑等）的权利，以为实现本协议目的、提升大模型服务体验进行使用。**

5.4 **除非法律另有规定或本协议另有约定，本平台运行过程中所产生的一切数据由我们享有合法权利，未经我们事先同意，任何人不得为本协议约定之外的目的获取、使用前述数据，亦不得以任何形式将前述数据提供给他人。**

5.5 未经我们许可，请不要擅自使用本平台及我们相关的任何商标、服务标记、商号、域名、网站名称、URL或其他显著品牌特征等，不得将本条款前述标识以单独或结合任何方式展示、使用或申请注册商标、进行域名注册等，也不得实施向他人明示或暗示有权展示、使用、或其他有权处理该等标识的行为。

5.6 **您保证在使用本平台过程中没有侵犯任何第三方知识产权的行为；若您违反上述约定，我们有权按照本条及本协议之其他相关约定终止您全部或部分服务；由此导致我们和/或第三方损失的，由您自行承担责任。**

5.7 **您同意在合作期间，我们有权使用您或您企业的名称、品牌等作为商业案例进行宣传、展示。**

5.8 本条款在本协议终止后对本协议各方仍继续有效。

## 6 数据和个人信息保护

6.1 **我们提供本服务时可能需要您提供一定的个人信息，具体请参见我们《StepFun平台隐私政策》的约定，我们会根据该等隐私政策的说明处理和保护您的个人信息。**

6.2 **您使用本服务向最终用户提供服务的过程中可能涉及到收集使用最终用户的个人信息，该等情况下，您作为最终用户个人信息的处理者应当履行个人信息处理者的相关法定义务。为了确保个人信息的保护，您应建立健全的个人信息保护相关制度，采取适当的措施，并按照所适用的法律法规的要求保护用户个人信息。您应根据所提供的服务、行业监管要求以及所涉及的个人信息类别采取适当的数据保护措施，确保所涉及的个人信息的安全，避免个人信息泄露、被破坏、未经授权或者超出授权使用，并在停止提供服务后，及时主动删除最终用户的个人信息（除法律法规另有规定外）。同时，您应采取相应措施保障个人信息主体的权利，以符合所适用的法律法规的要求。**

6.3 **您应当建立健全的信息生态治理机制、网络信息安全责任制度和信息发布审查制度，对最终用户通过指定软件以及使用本服务所发布的信息进行审查，并及时处理最终用户发布违规信息的事件。**

6.4 **您使用本服务时，向我们传输的任何信息，如涉及到个人信息和其他数据的，必须充分取得相关主体的明示同意和授权，并确保我们不会因为处理相关数据和个人信息遭受任何损失和投诉，否则相关纠纷和赔偿责任由您向第三方或国家主管机关承担责任（包括但不限于直接经济损失、间接经济损失、相关罚款和费用等），并需赔偿给我们造成的一切损失。您需进一步承诺**：

(1) **处理最终用户个人信息的过程中，遵守可适用的法律法规和国家规范性文件，包括但不限于《中华人民共和国网络安全法》《中华人民共和国数据安全法》《中华人民共和国个人信息保护法》等。**

(2) **向最终用户告知对应的个人信息处理目的、处理方式和个人信息种类等信息，并获取最终用户的授权同意。**

(3) **已向最终用户提供易于操作的用户权利实现机制，包括告知最终用户如何行使知情、查阅、复制、更正、删除、补充、转移等可适用法律法规要求的各项权利。**

6.5 **您特此授权我们在为您提供服务期间或者为提供、诊断、改善、优化、升级本服务之目的使用、处理您使用本平台服务产生的相关数据（如涉及），我们承诺采取相应的合理的安全、保密措施进行保护，如采取脱敏、匿名、假名、加密等技术措施。如遇到履行法定义务、社会公众利益等情况时，我们会向监管部门提供相关数据，但会在合理的时间向您进行通知。**

## 7 意见反馈

如您对本平台及相关服务有任何意见、建议，或希望向我们进行投诉、举报的，可以通过[feedback@api.stepfun.com](mailto:feedback@api.stepfun.com)与我们联系，向我们进行如实反馈，并提供相应的证明材料。我们对您的意见高度重视并依法采取处理措施。

## 8 本协议的修改

**我们依据国家政策法律变化、技术进步、产品功能变更等有权根据变化适时或必要时对本协议条款内容做出修改，我们将以合理的方式通知您。如您不同意对本协议条款所做的修改，您有权停止使用本平台及相关服务，如您继续使用本平台及相关服务，则视为您接受修改后的条款。**

## 9 法律与管辖

**本协议根据中华人民共和国大陆法律法规制定，受中华人民共和国大陆法律法规管辖。因本协议而发生的任何争议应提交至公司住所地的人民法院诉讼解决。**

## 10 其他条款

10.1 您在使用本平台过程中，涉及任何第三方提供的产品或服务时，我们和第三方对可能出现的纠纷在法律规定和约定的范围内各自承担责任；同时，您还须遵守第三方的用户协议或使用协议。

10.2 本协议中的标题仅为方便阅读而设，并不影响本协议中任何规定的含义或解释。本协议各自部分的效力相互独立，部分条款的无效或终止不影响其他部分的效力。

10.3 **我们因经营策略调整或公司合并、分立、收购、资产转让时，在提前30天通过发布公告或邮件通知等方式书面通知您后，我们有权单方将本协议部分或全部权利义务转让给第三方。**

10.4 **您和公司均是独立的主体，在任何情况下本协议不构成公司对您的任何形式的明示或暗示担保，双方之间亦不构成代理、合伙、合营或雇佣关系。**

10.5 本协议条款无论因何种原因部分无效，其余条款仍有效且对双方具有约束力。


# 常见问题
Source: https://platform.stepfun.com/docs/zh/faq/common-questions



## 接口支持

### 是否会开放类似跃问的文件内容提取的接口？

目前阶跃星辰已为开发者提供了文件解析能力，可以参考[文件解析](/docs/zh/guides/developer/doc-parser)文档使用。

### 是否会开放类似跃问的搜索接口？

目前阶跃星辰为开发者提供了以下搜索接入方式，按需选择：

* **网页搜索 API**：`POST /v1/search`，与对话模型解耦。`step-5-preview` 请使用这种方式，详见 [网络搜索](/docs/zh/guides/developer/web-search)。
* **内置 Web Search 工具**：仅部分模型可在 Chat Completions 的 `tools` 中调用；`step-5-preview` 不支持。
* **StepSearch MCP Server**：基于 Model Context Protocol 的远程搜索服务，面向 Claude Code、Cline、OpenCode 等兼容 MCP 的客户端，无需本地安装，详见 [StepSearch](/docs/zh/guides/developer/search-mcp)。

### 是否兼容 Langchain 或者 OpenAI

兼容，可以直接使用 Langchain 或者 OpenAI 的 SDK 调用。您可以参考 [从 OpenAI 迁移至阶跃星辰](/docs/zh/guides/developer/openai) 完成迁移。

## 账号相关

### 个人充值能否开企业抬头的发票？

个人微信充值的订单，进行企业认证后可以开企业抬头发票。

### 如何完成个人实名认证？

个人实名认证通过支付宝完成人脸识别核验，操作步骤见[个人实名认证](/docs/zh/quickstart/real-name-verification)。

### 个人实名认证一直失败怎么解决？

请提交[工单](https://platform.stepfun.com/ticket)联系技术支持。

### 一个实名身份可以认证多个账号吗？

同一个实名身份最多可以用于两个账号的实名认证。

### 个人实名认证次数达到上限后如何处理？

平台限制 24 小时内最多认证 10 次。达到上限后，请等待 24 小时，系统会自动解除限制；您也可以进入工单系统反馈认证问题。

### 不进行实名认证会影响使用吗？

使用免费套餐的用户需要完成实名认证才能继续使用。所有用户在付费前都需要完成实名认证。

### 如何进行企业认证？

企业认证通过企业信息核验与对公账户小额打款验证完成，所需材料与操作步骤见[企业认证](/docs/zh/guides/organization/verification)。

### 企业认证后能否转为个人账号？

目前还未支持该功能，如有强烈诉求请扫描官网首页底部的二维码加入开发者交流群，联系客服处理。

### 企业认证后还能通过个人微信充值么？

认证为企业账户后，仍然可以进行个人微信充值。已进行企业认证的账户进行个人充值后，只能开具企业抬头发票。

### 企业认证后可以换绑手机号么？

该功能已在规划进行中，预计近期上线。

### 怎么提高账号的请求限制？

为了整体资源分配的公平性，我们会根据您拥有的账户累计充值金额实施相应的速率限制策略。详情请参见[API 速率限制](/docs/zh/guides/pricing/rate-limits#阶梯限速)。

### 充值金额是否有使用时限？

目前没有使用时限，请放心使用。

## 其他

### 怎样获取大模型或应用相关协议/合同？

请扫描官网首页底部的二维码加入开发者交流群，联系客服获取。


# 基本概念
Source: https://platform.stepfun.com/docs/zh/guides/basic-concepts



## 关键概念

### 文本大模型

> 文本大模型，例如 `step-5-preview`，基于生成式人工智能技术，通过在大量数据上进行训练，以理解和生成自然语言。

**文本大模型可以用于但不限于以下任务：**

* **内容生成**：生成文章、故事、对话等。
* **代码生成**：根据描述生成代码片段。
* **摘要**：将长篇文章或文档缩减为简短的摘要。
* **翻译**：将一种语言翻译成另一种语言。
* **问答**：回答各种问题，从简单的事实查询到复杂的推理问题。
* **创意写作**：创作诗歌、歌词或其他形式的创意文本。
* **语言理解**：进行情感分析、文本分类等。
* **对话系统**：与用户进行自然语言对话，模拟聊天机器人或虚拟助手。

使用这些模型时，通常需要提供一个 `prompt`，即一段引导性的文本，它告诉模型需要执行的任务类型以及相关的上下文信息。设计一个有效的 `prompt` 是至关重要的，因为它直接影响到模型输出的质量和相关性。

### 多模态大模型

> 多模态大模型，在文本大模型基础上，增加了对多种模态（如图像、音频、视频等）数据的处理能力，如 `step-5-preview` 和 `step-3.7-flash`，目前能够理解处理文本、图像与视频。
> 多模态大模型的核心优势在于更符合人类认知世界的习惯，因为人类通过多种感官接收多模态信息，这些信息通常是互补和协同的，使用多模态大模型可以更好地理解这些信息以及进行推理。

**多模态大模型可以用于但不限于以下任务：**

* **图像到文本的翻译**：为图像生成描述性文本。
* **对话系统**：结合文本和图像信息回答复杂问题。
* **创作**：根据图像和文本创作文学作品。
* **医疗影像诊断**：结合医学影像（如 X 光片、MRI 图像）和病人的病历文本，多模态模型可以帮助医生更准确地诊断疾病。
* **搜索引擎**：搜索引擎可以利用多模态技术来理解用户的查询意图，结合文本、图像，提供更相关的搜索结果。
* **自动驾驶**：自动驾驶汽车可以使用多模态模型来处理来自多个传感器（如摄像头、雷达、激光雷达）的数据，以更好地理解周围环境并做出驾驶决策。

### Context 长度

> **Context 长度**指的是在自然语言处理任务中，模型在生成响应或进行预测时所考虑的输入文本的 Token 数量。这个长度限制了模型单次处理信息的范围。

**重要性**

* **效果影响**：Context 长度决定了模型能够记忆和处理的信息量，影响其理解和生成文本的效果。
* **性能影响**：较大的 Context 长度可以提高模型的准确性，但同时也会增加计算资源的消耗。
* **费用影响**：开发者需要在效果和成本之间做出权衡，较长的 Context 如下应用场景中所述可能提高效果，但也会增加使用成本。

**应用场景**

* **对话系统**：在对话系统中，Context 长度影响对话的连贯性和上下文理解。
* **创作**：在文学创作中，较长的 Context 长度可以生成更连贯和逻辑性更强的文本。
* **学术论文和研究**：学术论文通常很长，包含大量的背景信息、实验数据和详细讨论，较长的 Context 长度可以帮助模型更好地理解和总结这些文档。
* **小说和文学作品**：对于文学作品的分析和理解，较长的 Context 长度可以帮助模型捕捉到故事的情节发展和角色之间的关系。

### Token

> 在文本大模型中，Token 是处理文本的基本单位，它代表了文本中的一个有意义的字符序列。Token 可以是单个字符、单词、短语，甚至是句子，具体取决于模型的设定和训练数据的特点。在中文文本中，Token 的划分尤为关键，因为中文字符不像英文那样以空格分隔单词，而是以单个汉字或汉字组合来表达意思。

**Token 的长度**

* **汉字与 Token 的关系**：一般而言，一个 Token 大约相当于 1.5 到 2 个汉字。这个比例是根据模型对中文文本的常规处理方式得出的，但实际的 Token 数量可能会因文本内容的不同而有所变化。

**模型的上下文长度限制**

* **最大上下文长度**：文本模型在处理输入（Input）和输出（Output）时，需要遵守模型的最大上下文长度限制。这意味着输入和输出的 Token 总数不能超过模型设定的最大值。
* **长度限制的重要性**：这一限制确保了模型能够有效地处理信息，避免因处理过长文本而导致的性能下降或错误。

**实际应用中的考量**

* **文本长度的规划**：在实际应用中，需要根据模型的最大上下文长度来规划文本的长度，以确保文本能够被模型完整地理解和生成。
* **Token 优化**：在某些情况下，可能需要对文本进行优化，比如通过减少不必要的 Token 或者重新组织文本结构，以适应模型的上下文长度限制。

### 速率限制

> 速率限制是确保服务稳定性和公平性的重要机制，它通过限制用户在特定时间内可以发起的请求数量来工作。以下是速率限制的3种主要衡量方式：

**RPM (每分钟请求数)**: RPM 限制是基于时间的，它规定了用户在一分钟内可以发起的请求数量。例如，如果 RPM 限制是20，那么用户在任何连续的一分钟时间段内最多只能发起20个请求。

**TPM(每分钟 Token 数)**: TPM 限制同样是基于时间的，但它衡量的是用户在一分钟内可以传输的 Token 数量。Token 通常是指请求以及响应中的数据单位，如果用户的请求非常简短，即使在一分钟内发起了很多请求，也可能不会达到 TPM 限制。

**并发数(同时在线请求数)**: 并发 限制基于同一时刻在线的推理请求数量。例如，如果并发限制是20，那么同时在线的请求数量最多只能是20个，超过并发限制的请求会被拒绝，除非旧的推理请求被处理完毕，新的推理请求才会被允许进入模型推理。

**速率限制的触发**: 速率限制可能会在以上任何一种选项中达到，具体取决于哪种限制先被触发。例如：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
假如当前用户的速率限制规则RPM是20，TPM是200K，如果用户向 `ChatCompletions` 发送了20个请求，每个请求包含100个 Token，
即使TPM未达到200K，但是由于RPM已经达到20，也会触发速率限制
```


# 联系我们
Source: https://platform.stepfun.com/docs/zh/guides/contact-us



## 开放平台客服

扫描以下二维码添加开放平台客服微信：

![客服微信](https://static-openapi.stepfun.com/static/platform-docs/resource/step-wechat-person-qrcode.webp)

## 开发者交流群

扫描以下二维码加入开发者交流群：

![开发者交流群](https://static-openapi.stepfun.com/static/platform-docs/resource/step-wechat-group-qrcode.webp)


# 语音对话
Source: https://platform.stepfun.com/docs/zh/guides/developer/audio-chat



阶跃星辰端到端语音模型支持在对话过程中传入音频内容，并生成语音回复。用户可以通过 Chat Completion API 发送语音输入，模型会同时返回文本和音频响应，实现真正的语音到语音交互体验。

> [!NOTE]
>
> 推荐使用 `step-audio-2` 或 `step-audio-2-mini` 模型，这些模型具备最新的语音理解和生成能力。`step-audio-r1.5` 具有出色的声音理解与推理能力，能够并行边想边说，适合需要高精度语音理解的场景。

## 能力概述

* **语音输入理解**：支持用户通过语音提问，模型可以理解语音中的内容和语调
* **语音输出生成**：模型可以直接生成语音回复，无需额外的 TTS 步骤
* **多种声音选择**：支持多种预置声音风格，满足不同场景需求
* **流式输出**：支持流式返回音频数据，实现低延迟的语音交互
* **工具调用**：支持用户自定义函数调用（`step-audio-r1.5` 模型不支持）

## 核心参数

在调用 chat completions 接口时，指定 model 为以下模型，可以获得语音回复能力。

| 模型名称 | 说明 |
| - | - |
| `step-audio-r1.5` | 超强语音理解与推理模型，理解各类声音与文字，边想边说，推理能力出众 |
| `step-audio-2` | 最新的端到端语音模型，支持语音输入输出、toolcall，支持音色复刻（realtime 接口） |
| `step-audio-2-mini` | 轻量版端到端语音模型，轻便快速 |
| `step-1o-audio` | 上一代语音模型，音色多样 |

### audio 参数

`audio` 参数用于控制音频输出，只在端到端语音模型下生效。

* `voice` `string` ***required***\
  指定生成音频的声音 ID。对于 `step-audio-2` 系列模型，可用以下声音：

  * `wenrounansheng`（温柔男声）
  * `qingchunshaonv`（青春少女）
  * `livelybreezy-female`（活力少女）
  * `elegantgentle-female`（高雅女声）

  对于 `step-1o-audio` 和 `step-audio-r1.5` 模型，可通过[获取声音列表接口](/docs/zh/api-reference/audio/list-voice)查询可用的声音 ID。

* `format` `string` ***required***\
  指定生成音频的格式：
  * `wav`：在非流式场景下（stream=false）支持
  * `pcm`：在流式场景下（stream=true）使用，格式为 24kHz、单声道、16bit

### modalities 参数

`modalities` 参数指定输出的模态类型，支持 `text`、`audio` 两种类型。

如果需要模型输出音频，则需要将 `audio` 添加到该参数中，例如：`["text", "audio"]`。

## 快速开始

### 文本输入，语音输出

最简单的使用方式是发送文本消息，让模型返回语音回复。

**python**

```python copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import base64
from openai import OpenAI

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

completion = client.chat.completions.create(
    model="step-audio-2",
    modalities=["text", "audio"],
    messages=[
        {
            "role": "system",
            "content": "你是一个老北京大爷，喜欢用京片子和用户聊天。",
        },
        {
            "role": "user",
            "content": "今儿个北京的天气咋样啊？",
        }
    ],
    audio={
        "voice": "wenrounansheng",
        "format": "wav",
    },
    stream=False,
)

# 获取文字回复
print(completion.choices[0].message.audio.transcript)

# 保存音频文件
with open("response.wav", "wb") as f:
    f.write(base64.b64decode(completion.choices[0].message.audio.data))
# 打开 response.wav 即可收听音频回复
```

**js**

```js copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";
import fs from "fs";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1",
});

async function main() {
    const completion = await openai.chat.completions.create({
        model: "step-audio-2",
        modalities: ["text", "audio"],
        messages: [
            {
                "role": "system",
                "content": "你是一个老北京大爷，喜欢用京片子和用户聊天。",
            },
            {
                "role": "user",
                "content": "今儿个北京的天气咋样啊？",
            }
        ],
        audio: {
            voice: "wenrounansheng",
            format: "wav",
        },
        stream: false,
    });

    // 获取文字回复
    console.log(completion.choices[0].message.audio.transcript);

    // 保存音频文件
    fs.writeFileSync("response.wav", Buffer.from(completion.choices[0].message.audio.data, 'base64'));
    // 打开 response.wav 即可收听音频回复
}

main();
```

**curl**

```bash copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-audio-2",
    "modalities": ["text", "audio"],
    "messages": [
      {
        "role": "system",
        "content": "你是一个老北京大爷，喜欢用京片子和用户聊天。"
      },
      {
        "role": "user",
        "content": "今儿个北京的天气咋样啊？"
      }
    ],
    "audio": {
      "voice": "wenrounansheng",
      "format": "wav"
    },
    "stream": false
  }'
```

### 语音输入，语音输出

支持用户通过语音提问，模型返回语音回复，实现端到端的语音对话。

**python**

```python copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import base64
from openai import OpenAI

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

# 读取本地音频文件并转换为 base64
with open("question.wav", "rb") as f:
    audio_data = base64.b64encode(f.read()).decode('utf-8')

completion = client.chat.completions.create(
    model="step-audio-2",
    modalities=["text", "audio"],
    messages=[
        {
            "role": "system",
            "content": "你是一个动物声音识别专家，请根据用户提供的声音进行识别和回答。",
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "听听这是什么声音？",
                },
                {
                    "type": "input_audio",
                    "input_audio": {
                        "data": f"data:audio/wav;base64,{audio_data}",
                    }
                }
            ],
        }
    ],
    audio={
        "voice": "qingchunshaonv",
        "format": "wav",
    },
    stream=False,
)

# 获取文字回复
print(completion.choices[0].message.audio.transcript)

# 保存音频文件
with open("response.wav", "wb") as f:
    f.write(base64.b64decode(completion.choices[0].message.audio.data))
```

**js**

```js copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";
import fs from "fs";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1",
});

// 从 URL 下载音频并转换为 base64
const downloadAudioAsBase64 = async (url) => {
    const response = await fetch(url);
    const arrayBuffer = await response.arrayBuffer();
    const buffer = Buffer.from(arrayBuffer);
    return "data:audio/wav;base64," + buffer.toString('base64');
}

async function main() {
    const completion = await openai.chat.completions.create({
        model: "step-audio-2",
        modalities: ["text", "audio"],
        messages: [
            {
                "role": "system",
                "content": "你是一个动物声音识别专家，请根据用户提供的声音进行识别和回答。",
            },
            {
                "role": "user",
                "content": [
                    {
                        type: "text",
                        text: "听听这是什么声音",
                    },
                    {
                        type: "input_audio",
                        input_audio: {
                            data: await downloadAudioAsBase64("https://stepchat-static.tos-cn-shanghai.volces.com/resource_tmp/cat-meow.wav"),
                        }
                    }
                ],
            }
        ],
        audio: {
            voice: "qingchunshaonv",
            format: "wav",
        },
        stream: false,
    });

    // 获取文字回复
    console.log(completion.choices[0].message.audio.transcript);

    // 保存音频文件
    fs.writeFileSync("response.wav", Buffer.from(completion.choices[0].message.audio.data, 'base64'));
}

main();
```

## 流式语音输出

当 `stream=true` 时，API 会以流式方式返回音频数据，实现超低延迟的语音交互体验。

**python**

```python copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import base64
import struct
from openai import OpenAI

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

completion = client.chat.completions.create(
    model="step-audio-2",
    modalities=["text", "audio"],
    messages=[
        {
            "role": "user",
            "content": "请用温柔的语气给我讲一个睡前故事",
        }
    ],
    audio={
        "voice": "elegantgentle-female",
        "format": "pcm",  # 流式场景下使用 pcm 格式
    },
    stream=True,
)

audio_chunks = []
transcript = ""

for chunk in completion:
    delta = chunk.choices[0].delta

    # 处理音频数据
    if hasattr(delta, 'audio') and delta.audio:
        if hasattr(delta.audio, 'data') and delta.audio.data:
            audio_chunks.append(base64.b64decode(delta.audio.data))
        if hasattr(delta.audio, 'transcript') and delta.audio.transcript:
            transcript += delta.audio.transcript
            print(delta.audio.transcript, end="", flush=True)

print("\n\n完整文字回复:", transcript)

# 合并所有 PCM 数据
pcm_data = b''.join(audio_chunks)

# 生成 WAV 文件头（24kHz，单声道，16bit）
def create_wav_header(pcm_size, sample_rate=24000, channels=1, bits_per_sample=16):
    byte_rate = sample_rate * channels * bits_per_sample // 8
    block_align = channels * bits_per_sample // 8
    return struct.pack(
        '<4sI4s4sIHHIIHH4sI',
        b'RIFF',
        36 + pcm_size,       # 文件大小 - 8
        b'WAVE',
        b'fmt ',
        16,                   # fmt chunk 大小
        1,                    # 音频格式 (1 = PCM)
        channels,
        sample_rate,
        byte_rate,
        block_align,
        bits_per_sample,
        b'data',
        pcm_size
    )

# 保存为 WAV 文件
with open("response.wav", "wb") as f:
    f.write(create_wav_header(len(pcm_data)))
    f.write(pcm_data)
# 打开 response.wav 即可收听音频回复
```

**js**

```js copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";
import fs from "fs";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1",
});

// 生成 WAV 文件头（24kHz，单声道，16bit）
function createWavHeader(pcmSize, sampleRate = 24000, channels = 1, bitsPerSample = 16) {
    const byteRate = sampleRate * channels * bitsPerSample / 8;
    const blockAlign = channels * bitsPerSample / 8;
    const header = Buffer.alloc(44);

    header.write('RIFF', 0);
    header.writeUInt32LE(36 + pcmSize, 4);
    header.write('WAVE', 8);
    header.write('fmt ', 12);
    header.writeUInt32LE(16, 16);           // fmt chunk 大小
    header.writeUInt16LE(1, 20);            // 音频格式 (1 = PCM)
    header.writeUInt16LE(channels, 22);
    header.writeUInt32LE(sampleRate, 24);
    header.writeUInt32LE(byteRate, 28);
    header.writeUInt16LE(blockAlign, 32);
    header.writeUInt16LE(bitsPerSample, 34);
    header.write('data', 36);
    header.writeUInt32LE(pcmSize, 40);

    return header;
}

async function main() {
    const completion = await openai.chat.completions.create({
        model: "step-audio-2",
        modalities: ["text", "audio"],
        messages: [
            {
                "role": "user",
                "content": "请用温柔的语气给我讲一个睡前故事",
            }
        ],
        audio: {
            voice: "elegantgentle-female",
            format: "pcm",  // 流式场景下使用 pcm 格式
        },
        stream: true,
    });

    const audioChunks = [];
    let transcript = "";

    for await (const chunk of completion) {
        const delta = chunk.choices[0].delta;

        // 处理音频数据
        if (delta.audio) {
            if (delta.audio.data) {
                audioChunks.push(Buffer.from(delta.audio.data, 'base64'));
            }
            if (delta.audio.transcript) {
                transcript += delta.audio.transcript;
                process.stdout.write(delta.audio.transcript);
            }
        }
    }

    console.log("\n\n完整文字回复:", transcript);

    // 合并 PCM 数据并保存为 WAV 文件
    const pcmData = Buffer.concat(audioChunks);
    const wavHeader = createWavHeader(pcmData.length);
    fs.writeFileSync("response.wav", Buffer.concat([wavHeader, pcmData]));
    // 打开 response.wav 即可收听音频回复
}

main();
```

流式返回的音频格式为 24kHz、单声道、16bit 的 PCM 数据，您可以直接将数据流式送入播放器进行实时播放，也可以按上述示例将其保存为标准的 WAV 文件。

## 多轮语音对话

支持在多轮对话中保持语音上下文。您可以将用户的语音历史放入 messages 中，AI 的输出推荐将文字部分作为 assistant 回复填入 content。

```python copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import base64
from openai import OpenAI

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

# 读取当前轮用户语音
with open("current_question.wav", "rb") as f:
    current_audio = base64.b64encode(f.read()).decode('utf-8')

completion = client.chat.completions.create(
    model="step-audio-2",
    modalities=["text", "audio"],
    messages=[
        {
            "role": "system",
            "content": "你是一个友好的助手，请用自然的语气回答用户的问题。",
        },
        # 第一轮对话（可以用 ASR 文本表示历史语音）
        {
            "role": "user",
            "content": "你好，请问今天天气怎么样？",
        },
        {
            "role": "assistant",
            "content": "你好！今天天气晴朗，气温适宜，非常适合出门活动。",
        },
        # 当前轮语音输入
        {
            "role": "user",
            "content": [
                {
                    "type": "input_audio",
                    "input_audio": {
                        "data": f"data:audio/wav;base64,{current_audio}",
                    }
                }
            ],
        }
    ],
    audio={
        "voice": "wenrounansheng",
        "format": "wav",
    },
    stream=False,
)

print(completion.choices[0].message.audio.transcript)
```

> [!NOTE]
>
> **上下文限制说明**：
>
> * `step-audio-2` / `step-audio-r1.5` 支持上下文传入 wav 格式音频
> * 请求最大支持 10MB（指 base64 后的总大小，大致能传 7.5MB 的 wav 文件）
> * 最多支持 30 段声音（如果单段声音超过 25s，会被自动分段，每 25s 视为一段）
> * `step-1o-audio` 目前不支持上下文中传入 wav（但支持语音输出）

## 结合 Tool Call 使用

`step-audio-2` / `step-1o-audio` 语音模型支持 Tool Call 功能，可以在语音对话中调用外部工具。完整流程包括：检测函数调用、执行函数、返回结果并获取最终语音回复。

```python copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import base64
import json
from openai import OpenAI

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

# 定义工具函数
def get_weather(city: str) -> str:
    """模拟获取天气信息"""
    # 实际应用中这里调用真实的天气 API
    return f"{city}：晴，气温 25°C，空气质量良好"

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的天气信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市名称，如：北京、上海"
                    }
                },
                "required": ["city"]
            }
        }
    }
]

messages = [
    {
        "role": "user",
        "content": "北京今天天气怎么样？",
    }
]

# 第一次调用：模型可能返回 tool_calls
completion = client.chat.completions.create(
    model="step-audio-2",
    modalities=["text", "audio"],
    messages=messages,
    tools=tools,
    audio={
        "voice": "wenrounansheng",
        "format": "wav",
    },
    stream=False,
)

assistant_message = completion.choices[0].message

# 检查是否有 tool_calls
if assistant_message.tool_calls:
    # 将 assistant 消息加入上下文
    messages.append({
        "role": "assistant",
        "content": assistant_message.audio.transcript if assistant_message.audio else None,
        "tool_calls": [
            {
                "id": tc.id,
                "type": "function",
                "function": {
                    "name": tc.function.name,
                    "arguments": tc.function.arguments
                }
            }
            for tc in assistant_message.tool_calls
        ]
    })

    # 执行每个工具调用并添加结果
    for tool_call in assistant_message.tool_calls:
        function_name = tool_call.function.name
        function_args = json.loads(tool_call.function.arguments)

        # 执行函数
        if function_name == "get_weather":
            result = get_weather(function_args["city"])
        else:
            result = "未知函数"

        # 将工具执行结果加入上下文
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": result,
        })

    # 第二次调用：获取最终的语音回复
    final_completion = client.chat.completions.create(
        model="step-audio-2",
        modalities=["text", "audio"],
        messages=messages,
        tools=tools,
        audio={
            "voice": "wenrounansheng",
            "format": "wav",
        },
        stream=False,
    )

    # 获取最终回复
    final_message = final_completion.choices[0].message
    print("文字回复:", final_message.audio.transcript)

    # 保存音频
    with open("response.wav", "wb") as f:
        f.write(base64.b64decode(final_message.audio.data))
else:
    # 没有 tool_calls，直接输出回复
    print("文字回复:", assistant_message.audio.transcript)
    with open("response.wav", "wb") as f:
        f.write(base64.b64decode(assistant_message.audio.data))
```

### Tool Call 返回示例

第一次调用返回（text+audio 模态，带 tool\_call 字段）：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "019b55f32eb27db7a0cc933be0216686",
  "choices": [
    {
      "finish_reason": null,
      "index": 0,
      "message": {
        "role": "assistant",
        "audio": {
          "data": "[base64 wav data]",
          "transcript": "让我帮您查一下北京的天气。"
        },
        "tool_calls": [
          {
            "id": "call-1766673564415832077",
            "function": {
              "arguments": "{\"city\": \"北京\"}",
              "name": "get_weather"
            },
            "type": "function",
            "index": 0
          }
        ]
      }
    }
  ],
  "model": "step-audio-2",
  "usage": {
    "completion_tokens": 106,
    "prompt_tokens": 410,
    "total_tokens": 516
  }
}
```

> [!NOTE]
>
> **注意**：模型可能会在返回 tool\_calls 的同时输出语音（如"让我帮您查一下"），您可以在等待函数执行时播放这段语音，提升用户体验。

## 音频格式说明

### 输入音频格式

* 支持 mp3 和 wav 格式
* Base64 编码格式示例：`data:audio/mpeg;base64,${base64_string}` 或 `data:audio/wav;base64,${base64_string}`

### 输出音频格式

| 场景 | 格式 | 规格 |
| - | - | - |
| 非流式（stream=false） | wav | 标准 wav 文件格式 |
| 流式（stream=true） | pcm | 24kHz，单声道，16bit |

## Chat Completions vs Realtime API

阶跃星辰提供两种语音对话方案，适用于不同的场景需求：

| 特性 | Chat Completions API | Realtime API |
| - | - | - |
| 连接方式 | HTTP 请求 | WebSocket 长连接 |
| 语音识别 (ASR) | 需自行实现或使用第三方服务 | 内置，自动识别用户语音 |
| 上下文管理 | 需自行维护 messages 列表 | 内置，自动管理对话历史 |
| 语音活动检测 (VAD) | 需自行实现 | 内置，自动检测用户说话 |
| 联网搜索 | 需自行实现搜索接口 | 内置 web\_search 工具 |
| 知识库检索 | 需自行实现 | 内置 retrieval 工具 |
| 延迟 | 较低（流式输出） | 极低（双向流式交互） |
| 适用场景 | 离线处理、批量任务、简单集成 | 实时对话、语音助手、客服机器人 |
| 音色复刻 | 不支持 | `step-audio-2` 支持音色复刻 |

### 使用 Realtime API 的优势

如果您需要构建实时语音对话应用，推荐使用 [Realtime API](/docs/zh/guides/developer/realtime)：

* **开箱即用**：内置 ASR、VAD、上下文管理，无需额外集成
* **超低延迟**：基于 WebSocket 的实时双向通信
* **内置工具**：支持 `web_search` 联网搜索和 `retrieval` 知识库检索
* **自定义 Tool Call**：同样支持自定义函数调用
* **音色复刻**：支持使用自定义音色进行语音生成

> **[实时语音互动开发指南](/docs/zh/guides/developer/realtime)**

## 常见问题

### 流式播放 PCM 音频

在浏览器环境中播放流式 PCM 音频，需要使用 Web Audio API。以下是一个简单的播放器示例：

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
class SimplePCMPlayer {
  constructor() {
    this.audioContext = new (window.AudioContext || window.webkitAudioContext)();
    this.bufferedData = [];
    this.isPlaying = false;
    this.nextStartTime = 0;
  }

  // 追加 PCM 数据（16位有符号小端，24kHz，单声道）
  appendPCM(pcmArrayBuffer) {
    const int16Array = new Int16Array(pcmArrayBuffer);
    const float32Array = new Float32Array(int16Array.length);
    for (let i = 0; i < int16Array.length; i++) {
      float32Array[i] = int16Array[i] / 32768;
    }
    this.bufferedData.push(float32Array);
    if (!this.isPlaying) {
      this.playNext();
    }
  }

  playNext() {
    if (this.bufferedData.length === 0) {
      this.isPlaying = false;
      return;
    }
    this.isPlaying = true;
    const data = this.bufferedData.shift();
    const audioBuffer = this.audioContext.createBuffer(1, data.length, 24000);
    audioBuffer.copyToChannel(data, 0);
    const source = this.audioContext.createBufferSource();
    source.buffer = audioBuffer;
    source.connect(this.audioContext.destination);
    const startTime = Math.max(this.audioContext.currentTime, this.nextStartTime);
    this.nextStartTime = startTime + audioBuffer.duration;
    source.start(startTime);
    source.onended = () => this.playNext();
  }

  // 清空缓冲并停止播放
  clear() {
    this.bufferedData = [];
    this.isPlaying = false;
    this.nextStartTime = this.audioContext.currentTime;
  }
}
```

### 优化首字延迟

如果需要更低的首字延迟：

1. 使用 `step-audio-2-mini` 模型，它的响应速度更快
2. 使用流式输出（stream=true），可以边生成边播放
3. 考虑使用 [Realtime API](/docs/zh/guides/developer/realtime) 获得最低延迟体验


# 文件解析
Source: https://platform.stepfun.com/docs/zh/guides/developer/doc-parser



> [!NOTE]
>
> 文档解析能力限时免费使用中。文件服务本身存储按 0.5元/GB/天计费。

阶跃星辰文档解析接口提供强大的文档解析能力，支持 PDF、Word 等多种格式，帮助开发者快速解析文档内容，并将其作为输入用于生成和推理。该接口提供从文档内容提取到生成应用的一站式解决方案，让基于文档内容的应用开发更加高效便捷。

## 效果

* [上传文件](/docs/zh/api-reference/files/create)：提供文档上传接口，支持多种文档格式，简化了基于文档的内容的输入。（注意：目前仅支持纯文本内容，图片或扫描形式的文本内容暂不支持）
* [查询文件状态](/docs/zh/api-reference/files/retrieve)：文档状态查询接口让开发者及时跟踪解析进度，随时了解文档是否成功解析。
* [读取文件内容](/docs/zh/api-reference/files/retrieve-content)：文档解析成功后，内容提取接口可快速获得文档内容，为后续基于文档内容的生成或分析提供数据基础。
* [查询文件清单](/docs/zh/api-reference/files/list)：提供文件清单查询接口，帮助开发者获取已上传文档的列表，便于文档管理。
* [删除文件](/docs/zh/api-reference/files/delete)：支持文件删除功能，让开发者可以在文档处理完成后随时删除文档，方便管理文档存储。

## 开发步骤

![doc-parser-flow](https://mintcdn.com/stepfun/ivZhb9pOE5X12y-g/images/doc-parser-flow.jpg?fit=max\&auto=format\&n=ivZhb9pOE5X12y-g\&q=85\&s=50cde0d85c5050ad72081f3b9941ce4b)

通过【上传文件】【查询文件状态】【提取文件内容】+文本补全接口 即可获得完整基于文档内容的对话补全能力

### 1.上传文件

上传文件到阶跃星辰文件服务，由阶跃星辰文件服务解析文件内容，用于后续生成和推理。

* 上传时使用的 purpose 字段的值为 `file-extract`，用于文件解析。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import requests

STEP_API_KEY="YOUR_STEP_API_KEY"
BASE_URL = "https://api.stepfun.com/v1"

headers = {
    "Authorization": f"Bearer {STEP_API_KEY}"
}
#定义文件名，上传本地文件
files = {
    "file": ("sampleFileName.doc", open("./file/《内部审计制度》.doc", "rb")),
}
#purpose为文件使用意图字段，目前支持以下选项
#file-extract： 用作文件解析，可以将文件内的文本，解析出来。（暂时不支持图片，或扫描的文字）
#retrieval： 用于知识库，在后续上线知识库能力的时候，在知识库关联该文档的时候，会将文档字段分片并向量化，以便RAG使用
data = {
    "purpose": "file-extract"
}
#调用接口上传文件
response = requests.post(BASE_URL+"/files", headers=headers, files=files, data=data)

print(response.json())
#解析出json
responseJson = response.json()
#提取出文件id
print(responseJson['id'])
```

返回结果如下:

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
#返回的报文：请注意存好 id!!!!后续对文件的操作都是基于此id
{
    "id": "file-C0DDg04QPg",
    "object": "file",
    "bytes": 56182,
    "created_at": 1730194303,
    "filename": "sampleFileName.doc",
    "purpose": "file-extract"
}
file-C0DDg04QPg
```

### 2. 查询文件状态

在文件上传完成后，需要查询文件解析状态，确认文件解析是否完成，以便后续获取文件内容。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import requests

STEP_API_KEY="YOUR_STEP_API_KEY"
BASE_URL = "https://api.stepfun.com/v1"

file_id = "file-C0DDg04QPg"
URL = BASE_URL+"/files/"+file_id

headers = {
    "Authorization": f"Bearer {STEP_API_KEY}"
}

response = requests.get(URL, headers=headers)
print(response.json())
#解析出json
responseJson = response.json()
#提取出文件解析的状态
print(responseJson['status'])
```

返回结果如下，在返回的报文中重点关注 status 状态，当 status 为 success 时，表示文件解析处理完成，可以通过接口获取到文件的内容。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
#返回的报文：重点关注status状态。
#当purpos为file-extract时。
#success：表示文件解析处理完成，可以通过接口获取到文件的内容
#processed：表示还在解析中，当前状态无法提取文件内容
{
    "id": "file-C0DDg04QPg",
    "object": "file",
    "bytes": 56182,
    "created_at": 1730194304,
    "filename": "sampleFileName.doc",
    "purpose": "file-extract",
    "status": "success"
}
success
```

### 3. 提取文件内容

当文件完成解析后，就可以使用提取文件内容接口获取文件内容，并在 Chat API 中，将内容作为对话的输入，生成对话补全。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import requests

STEP_API_KEY="YOUR_STEP_API_KEY"
BASE_URL = "https://api.stepfun.com/v1"

file_id = "file-C0DDg04QPg"
URL = BASE_URL+"/files/"+file_id+"/content"

headers = {
    "Authorization": f"Bearer {STEP_API_KEY}"
}

response = requests.get(URL, headers=headers)

print(response.text)

#返回的报文：解析文档后生成内容
#例如
好好学习，天天向上
```

### 4. 基于文档推理完整示例

当提取到需要的文档内容后，可以将文档内容作为对话的输入，生成对话补全。完整代码参考如下

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import requests
import time
from openai import OpenAI

STEP_API_KEY = "YOUR_STEP_API_KEY"
BASE_URL = "https://api.stepfun.com/v1"
#定义上传文件方法
def upload_file(filename, filepath, base_url, step_api_key):
    headers = {
        "Authorization": f"Bearer {step_api_key}"
    }
    with open(filepath, "rb") as file:
        files = {
            "file": (filename, file),
        }
        data = {
            "purpose": "file-extract"
        }
        # Make the API request
        response = requests.post(f"{base_url}/files", headers=headers, files=files, data=data)
        # Parse the JSON response
        response_json = response.json()
        # Return the file ID
        return response_json.get("id")

#定义获取文件状态方法
def get_file_status(fileid, base_url, step_api_key):
    headers = {
        "Authorization": f"Bearer {step_api_key}"
    }
    url = f"{base_url}/files/{fileid}"
    response = requests.get(url, headers=headers)
    response_json = response.json()
    return response_json.get('status', 'unknown')

#定义获取文件内容方法
def get_file_content(fileid, base_url, step_api_key):
    headers = {
        "Authorization": f"Bearer {step_api_key}"
    }
    url = f"{base_url}/files/{fileid}/content"
    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        return response.text
    else:
        return f"Error: {response.status_code} - {response.text}"

# 上传文件获取文件ID
file_id = upload_file(
    filename="经济责任审计制度.doc",
    filepath="./file/《经济责任审计制度》.doc",
    base_url=BASE_URL,
    step_api_key=STEP_API_KEY,
)

# 等待文件解析完成
while True:
    status = get_file_status(file_id, BASE_URL, STEP_API_KEY)
    if status == 'success':
        break
    time.sleep(1)  # 避免频繁请求

# 获取文件内容
file_content = get_file_content(file_id, BASE_URL, STEP_API_KEY)
print(file_content)

# 生成对话
messages = [
    {
        "role": "system",
        "content": "你是阶跃星辰助手，会读取用户发送给你的文件的内容，并结合文件内容回答问题",
    },
    {
        "role": "user",
        "content": file_content,
    },
    {"role": "user", "content": "请简单介绍文档的具体内容"},
]
time_start = time.time()
# 初始化
client = OpenAI(api_key=STEP_API_KEY,base_url=BASE_URL)
# 针对长文本分析，建议先使用token count接口计算一次文件解析出文本的tokens,https://platform.stepfun.com/zh/api-reference/token-count，
# 再选择合适上下文长度的模型
# 实现文本补全
response = client.chat.completions.create(
    messages=messages,
    model="step-5-preview",
    stream=True,
)
i=0
for chunk in response:
    i += 1
    print(chunk.choices[0].delta.content.strip(),end="")
    if i == 1:
        time_firstWord = time.time()
        elapsed_time= time_firstWord-time_start
        print(f"首字生成时间: {elapsed_time:.2f} 秒")
time_end = time.time()
elapsed_time = time_end - time_start
print(f"总生成时间: {elapsed_time:.2f} 秒")

#返回的报文：即针对文件解析出来的内容生成的会话补全内容
```

## 其他操作实例

### 查看文件列表

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import requests

STEP_API_KEY="YOUR_STEP_API_KEY"
BASE_URL = "https://api.stepfun.com/v1"
#filePurpose根据需要填写file-extract或retrieval
filePurpose="file-extract"
URL = BASE_URL+"/files?purpose="+filePurpose

headers = {
    "Authorization": f"Bearer {STEP_API_KEY}"
}

response = requests.get(URL, headers=headers)
responseJson = response.json()
print(responseJson)
```

返回结果如下：

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
#返回的报文，将会列举出上传成功的文件清单。
#建议将文件清单读取后，缓存到页面上，以便于对文档进行操作
{
  "object": "list",
  "data": [
    {
      "id": "file-C0OBldwum0",
      "object": "file",
      "bytes": 1095573,
      "created_at": 1730203514,
      "filename": "繁花.txt",
      "purpose": "file-extract",
      "status": "success"
    },
    {
      "id": "file-C0OGG69uvw",
      "object": "file",
      "bytes": 60728,
      "created_at": 1730203574,
      "filename": "经济责任审计制度.doc",
      "purpose": "file-extract",
      "status": "success"
    }
  ]
}
```

### 删除文件

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import requests

STEP_API_KEY="YOUR_STEP_API_KEY"
BASE_URL = "https://api.stepfun.com/v1"

file_id = "file-C0OGG69uvw"
URL = BASE_URL+"/files/"+file_id

headers = {
    "Authorization": f"Bearer {STEP_API_KEY}"
}

response = requests.delete(URL, headers=headers)
responseJson = response.json()
print(responseJson)

```

返回结果如下：

```jsonc theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// 返回的报文，将会告知是否删除成功。
{
  "id": "file-C0OGG69uvw",
  "object": "file",
  "deleted": true
}
```

## 注意事项

* 文件解析流程：
  * 对于首次解析的文件，需先查询文件解析状态，确认成功后再获取内容。
  * 超长文本解析时，请先计算内容的 tokens 数量，以避免超出限制导致的请求中断。
* 文件与请求限制：
  * 单文件大小：最大 64MB。
  * 文件总数限制：最多存储 1000 个文件。
  * 支持的意图：
    * file-extract：用于文档内容解析。
    * retrieval：用于知识库存储。
* 支持的文件类型：
  * 纯文本文件：.txt, .md
  * PDF 文件：.pdf
  * Word 文档：.doc, .docx
  * Excel 表格：.xls, .xlsx
  * PPT 文件：.ppt, .pptx
  * CSV 文件：.csv
  * HTML/XML 文件：.html, .htm, .xml
* 内容限制：
  * 仅支持纯文本内容解析，不支持图片或扫描的文本内容。


# 异常处理
Source: https://platform.stepfun.com/docs/zh/guides/developer/exception



大模型本身在运行过程中，存在一定的随机性，这些随机性也会带来一些可能的问题或异常。此外，当请求频次过高时，也会触发阶跃星辰所设定的请求限制，因此作为开发者，您可以通过在您的应用程序中添加错误处理的逻辑，来帮助您更好的提供服务。

阶跃星辰 API 提供的异常类型一共有两种：

1. HTTP 层面的异常
2. 模型层面的异常

### HTTP 层面的异常

目前阶跃星辰可能会返回如下几类错误码，您可以通过在应用程序中添加不同的拦截和处理，来优化您的应用程序体验。

#### 400 错误

当阶跃星辰 API 返回 HTTP 400 错误时，表明您的请求当中存在了超出参数配置的内容， 因此，您需要参考所调用的 API 文档，检查自己的请求是否出现了问题。
如果您的请求信息中包含 UGC 内容， 则可以前置的在应用程序中参考阶跃星辰 API 的限制进行用户输入的验证，以帮助用户更早的感知到自己输入的问题。

#### 401 错误

当阶跃星辰 API 返回 HTTP 401 错误时，表明您的认证无效。这可能是由于您使用了错误的 API 密钥。您需要仔细检查您所使用的 API 密钥是否正确，确保其准确无误。
如果问题仍然存在，您可以联系我们的技术支持团队，他们将为您提供进一步的帮助和指导，以解决认证相关的问题，确保您能够正常使用阶跃星辰 API 的各项功能。

#### 402 错误

当阶跃星辰 API 返回 HTTP 402 错误时，表明您的账号当中的余额已经无法支撑本次调用，因此，您需要尽快访问阶跃星辰开放平台充值费用，以恢复正常调用。

#### 404 错误

当阶跃星辰 API 返回 HTTP 404 错误时，表明您的请求路径不正确。这意味着您所请求的资源在服务器上无法按照您提供的路径被找到。您需要仔细参照文档，检查并修复请求路径信息。

* 首先，确认您输入的路径格式是否符合 API 的规范要求，包括大小写、特殊字符等是否准确。
* 如果经过检查和修复后，仍然返回 404 错误，您可以进一步查看文档中关于路径结构和层级的详细说明，确保您对 API 的资源组织结构有清晰的理解。

如果问题依旧无法解决，您可以联系我们的技术支持团队，他们将为您提供更深入的指导和帮助，以确保您能够正确地访问到所需的资源，顺利使用阶跃星辰 API 的相关功能。

#### 429 错误

当阶跃星辰 API 返回 HTTP 429 错误时，表明您的请求频次已经超出了允许的频次。您可以通过设定一定的 delay 时间后，再次请求。如果 delay 仍无法解决，则可以通过充值获得更高的频次。
如充值后的限额依然无法满足您的需求，可以联系我们以开通更高的频次。

#### 451 错误

当阶跃星辰 API 返回 HTTP 451 错误时，表明您的请求内容或大模型响应内容中出现了无法通过安全审核的内容，您可以通过前置添加安全审核能力，来前置完成验证，以帮助用户更早的感知到自己输入的问题。

#### 500 / 503 / 504 错误

当阶跃星辰 API 返回 HTTP 500 /503 /504 错误时，表明是阶跃星辰的服务端出现的问题，当您遇到 5XX 错误时，可以稍等重试。如多次重试后依然无法解决，则可以联系我们定位。

### 模型层面的异常

在大模型补全时，可能会因为多种原因停止返回，因此需要根据返回的 `finish_reason` 进行下一步的处理

* 当结束原因为 `stop` 时，表示大模型按照预定计划结束生成，可直接处理 Message。
* 当结束原因为 `length` 时，表示大模型没有按照预定计划结束生成，受限于 max\_token 未能完整输出。
* 当结束原因为 `content_filter` 时，表示大模型虽然按照预定计划结束生成，但未通过安全审核，可以通过前置添加安全审核能力，来前置完成验证，以帮助用户更早的感知到自己输入的问题。
* 当结束原因为 `tool_calls` 时，表示大模型希望调用函数，则需要进行相应的处理，并将返回的函数调用结果传入下一次请求中。

#### 流式请求下的处理

在使用流式请求时，请求可能会在生成过程中因为模型输出原因结束，因此，您需要在获取到服务器的流式返回时，根据每一个 chunk 返回的 `finish_reason` 进行下一步的处理。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
completion = client.chat.completions.create()
for c in completion:
    for choice in c.choices:
        if choice.finish_reason == "stop":
            # 表示正常结束，直接输出即可。
            print(c.to_dict())
        if choice.finish_reason == "content_filter":
            # 表示此请求被安全审核拦截
            print(c.to_dict())
        ### .... 更多处理
```


# 图片理解
Source: https://platform.stepfun.com/docs/zh/guides/developer/image-chat



阶跃星辰视觉理解大模型支持在对话过程中传入图片文件用于理解图片当中的内容，参与大模型的对话过程中，通过图像来补充上下文，以实现诸如：基于图片追问、提问图片中的内容等能力。

> [!NOTE]
>
> 推荐优先使用 `step-5-preview`，支持文本、图片和视频输入，提供 1M tokens 上下文。需要辨认图片细节时，可显式设置 `detail: "high"`；高速多模态场景也可使用 `step-3.7-flash`。

## 能力限制

* 目前 `step-5-preview`、`step-3.7-flash`、`step-1o-turbo-vision` 等模型支持 JPG/JPEG、PNG、静态 GIF、WebP 格式的图片，且支持通过 URL 或 Base64 作为参数传递。
* 上述模型限制了单次请求图像不能超过 60 张，如果超过 60 张照片，可以先对图片进行描述，并作为上下文传入到请求当中。

## 使用 Step 5 Preview

在启动程序的终端设置 `STEPFUN_API_KEY` 后，可使用以下示例。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import os
from openai import OpenAI

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

completion = client.chat.completions.create(
    model="step-5-preview",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "请描述这张图片。"},
            {"type": "image_url", "image_url": {
                "url": "https://www.stepfun.com/assets/section-1-CTe4nZiO.webp",
                "detail": "high",
            }},
        ],
    }],
)
print(completion.choices[0].message.content)
```

## 其他兼容模型示例

以下保留 `step-1o-turbo-vision` 的示例与历史输出，便于维护现有集成。其中图片 Token 数、默认细节模式与预处理参数不代表 Step 5 Preview 的实际用量；请以目标模型文档及响应中的 `usage` 为准。

## 如何实现图片理解

### 简单图片理解

在对话过程中，如果您需要将图片传递给大模型，则可以通过在传入的信息当中，加入 `type` 为 `image_url` 类型的内容，来完成对话。

阶跃星辰支持在 image\_url 类型中使用 URL 或 Base64 格式的内容，为了保证更好的性能，推荐使用 URL 来完成图片参数的传递。

具体实现可以参考如下代码

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI
import os

API_KEY= os.getenv("API_KEY")
client = OpenAI(api_key=API_KEY, base_url="https://api.stepfun.com/v1")

completion = client.chat.completions.create(
  model="step-1o-turbo-vision",
  messages=[
      {
          "role": "system",
          "content": "你是由阶跃星辰提供的AI聊天助手，你除了擅长中文，英文，以及多种其他语言的对话以外，还能够根据用户提供的图片，对内容进行精准的内容文本描述。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容",
      },
      # 在对话中传入图片，来实现基于图片的理解
      {
          "role": "user",
          "content": [
              {
                  "type": "text",
                  "text": "用优雅的语言描述这张图片",
              },
              {
                  "type": "image_url",
                  "image_url": {
                      "url": "https://www.stepfun.com/assets/section-1-CTe4nZiO.webp",
                      "detail": "high"
                  },
              },
          ],
      },
  ],
)

print(completion.model_dump_json(indent=3))

# 输出内容
# {
#    "id": "105e9027276481c141821b77b1b2a2f2.eeb4fc6f4b4e39921fe5fc5e2f33d57c",
#    "choices": [
#       {
#          "finish_reason": "stop",
#          "index": 0,
#          "logprobs": null,
#          "message": {
#             "content": "在这幅静谧的夜景中，一座现代建筑在微光中显得格外引人注目。建筑外墙上“ART WEST BUND”的字样在灯光的映衬下熠熠生辉，透露出浓厚的艺术气息。建筑前的广场宽敞而整洁，几盏路灯散发出温暖的光芒，为夜色增添了一丝浪漫。树木静静地矗立在广场上，仿佛在守护着这片宁静的艺术之地。远处的高楼在夜幕中若隐若现，与这座艺术殿堂相映成趣，共同构成了一幅充满现代感与艺术气息的都市夜景图。",
#             "refusal": null,
#             "role": "assistant",
#             "function_call": null,
#             "tool_calls": null
#          }
#       }
#    ],
#    "created": 1727073234,
#    "model": "step-1o-turbo-vision",
#    "object": "chat.completion",
#    "service_tier": null,
#    "system_fingerprint": null,
#    "usage": {
#       "completion_tokens": 130,
#       "prompt_tokens": 497,
#       "total_tokens": 627,
#       "completion_tokens_details": null,
#       "cached_tokens": 256
#    }
# }
```

### 基于图片的多轮对话

除了直接使用图片进行图像理解，您还可以使用图片进行多轮对话，通过将其放置在上下文中，即可完成多轮对话。

具体实现可以参考如下代码。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI
import os

API_KEY= os.getenv("API_KEY")
client = OpenAI(api_key=API_KEY, base_url="https://api.stepfun.com/v1")

completion = client.chat.completions.create(
  model="step-1o-turbo-vision",
  messages=[
      {
          "role": "system",
          "content": "你是由阶跃星辰提供的AI聊天助手，你除了擅长中文，英文，以及多种其他语言的对话以外，还能够根据用户提供的图片，对内容进行精准的内容文本描述。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容",
      },
      {
          "role": "user",
          "content": [
              {
                  "type": "text",
                  "text": "用优雅的语言描述这张图片",
              },
              {
                  "type": "image_url",
                  "image_url": {
                      "url": "https://www.stepfun.com/assets/section-1-CTe4nZiO.webp",
                      "detail": "high"
                  },
              },
          ],
      },
      # 将模型给予的返回重新插入会对话上下文，进行一轮新的对话
      {
          "role":"assistant",
          "content": "这幅图片中，我们看到了一座现代建筑，它坐落在一个宁静而宽敞的广场上。建筑的外墙以简洁的线条和明亮的色彩为特色，彰显出一种现代美学。夜幕降临，天空呈现出淡淡的蓝色，与建筑的暖色灯光形成了鲜明的对比，营造出一种温馨而宁静的氛围。\n\n广场上，几盏路灯散发出柔和的光芒，为周围的树木和地面铺上了一层温暖的光辉。树木静静地矗立在广场上，为这座建筑增添了一丝自然的气息。远处的高楼大厦在夜色中若隐若现，与这座建筑形成了鲜明的对比，展现出城市的繁华与宁静并存的景象。\n\n总的来说，这幅图片通过巧妙的构图和色彩运用，展现了一座现代建筑在夜幕中的美丽景象，让人感受到城市中的宁静与温馨。"
      },
      # 将用户的新问题继续追问大模型
      {
          "role":"user",
          "content":"那这张照片可能是在哪个国家拍摄的？"
      }
  ],
)

print(completion.model_dump_json(indent=3))

# 输出内容

# {
#    "id": "aad5d20afc7506cfda8fc7510124d948.05ca5a939a04585bd7a68e5a9ee64563",
#    "choices": [
#       {
#          "finish_reason": "stop",
#          "index": 0,
#          "logprobs": null,
#          "message": {
#             "content": "这张照片展示了一座现代建筑，建筑外墙上写有“ART WEST BUND”的字样，这通常是上海西岸艺术中心的标志。上海西岸艺术中心位于中国上海，是一处集艺术展览、文化交流和休闲娱乐于一体的综合性艺术园区。因此，这张照片很可能是在中国上海拍摄的。",
#             "refusal": null,
#             "role": "assistant",
#             "function_call": null,
#             "tool_calls": null
#          }
#       }
#    ],
#    "created": 1727073254,
#    "model": "step-1o-turbo-vision",
#    "object": "chat.completion",
#    "service_tier": null,
#    "system_fingerprint": null,
#    "usage": {
#       "completion_tokens": 65,
#       "prompt_tokens": 697,
#       "total_tokens": 762,
#       "completion_tokens_details": null,
#       "cached_tokens": 256
#    }
# }
```

### 多图图片理解

### 使用 detail 参数提供更加完整的信息

> [!NOTE]
>
> `step-1o-turbo-vision` 模型推荐默认开启 detail 模式，会拥有更好的视觉理解能力。

目前默认会选择低分辨率模式，以获得更加快速响应速度，同时，低分辨率模式也会带来较少的 token 消耗。在低分辨率模式下，`step-1o-turbo-vision` 默认每张图片约 169 token；

但在一些具体的业务场景下，需要大模型细致的理解图片中的细节和内容，则可以通过设置其 detail 模式为 `high`，使得大模型获取到更加完整的信息，从而进行更加详细的图片理解和描述。需要注意的是，当 detail 模式为 `high` 时，图片的 Token 消耗将会基于图片大小进行计算，可能会消耗远超低分辨率模式的 token 数，此外，由于大模型会看到完整版的图片，响应的首字时延也会有提升。

具体代码可参考下

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI
import os

API_KEY= os.getenv("API_KEY")
client = OpenAI(api_key=API_KEY, base_url="https://api.stepfun.com/v1")

completion = client.chat.completions.create(
  model="step-1o-turbo-vision",
  messages=[
      {
          "role": "system",
          "content": "你是由阶跃星辰提供的AI聊天助手，你除了擅长中文，英文，以及多种其他语言的对话以外，还能够根据用户提供的图片，对内容进行精准的内容文本描述。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容",
      },
      # 在对话中传入图片，来实现基于图片的理解
      {
          "role": "user",
          "content": [
              {
                  "type": "text",
                  "text": "用优雅的语言描述这张照片",
              },
              {
                  "type": "image_url",
                  "image_url": {
                      "url": "https://www.stepfun.com/assets/section-1-CTe4nZiO.webp"
                  },
              },
              {
                  "type":"image_url",
                  "image_url":{
                      "url":"https://postimg.aliavv.com/step/daesog.png"
                  }
              }
          ],
      },
  ],
)

print("low detail")
print(completion.model_dump_json(indent=2))

print("high detail")
completion = client.chat.completions.create(
  model="step-1o-turbo-vision",
  messages=[
      {
          "role": "system",
          "content": "你是由阶跃星辰提供的AI聊天助手，你除了擅长中文，英文，以及多种其他语言的对话以外，还能够根据用户提供的图片，对内容进行精准的内容文本描述。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容",
      },
      {
          "role": "user",
          "content": [
              {
                  "type": "text",
                  "text": "用优雅的语言描述这张照片",
              },
              {
                  "type":"image_url",
                  "image_url":{
                      "url":"https://postimg.aliavv.com/step/daesog.png",
                      "detail":"high"
                  }
              }
          ],
      },
  ],
)
print(completion.model_dump_json(indent=2))

# 输出内容
# low detail
# {
#   "id": "3f4db73a6d12292f6a4ca78b9811bcc5.9cad450fae99f56ba0e269e6185981ef",
#   "choices": [
#     {
#       "finish_reason": "stop",
#       "index": 0,
#       "logprobs": null,
#       "message": {
#         "content": "这张照片展现了一座现代化城市的壮丽夜景。从高处俯瞰，城市的天际线在夜幕中熠熠生辉，高楼大厦的灯光如繁星点点，勾勒出一幅繁华而迷人的画卷。蜿蜒的河流贯穿城市，水面反射着两岸的灯火，宛如一条闪耀的丝带。照片中的建筑各具特色，有的高耸入云，有的独具匠心，共同谱写出一曲都市的交响乐。夜色中的城市，充满了活力与魅力，让人不禁为之沉醉。",
#         "refusal": null,
#         "role": "assistant",
#         "function_call": null,
#         "tool_calls": null
#       }
#     }
#   ],
#   "created": 1727073489,
#   "model": "step-1o-turbo-vision",
#   "object": "chat.completion",
#   "service_tier": null,
#   "system_fingerprint": null,
#   "usage": {
#     "completion_tokens": 117,
#     "prompt_tokens": 899,
#     "total_tokens": 1016,
#     "completion_tokens_details": null
#   }
# }
# high detail
# {
#   "id": "cb3b1fb0f8e7aeb4caa096ec235b494e.f2bbc7d720611275241dd62954fb3b19",
#   "choices": [
#     {
#       "finish_reason": "stop",
#       "index": 0,
#       "logprobs": null,
#       "message": {
#         "content": "在这幅照片中，我们俯瞰着一座繁华的城市，夜幕低垂，万家灯火如星辰般点缀着大地。高楼大厦拔地而起，宛如巨人般屹立在城市的心脏，勾勒出一幅现代与传统的完美融合画卷。河流蜿蜒流过城市，水面反射着璀璨的灯光，宛如一条银色的丝带，将城市的繁华与宁静巧妙地连接在一起。\n\n照片中，东方明珠电视塔高耸入云，成为城市的标志性建筑，其独特的造型在夜色中熠熠生辉。周围的建筑也纷纷点亮了灯光，犹如一座座灯塔，指引着夜归的人们。街道上车水马龙，流光溢彩，仿佛一条条流动的银河，为这座城市增添了无限的活力与魅力。\n\n在这幅照片中，我们不仅看到了城市的繁华与喧嚣，更感受到了一种宁静与和谐。它让我们明白，无论城市多么喧嚣，总有一片宁静的港湾等待着我们去发现。",
#         "refusal": null,
#         "role": "assistant",
#         "function_call": null,
#         "tool_calls": null
#       }
#     }
#   ],
#   "created": 1727073505,
#   "model": "step-1o-turbo-vision",
#   "object": "chat.completion",
#   "service_tier": null,
#   "system_fingerprint": null,
#   "usage": {
#     "completion_tokens": 217,
#     "prompt_tokens": 2102,
#     "total_tokens": 2319,
#     "completion_tokens_details": null
#   }
# }
```

如果您需要在对话过程中，使用多个图片，则可以在对话过程中通过 image\_url 传入多个图片来完成对话和问答。

> 需要注意的是，根据模型不同，一次多轮对话最多可以拥有不超过 10 张照片或 50 张照片。如果超过图片数量限制，可以参考[超出模型图片数量上限的处理方式](/docs/zh/guides/developer/image-chat#超出模型图片数量上限的处理方式)进行调整。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI
import os

API_KEY= os.getenv("API_KEY")
client = OpenAI(api_key=API_KEY, base_url="https://api.stepfun.com/v1")

completion = client.chat.completions.create(
  model="step-1o-turbo-vision",
  messages=[
      {
          "role": "system",
          "content": "你是由阶跃星辰提供的AI聊天助手，你除了擅长中文，英文，以及多种其他语言的对话以外，还能够根据用户提供的图片，对内容进行精准的内容文本描述。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容",
      },
      # 在对话中传入图片，来实现基于图片的理解
      {
          "role": "user",
          "content": [
              {
                  "type": "text",
                  "text": "用优雅的语言描述这两张照片",
              },
              {
                  "type": "image_url",
                  "image_url": {
                      "url": "https://www.stepfun.com/assets/section-1-CTe4nZiO.webp",
                      "detail": "high"
                  },
              },
              {
                  "type":"image_url",
                  "image_url":{
                      "url":"https://postimg.aliavv.com/step/daesog.png",
                      "detail":"high"
                  }
              }
          ],
      },
  ],
)

print(completion.model_dump_json(indent=3))

# 输出内容
# {
#    "id": "dd2937ea8d72e0a5064826e2f0154c02.1e83c144d202624be954996ef3fa3a5c",
#    "choices": [
#       {
#          "finish_reason": "stop",
#          "index": 0,
#          "logprobs": null,
#          "message": {
#             "content": "第一张照片展现了一座现代建筑，其设计简洁而富有现代感。在黄昏的柔和光线下，建筑外墙的浅色与周围环境形成了和谐的对比。入口处的红色设计引人注目，仿佛是这座建筑的心脏，散发着温暖的光芒。周围的树木和灯光点缀其间，为整个场景增添了一丝宁静与优雅。地面的石材铺装和远处的阶梯设计，使空间显得更加开阔和有层次感。\n\n第二张照片则展示了一座繁华都市的夜景，从高空俯瞰，城市的灯火辉煌尽收眼底。高楼大厦错落有致，灯光璀璨，犹如星河倒映在人间。河流蜿蜒穿过城市，水面反射着两岸的霓虹，为这座城市增添了一份流动的韵律。夜色中的城市充满了活力与魅力，每一栋建筑都仿佛在诉说着自己的故事，共同谱写出一曲繁华的乐章。",
#             "refusal": null,
#             "role": "assistant",
#             "function_call": null,
#             "tool_calls": null
#          }
#       }
#    ],
#    "created": 1727073194,
#    "model": "step-1o-turbo-vision",
#    "object": "chat.completion",
#    "service_tier": null,
#    "system_fingerprint": null,
#    "usage": {
#       "completion_tokens": 193,
#       "prompt_tokens": 900,
#       "total_tokens": 1093,
#       "completion_tokens_details": null,
#       "cached_tokens": 768
#    }
# }
```

在上述对话过程中，通过在 content 当中传入多个图片的 image\_url，实现了在对话中使用多张图片来进行问答。您可以根据实际情况，将多个图片插入到多个消息当中，或保留在同一个消息当中。

### 使用 Base64 进行图片理解

在一些场景下，希望大模型可以直接处理用户上传的图片，而不会再次上传至对象存储或服务当中，则可以选择在对话信息中使用 Base64 编码来传递图片内容，方便大模型理解和生成。

在使用时，您只需要提前将原本的图片连接替换为标准的 Base64 [Data URL](https://www.rfc-editor.org/rfc/rfc2397) 来发起请求即可使用 Base64 进行大模型对话和理解。

![](https://mintcdn.com/stepfun/ivZhb9pOE5X12y-g/images/guide/base64image.jpg?fit=max\&auto=format\&n=ivZhb9pOE5X12y-g\&q=85\&s=3dcbdbb55f572f95e350df5e1ed0a44c)

您可以参考如下代码对图片处理，获得图片对应的 Base64 文本，并拼接到 Chat 中

**python**

```python copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import base64

with open("./sample.jpg", "rb") as image_file:
base64_bytes = base64.b64encode(image_file.read())
print(base64_bytes)

```

**Node.js**

```js copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const fs = require('fs');
const imageBuffer = fs.readFileSync('./sample.jpg');
const base64Image = imageBuffer.toString('base64');
console.log(base64Image)
```

需要注意的是，上述方法获得的是图片的 bas64 编码，在实际调用时，您还需要拼上对应格式的类型等信息，常见图片类型的对应前缀可参考如下表格。

| 图片后缀 | 图片类型 | 对应前缀 |
| - | - | - |
| jpg | image/jpeg | `data:image/jpeg;base64,` |
| png | image/png | `data:image/png;base64,` |
| gif | image/gif | `data:image/gif;base64,` |
| webp | image/webp | `data:image/webp;base64,` |

### 使用 Files API 加速图片理解

在使用图片理解时，如果传入的是外部的 URL，阶跃星辰的服务器将会请求外部 URL，获取图片内容并进行生成。生成的速度将会受到图片下载速度的影响，因此，我们推荐将图片放置在 CDN 或具有较大下载带宽的对象存储上，以便于对图片进行更快的下载。但如果您的图片需要重复使用，比如用来做 Few-shot,则可以考虑将图片使用阶跃星辰 Files API 上传至阶跃星辰文件存储服务上，以避免重复下载，产生持续的流量消耗。

![](https://mintcdn.com/stepfun/ivZhb9pOE5X12y-g/images/guide/image_url.png?fit=max\&auto=format\&n=ivZhb9pOE5X12y-g\&q=85\&s=f5202757927ec6b252a25c33f499b6c8)

您可以调用[上传文件](/docs/zh/api-reference/files/create) API，并传入文件，选择 **purpose 为 storage**，上传完成后所获取的 File ID 则可以在对话过程中使用。在拿到 File ID 后，您需要在 File ID 前拼上 `stepfile://`，用于标注这个图片从阶跃星辰文件服务中获取，后续模型在推进推理时，将会从阶跃星辰文件存储服务上获取文件，从而降低下载文件所需的时间，提升整体推理的时延。

## 常见问题

### 图片较多情况下指令跟随较差的处理方式

模型在进行推理时，图片也会转换成为相应的 Image Token，当一个对话的上下文较长时，可能会导致模型重点关注靠后的 Prompt，因此在撰写 Prompt 时，可以将指令放在尾部，图片放在头部，方便模型更加关注指令，从而提升指令跟随的效果。

### 超出模型图片数量上限的处理方式

如果在对话过程中，出现了超过模型图片上限的情况，则可以将前述的照片先使用 `step-3.7-flash` 等多模态模型对图片进行总结和描述，并作为上下文传递。从而实现在整个对话中插入多个图片的信息。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI
import os

API_KEY= os.getenv("API_KEY")
client = OpenAI(api_key=API_KEY, base_url="https://api.stepfun.com/v1")

# 使用 `step-1o-turbo-vision` 模型，对图片进行描述
def get_description_from_img(img_url:str):
    completion = client.chat.completions.create(
        model="step-1o-turbo-vision",
        messages=[
            {
                "role": "system",
                "content": "你是由阶跃星辰提供的AI聊天助手，你除了擅长中文，英文，以及多种其他语言的对话以外，还能够根据用户提供的图片，对内容进行精准的内容文本描述。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容",
            },
            # 在对话中传入图片，来实现基于图片的理解
            {
                "role": "user",
                "content": [
                    {
                        "type": "text",
                        "text": "请详细描述这张图片中的内容",
                    },
                    {
                        "type": "image_url",
                        "image_url": {
                            "url": img_url,
                            "detail":"high"
                        },
                    },
                ],
            },
        ],
    )
    return completion.choices[0].message.content

real_chat_context = []

real_chat_context.append({
    "role": "user",
    "content": get_description_from_img("https://www.stepfun.com/assets/section-1-CTe4nZiO.webp"),
})

print(real_chat_context)

#  调用模型进行真正的对话沟通。
```

### 优化图片以降低模型返回的首字延时

如果您的业务场景对于首字延时更敏感，而对于模型是否可以完整理解图片中的每一个细节，那么您可以通过对图片进行一定的预处理，以在保留绝大多数图片信息的同时，获得较好的处理速度。

&#x20;

> **[引入 Prompt 缓存提升推理速度](/docs/zh/guides/developer/prompt-cache)**

* 对图片进行 resize
  * 对于 detail 设置为 low 或保持默认的情况下，可以将图片的最长边缩放至 728px，短边等比例缩放，从而提升处理的速度。
  * 对于 detail 设置为 high 的情况下，可以将图片的最长边缩放至 504 的倍数，短边等比例缩放，从而提升处理的速度。
* 对图片质量进行压缩
  * 通过对图片进行压缩，将其 quality 设置为 80 ，来显著降低图片大小，同时不会太过影响模型的效果。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from PIL import Image
# 确保安装了Pillow库
# 运行以下命令以安装Pillow
# pip install Pillow

# 处理图片为 80% 质量

def compress(input_path, output_path, quality):
    image = Image.open(input_path)
    image.save(output_path, quality=quality)

# 将图片按照最长边resize到728，短边等比例缩放，并存储为新图片
def resize_image(input_path, output_path, max_size):
    image = Image.open(input_path)
    width, height = image.size

    # 计算新的尺寸
    if width > height:
        new_width = max_size
        new_height = int((max_size / width) * height)
    else:
        new_height = max_size
        new_width = int((max_size / height) * width)

    # 调整图片尺寸
    resized_image = image.resize((new_width, new_height), Image.ANTIALIAS)
    resized_image.save(output_path)

# 调用函数
resize_image('input.jpg', 'resized_output.jpg', 728)
compress('input.jpg', 're_quality_output.jpg',80)

```

### 适配透明背景的 PNG 图片

目前 `step-3.7-flash`、`step-1o-turbo-vision` 等模型支持对透明背景的 PNG 图片进行处理，但在使用时，会将透明通道处理景为黑色的情况。您可以通过对图片进行处理，将其背景设置为白色，从而避免模型在推理时，无法正确理解图片中的内容。

可以参考下方代码，提前将透明背景的 PNG 图片转换成白色背景。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from PIL import Image
def convert_rgba_to_rgb_with_white_background(input_path, output_path):
    img = Image.open(input_path)
    if img.mode != 'RGBA':
        raise ValueError("输入图片不是 RGBA 模式")
    white_background = Image.new('RGB', img.size, (255, 255, 255))
    white_background.paste(img, mask=img.split()[3])
    result = white_background.convert("RGB")
    result.save(output_path)

```


# Cherry Studio
Source: https://platform.stepfun.com/docs/zh/guides/developer/integrations/cherry-studio



Cherry Studio 是一款桌面 AI 客户端，支持多模型 Provider，并提供对话、代码生成和文本生成等能力。通过配置 Step API Key，Cherry Studio 可以直接接入 Step 模型，在桌面客户端中调用推理能力。

本文档介绍 Cherry Studio 接入 Step API 的准备条件、配置步骤与基础测试流程。

## 概述

Cherry Studio 适合在统一桌面工作台中完成多模型对话和开发辅助任务。完成 Provider 配置后，即可在客户端内直接调用 Step 模型。

## 前置条件

### 客户端环境

支持以下系统：

* macOS
* Windows
* Linux

建议使用最新版本 Cherry Studio。

### 安装 Cherry Studio

访问 [Cherry Studio 官网](https://cherry-ai.com)下载安装包。

安装完成后启动 Cherry Studio。

### 订阅 Step Plan

在开始配置前，请先确认当前账号已完成 Step Plan 订阅。只有在账号具备对应计划或调用权限后，后续模型调用与额度使用才会正常生效。

如需订阅或购买，请访问：[Step Plan 订阅](https://platform.stepfun.com/step-plan)

### 获取 Step API Key

访问 [Step 平台控制台](https://platform.stepfun.com/interface-key)创建 API Key，并妥善保存。

## 配置步骤

### 添加 Provider

打开 Cherry Studio，进入模型配置界面：

1. 在模型服务列表中选择**阶跃星辰**。
2. 输入 `Step API Key`。
3. 在 API 地址栏输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
https://api.stepfun.com/step_plan/v1
```

4. 保存配置。

5. 添加 `step-5-preview`、`step-3.7-flash`、`step-3.5-flash-2603` 或 `step-3.5-flash` 模型。

点&#x51FB;**+添加**，在打开的窗口中输入以下选项：

* 模型 ID：`<model_id>`
* 模型名称：可填写便于识别的名称
* 分组名称：可填写便于归类的名称

> 说明：`<model_id>` 请填写当前账号在 Step Plan 下可用的模型。已验证示例：`step-5-preview`、`step-3.7-flash`、`step-3.5-flash-2603`、`step-3.5-flash`。文档列出的模型不构成全部可用名单。

点击**添加模型**保存设置。

## 测试接入

点击 API 密钥右侧的**检测**。如果提示成功，则表明设置成功。如果出现错误，则需要检查 API key 和 base url 是否设置正确。


# Claude Code
Source: https://platform.stepfun.com/docs/zh/guides/developer/integrations/claude-code



本文介绍如何在 Claude Code 中通过 [Messages API](/docs/zh/api-reference/chat/messages-create) 接入 Step 模型，配置 Step Plan、推理强度与 1M 上下文，并验证对话和工具调用。

## 接入条件

### 运行环境

* macOS、Linux 或 Windows。Windows 可使用 PowerShell，也可在 WSL 中运行。
* 本文采用 npm 安装方式，需要 Node.js 22 或更高版本；已使用原生安装包安装 Claude Code 的用户可跳过 npm 安装。

使用 npm 安装前，确认 Node.js 与 npm 可用：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
node -v
npm -v
```

### 订阅 Step Plan

确认 [Step Plan 订阅](https://platform.stepfun.com/step-plan)有效、额度可用，且具备所用模型的调用权限。本文配置示例使用 Step Plan 通道。

### 获取 Step API Key

前往 [Step 开放平台密钥管理](https://platform.stepfun.com/interface-key)页面创建 API Key。

## 配置步骤

### 安装 Claude Code

在终端中执行：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
npm install -g @anthropic-ai/claude-code
```

安装完成后，验证版本：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
claude --version
```

兼容性验证版本：**Claude Code 2.1.209**。安装命令获取最新版；模型别名解析和上下文管理可能因版本不同而变化。

### 创建配置文件

**通过官方脚本快速配置**

以下命令从 Step 官方仓库 `stepfun-ai/Step-Cookbook` 下载中文脚本，下载成功后才执行。

macOS / Linux / WSL（Bash）

请先安装 `jq`，脚本使用它更新 JSON 配置。

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -fsSL https://raw.githubusercontent.com/stepfun-ai/Step-Cookbook/main/scripts/claude-key-setup/zh-CN/configure_claude.sh -o configure_claude.sh &&
  bash configure_claude.sh
```

Windows（普通 PowerShell）

使用当前用户的普通 PowerShell 即可，无需管理员权限。

```powershell theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
& {
  $ErrorActionPreference = "Stop"
  Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
  Invoke-WebRequest -Uri "https://raw.githubusercontent.com/stepfun-ai/Step-Cookbook/main/scripts/claude-key-setup/zh-CN/configure_claude.ps1" -OutFile "configure_claude.ps1"
  & .\configure_claude.ps1
}
```

接入 Step Plan 时，请在脚本菜单中选择 `2`，输入 API Key，并选择模型（默认 `step-5-preview`）。选择 `1` 会使用普通 API 通道。

脚本会备份已有配置并替换整个 `env` 对象，保留 `hooks`、`theme` 等其他顶层字段；原 `env` 中的额外变量会被移除。

**手动编辑配置文件**

将以下字段合并到用户级配置文件 `~/.claude/settings.json`，保留已有的 `permissions`、`hooks` 等设置。Windows 对应 `%USERPROFILE%\.claude\settings.json`；若设置了 `CLAUDE_CONFIG_DIR`，使用该目录下的 `settings.json`。文件不存在时先创建目录，再保存以下 JSON，将 `YOUR_STEP_API_KEY` 替换为实际密钥：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_STEP_API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.stepfun.com/step_plan"
  },
  "model": "step-5-preview"
}
```

模型 ID 可填写 `step-5-preview`、`step-3.7-flash`、`step-3.5-flash-2603` 或 `step-3.5-flash`。

#### 配置项说明

| 字段 | 位置 | 用途 |
| - | - | - |
| `ANTHROPIC_AUTH_TOKEN` | `env` | Step API Key，用于请求认证。 |
| `ANTHROPIC_BASE_URL` | `env` | 配置为 `https://api.stepfun.com/step_plan`，Claude Code 自动追加 `/v1/messages`。 |
| `model` | 顶层 | 主会话模型；启动参数 `--model` 或环境变量 `ANTHROPIC_MODEL` 可覆盖此项。 |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` 等 | `env`，可选 | 将内置模型档位映射到 Step 模型。 |
| `CLAUDE_CODE_SUBAGENT_MODEL` | `env`，可选 | 设置子 Agent 模型。 |
| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | `env`，可选 | 覆盖客户端对自定义模型的上下文窗口估计。 |
| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | `env`，可选 | 设置自动压缩使用的窗口，不超过模型上下文窗口。 |

可选：将以下模型别名和子 Agent 配置合并到 `env`。任务显式指定的模型需单独核对。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "ANTHROPIC_DEFAULT_SONNET_MODEL": "step-5-preview",
  "ANTHROPIC_DEFAULT_OPUS_MODEL": "step-5-preview",
  "ANTHROPIC_DEFAULT_HAIKU_MODEL": "step-5-preview",
  "ANTHROPIC_DEFAULT_FABLE_MODEL": "step-5-preview",
  "CLAUDE_CODE_SUBAGENT_MODEL": "step-5-preview"
}
```

首次接入先验证最小配置，再按需加入别名与子 Agent 设置。若后台任务仍请求内置模型名，请核对该任务显式指定的模型。

同名变量同时出现在配置文件 `env` 和终端环境时，配置文件中的值会覆盖终端值。切换服务后，请一并检查用户配置、项目配置及 `.zshrc` / `.bashrc` 中的旧地址和密钥，保存后重新启动 Claude Code。

### 设置推理强度

`step-5-preview` 支持以下推理强度：

| --effort | 适用任务 |
| - | - |
| `low` | 简单任务，优先速度与较低 token 消耗。 |
| `medium` | 一般推理与多步骤任务。 |
| `high` | 复杂推理、规划与代码分析。 |

调用 Step 5 Preview 时，`xhigh` 和 `max` 由 Step 服务端映射为 `high`。Claude Code 通过 Messages API 的 `output_config.effort` 传入该设置。

启动时指定本次会话的推理强度：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
claude --model step-5-preview --effort medium
```

保存默认档位时，将 `effortLevel` 合并到 `~/.claude/settings.json` 顶层，而不是 `env`：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "effortLevel": "medium"
}
```

保存后重启 Claude Code。若设置未生效，检查 `CLAUDE_CODE_EFFORT_LEVEL`、启动参数及项目或组织设置。

### 开启 1M 上下文

[`step-5-preview`](/docs/zh/guides/models/step-5-preview) 的模型上下文窗口为 **1M tokens**。若 `/context` 将其显示为未识别模型并按 200k 计算，将以下字段合并到 `~/.claude/settings.json`，保留已有配置：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_STEP_API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.stepfun.com/step_plan",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "1000000",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000"
  },
  "model": "step-5-preview"
}
```

说明：

* `CLAUDE_CODE_MAX_CONTEXT_TOKENS`：告诉 Claude Code 按 1M 窗口计算用量。必须写纯数字 `1000000`，不要写成 `1M` 或 `1000k`。
* `CLAUDE_CODE_AUTO_COMPACT_WINDOW`：将自动压缩窗口对齐到 1M。取值范围为 `100000`–`1000000`，同样只接受纯数字；客户端仍会预留输出与内部处理空间，可能在窗口填满前压缩。
* 保存后完全退出并重新启动 Claude Code，再输入 `/context` 确认窗口已接近 1M，而不再是 200k。
* 声明大于 200k 后，启动时可能出现「200K limit isn't enforced」类提示，属于预期行为。

通过官方脚本接入时，脚本不会自动写入上述两个字段，需要手动补进 `env`。

### 启动 Claude Code

进入任意代码项目目录：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
cd your-project
```

启动 Claude Code：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
claude
```

首次启动时若出现 `Do you want to use this API key?`，选择 `Yes` 即可。

## 测试接入

### 验证客户端对话

1. 保存配置，完全退出并重新启动 Claude Code。
2. 输入 `/status`，核对模型、认证方式和配置来源。
3. 发送「只回复 OK」，检查返回内容与流式输出。

### 验证 Agent 工具调用

在安装了 Python 的独立测试目录中，先创建一个输出 `Hello, world!` 的 `hello.py`，再向 Claude Code 发送：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
读取当前目录中的 hello.py，把它改成接受命令行参数 name。
未传参数时输出 Hello, Step5；传入 Ada 时输出 Hello, Ada。
使用本机可用的 Python 解释器分别运行这两种情况，检查输出。
如果验证失败，根据报错修正后重新运行。不要修改其他文件。
完成后汇报文件变更、执行的命令和运行结果。
```

按权限提示批准必要操作，核对读取、修改、运行的工具记录及两次输出。随后继续提问，确认会话保留任务上下文。

### 核对用量与路由

在 [Step 开放平台](https://platform.stepfun.com)按请求时间、模型与响应 ID 核对调用记录，确认使用 Step Plan 通道及对应额度。

## 常见问题

> **Q: 修改配置后不生效怎么办？**
>
> 重启后使用 `/status` 核对模型、认证与配置来源，依次检查项目配置、`--model`、`ANTHROPIC_MODEL`、`CLAUDE_CONFIG_DIR` 及组织设置。确认 `settings.json` 是有效 JSON。
>
> 以下 Bash / jq 命令只显示相关配置和密钥是否存在，不输出密钥值：
>
> ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> jq '{model, base_url: .env.ANTHROPIC_BASE_URL, context_window: .env.CLAUDE_CODE_MAX_CONTEXT_TOKENS, compact_window: .env.CLAUDE_CODE_AUTO_COMPACT_WINDOW, has_auth_token: (.env.ANTHROPIC_AUTH_TOKEN != null), has_api_key: (.env.ANTHROPIC_API_KEY != null)}' "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json"
> ```

> **Q: 返回 401 invalid\_api\_key 怎么办？**
>
> 将有效的 Step API Key 填入 `ANTHROPIC_AUTH_TOKEN`，检查密钥是否输入错误、被撤销或属于其他站点。若同时设置 `ANTHROPIC_API_KEY`，不要仅更新它而保留旧的 `ANTHROPIC_AUTH_TOKEN`。
>
> 曾通过 `/login` 登录其他账号时，先使用 `/status` 核对凭据来源；需要退出该登录态时，执行 `/logout` 后重启，再验证 Step 配置。

> **Q: 如何单独检查 Messages API 连通性？**
>
> 先通过 curl 检查端点、密钥和模型。以下命令适用于 Bash / Zsh；Windows 可在 WSL 或 Git Bash 中运行。
>
> ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> export STEP_API_KEY="YOUR_STEP_API_KEY"
>
> curl --silent --show-error --fail-with-body \
>   --write-out '\nHTTP %{http_code}\n' \
>   https://api.stepfun.com/step_plan/v1/messages \
>   -H "Authorization: Bearer ${STEP_API_KEY}" \
>   -H "Content-Type: application/json" \
>   -H "anthropic-version: 2023-06-01" \
>   -d '{
>     "model": "step-5-preview",
>     "max_tokens": 1024,
>     "messages": [{"role": "user", "content": "Reply only with OK."}]
>   }'
> ```
>
> **通过条件**：HTTP 200，响应 `type` 为 `message`，`content` 中有包含 `OK` 的 `text` 块。若只有 `thinking` 块，且 `stop_reason` 为 `max_tokens`，应提高输出预算后重试。

> **Q: 地址错误或 curl 成功但 Claude Code 失败怎么办？**
>
> Claude Code 在 `ANTHROPIC_BASE_URL` 后自动追加 `/v1/messages`。按下表检查地址：
>
> | ANTHROPIC\_BASE\_URL | 请求路径 | 说明 |
> | - | - | - |
> | `https://api.stepfun.com/step_plan` | `/step_plan/v1/messages` | Step Plan Messages 通道。 |
> | `https://api.stepfun.com/step_plan/v1` | `/step_plan/v1/v1/messages` | 重复 `/v1`，地址错误。 |
> | `https://api.stepfun.com/step_plan/v1/messages` | `/step_plan/v1/messages/v1/messages` | 重复接口路径，地址错误。 |
> | `https://api.stepfun.com` | `/v1/messages` | 普通按量付费 API，不使用 Step Plan 额度。 |
>
> 若 curl 正常而客户端失败，检查项目配置或用户配置是否覆盖了终端变量。需要进一步排查时，使用 `claude --debug` 查看日志。

> **Q: 后台任务或子 Agent 报模型错误怎么办？**
>
> 检查 `ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_DEFAULT_FABLE_MODEL`、`CLAUDE_CODE_SUBAGENT_MODEL` 及任务中显式指定的模型，确认它们使用可用的 Step 模型 ID。相关字段见上文配置项说明。

> **Q: /context 仍显示 200k 怎么办？**
>
> 确认正在使用 `step-5-preview`，配置目录正确，且 `env` 中的 `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 和 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 均为 `"1000000"`。完全退出并重启后再检查。官方脚本默认不写入这两项。

> **Q: 返回 model does not exist 怎么办？**
>
> 核对模型 ID、当前账号权限、目标通道以及子任务模型。客户端提示不识别自定义模型，不等于服务端拒绝该模型；以具体请求错误为准。

> **Q: 返回 402 quota\_exceeded 怎么办？**
>
> 先确认请求通道。Step Plan 通道检查订阅和 Credit；普通 API 通道检查账户余额或额度。

若仍需帮助，请提供客户端版本、错误信息、发生时间、脱敏配置及请求 ID，通过[技术支持](/docs/zh/guides/contact-us)进一步排查。

## 相关文档

* [Messages API](/docs/zh/api-reference/chat/messages-create)
* [Step 5 Preview](/docs/zh/guides/models/step-5-preview)
* [Step Plan 概述](/docs/zh/step-plan/overview)


# Cline
Source: https://platform.stepfun.com/docs/zh/guides/developer/integrations/cline



Cline 是运行在 VS Code、Cursor 等编辑器中的编码 Agent，支持 Plan / Act 工作模式、文件编辑和终端命令执行。通过 Step Plan Provider，可在编辑器中使用 Step 模型完成开发任务。

## 接入条件

* 已安装 VS Code 或 Cursor。运行下方 Python 验证示例时，还需安装 Python 3。
* [Step Plan 订阅](https://platform.stepfun.com/step-plan)有效、额度可用，且具备所用模型的调用权限。
* 已在 [StepFun 开放平台密钥管理](https://platform.stepfun.com/interface-key)页面创建 API Key。

## 安装 Cline

在编辑器扩展市场中搜索并安装 Cline，扩展标识为 `saoudrizwan.claude-dev`。

## 配置 Step Plan

### 选择 Provider

1. 打开 Cline 面板，进入设置中的 `API Configuration`。首次使用时，从 `Configure your provider` 进入。
2. 在 `API Provider` 中选择 `StepFun Step Plan (China)`。
3. 填写 API Key，并选择 `step-5-preview`。其余连接参数按下表确认。

| 配置项 | 填写值 |
| - | - |
| `API Provider` | `StepFun Step Plan (China)`。 |
| `Base URL` | `https://api.stepfun.com/step_plan/v1`，使用预设时确认已填入该地址。 |
| `API Key` | Step API Key，不包含 `Bearer ` 前缀或首尾空格。部分界面将该字段显示为 `OpenAI Compatible API Key`。 |
| `Model ID` | `step-5-preview`。 |

如果当前版本没有 Step Plan 预设，选择 `OpenAI Compatible`，手动填写同一 Base URL、API Key 和 Model ID。Cline 自动追加 `/chat/completions`，完整请求路径为 `/step_plan/v1/chat/completions`。

### 确认模型参数

展开 `MODEL CONFIGURATION`。以下配置适用于 [Step 5 Preview](/docs/zh/guides/models/step-5-preview)；使用预设时，核对已有值即可。

| 配置项 | 设置 | 说明 |
| - | - | - |
| `Supports Images` | 开启 | 允许发送图像输入。 |
| `Context Window` | `1000000` | 客户端使用的上下文窗口。 |
| `Max Output Tokens` | `65536` | 为推理和正文保留输出预算，避免设为过小值。 |
| `Input / Output Price / 1M` | 保留默认 | 用于 Cline 的成本估算，实际用量以平台记录为准。 |
| `Temperature` | 保留默认 | 无需为接入单独设置。 |
| `Reasoning Effort` | 保留默认，或选择 `High` | 需要较高推理强度时再调整。Step 5 Preview 支持 `low`、`medium`、`high`。 |

切换到其他模型时，按对应模型规格调整上下文与输出预算。配置完成后保存，并新建任务。

## 接入 StepSearch MCP

需要联网搜索或获取网页内容时，可配置 [StepSearch](/docs/zh/guides/developer/search-mcp)。该服务通过 Step Plan 端点提供 `web_search` 和 `web_fetch`。

1. 在 Cline 面板打开 `MCP Servers`，进入 `Configure`，选择 `Configure MCP Servers`。
2. 在打开的 `cline_mcp_settings.json` 中合并以下配置，保留其他 MCP 服务，将 `YOUR_STEP_API_KEY` 替换为实际密钥：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "mcpServers": {
    "step-search": {
      "type": "streamableHttp",
      "url": "https://api.stepfun.com/step_plan/v1/mcp/web_search/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_STEP_API_KEY"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

3. 保存后，在 MCP Servers 面板检查 `step-search` 是否已连接，并确认工具列表包含 `web_search` 和 `web_fetch`。
4. 新建任务，请 Cline 使用其中一个工具完成搜索或网页抓取，核对工具调用记录与返回结果。

`type` 必须使用 Cline 的 `streamableHttp` 写法；省略该字段会使用兼容旧版的 SSE 传输。`autoApprove: []` 保留逐次确认，首次调用时按提示批准即可。

> [!WARNING]
>
> MCP 配置中的 API Key 以明文保存。请使用 Cline 的用户配置文件，不要将真实密钥提交到代码仓库或分享给他人。任何获得该密钥的人都可能以您的权限发起请求并消耗额度。

## 验证接入

### 验证对话

新建任务并输入 `请只回复 OK。`，预期返回 `OK`。

### 验证工具调用

1. 在独立测试目录中创建 `README.md`，内容为 `Cline Step Plan test`，然后在编辑器中打开该目录。
2. 在 Cline 中选择 `Act` 模式，发送以下指令：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
读取 README.md，创建 hello.py，使其打印 "Hello, world!"。
使用本机可用的 Python 解释器运行 hello.py，并报告执行命令和实际输出。
不要修改 README.md 或其他已有文件。
```

3. 按提示批准必要的文件与命令操作，核对读取、编辑和执行记录。确认 `hello.py` 实际生成，输出为 `Hello, world!`，且 `README.md` 未被修改。

自动批准是可选设置，手动批准也可完成上述验证。

### 验证配置保存

重启编辑器后，检查 Provider 与模型选择是否保留，并重新发起一次简短对话。

## 常见问题

> **Q: 找不到 Step Plan Provider 怎么办？**
>
> 更新 Cline 扩展；也可选择 `OpenAI Compatible`，使用 `https://api.stepfun.com/step_plan/v1` 和实际 API Key，手动填写 `step-5-preview` 或账号可用的其他模型 ID。

> **Q: 提示 Connection error 怎么办？**
>
> 检查 Base URL、网络连接、API Key 和模型权限。Base URL 保留到 `/step_plan/v1`，API Key 字段不添加 `Bearer ` 前缀。查看完整错误信息，分别排查认证、模型和请求参数；仅查询模型列表成功还需继续验证实际对话请求。

> **Q: 返回 401 怎么办？**
>
> 确认密钥完整、有效，没有首尾空格，且属于所选 Provider 对应站点的账号。模型连接使用 API Key 字段，MCP 则使用 `Authorization: Bearer YOUR_STEP_API_KEY`，两处填写形式不同。

> **Q: Cline 只回复文字，没有修改文件或执行命令怎么办？**
>
> 确认已选择 `Act` 模式并打开目标项目。检查是否有等待确认的工具调用，按提示批准后继续；无需为此开启所有自动批准选项。若配置刚发生变化，新建任务后重试。

> **Q: 回复为空、被截断或推理阶段没有正文怎么办？**
>
> 推理阶段可能暂时没有正文。若请求结束后仍无正文，检查停止原因、错误信息与输出预算；预算过小可能在正文生成前耗尽。使用 Step 5 Preview 时，先核对模型参数表中的配置，再根据具体错误调整。

> **Q: MCP 中没有 step-search 或对应工具怎么办？**
>
> 确认配置合并在 `mcpServers` 下，`type` 为 `streamableHttp`，`disabled` 为 `false`，且请求头包含完整的 `Bearer ` 前缀和密钥。保存后刷新或重新连接服务，并检查连接日志。


# CodeGPT
Source: https://platform.stepfun.com/docs/zh/guides/developer/integrations/codegpt



CodeGPT 是运行在 VS Code 中的 AI 编码助手扩展，支持 Chat 与 Agent。通过 Custom Provider 的 OpenAI 兼容接口，可接入 Step Plan 模型进行对话和代码修改。

## 接入条件

* 已安装 VS Code 和 CodeGPT 扩展，扩展标识为 `danielsanmedium.dscodegpt`。配置步骤对应 CodeGPT 3.24.73。
* 已登录 CodeGPT 账号，可访问模型管理中的 Local / Custom 配置。
* [Step Plan 订阅](https://platform.stepfun.com/step-plan)有效、额度可用，且具备所用模型的调用权限。
* 已在 [StepFun 开放平台密钥管理](https://platform.stepfun.com/interface-key)页面创建 API Key。

## 配置连接

1. 打开 CodeGPT 面板，进入 Manage AI Models。
2. 选择 Local，再选择 Custom (any OpenAI-compatible server)。
3. 填写连接参数。

| 配置项 | 填写内容 |
| - | - |
| Base URL / endpoint | `https://api.stepfun.com/step_plan/v1` |
| API Key | StepFun API Key |

CodeGPT 自动在 Base URL 后追加 `/chat/completions`。上述地址使用 Step Plan 订阅额度。

4. 点击 Test。显示 `Connected` 并加载模型列表后，选择 `step-5-preview`。
5. 点击 Save & close 保存。
6. 在聊天模型选择器中选择 Custom 下的 `step-5-preview`，新建对话。

Custom Provider 的地址、密钥和模型通过模型管理面板配置。

## 验证接入

### 验证对话

在 Chat 中输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请只回复 OK。
```

预期返回 `OK`。

### 验证工具调用

在安装了 Python 的独立测试目录中创建 `README.md`，内容为 `CodeGPT Step Plan test`，并在 VS Code 中打开该目录。

切换到 Agent 模式，确认仍选中 Custom 下的 `step-5-preview`，输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
读取 README.md，创建 hello.py，输出 Hello, StepFun!。
使用本机可用的 Python 解释器运行 hello.py，并汇报执行命令和输出。
不要修改其他文件。
```

按扩展提示授权文件操作和命令执行，核对工具记录、生成的 `hello.py` 和 `Hello, StepFun!` 运行输出。

### 核对用量

在 [StepFun 开放平台](https://platform.stepfun.com)的使用详情中，按请求时间核对模型 ID 和计费来源，确认调用使用 Step Plan。

## 常见问题

> **Q: Test 连接失败怎么办？**
>
> 核对 Base URL、API Key 和网络连接。地址应为 `https://api.stepfun.com/step_plan/v1`，密钥应属于对应平台账号。修改后重新点击 Test。

> **Q: 模型列表为空或没有目标模型怎么办？**
>
> 确认 Test 已显示 `Connected`，并检查账号的 Step Plan 订阅与模型权限。重新测试连接后选择模型。

> **Q: 如何确认使用的是 Step 模型？**
>
> 模型选择器中选择 Custom 下的 `step-5-preview`，并在 StepFun 开放平台的使用详情中核对本次请求的模型及计费来源。

> **Q: Chat 正常，但 Agent 无法执行任务怎么办？**
>
> 确认已切换到 Agent 模式并打开项目目录，检查文件和终端权限。Python 示例还需要本机具有可用的 Python 解释器。


# Codex CLI
Source: https://platform.stepfun.com/docs/zh/guides/developer/integrations/codex



Codex CLI 是 OpenAI 开源的终端编码 Agent，支持文件读取、代码修改和命令执行。通过自定义 Provider，可在本地项目中使用 Step Plan 模型完成开发任务。

## 接入条件

* 已安装 Node.js、npm、`curl` 和 Python 3。以下终端命令适用于 Bash 或 zsh，Windows 用户可在 WSL 中执行。
* [Step Plan 订阅](https://platform.stepfun.com/step-plan)有效、额度可用，且具备所用模型的调用权限。
* 已在 [StepFun 开放平台密钥管理](https://platform.stepfun.com/interface-key)页面创建 API Key。

## 接入说明

* Codex CLI 0.154.0 仅支持 Responses API，`wire_api` 使用 `responses`。Step Plan 提供 `/step_plan/v1/responses`，可直接连接，无需协议转换代理。
* 用户配置写入 `$CODEX_HOME/config.toml`，`CODEX_HOME` 默认为 `~/.codex`。API Key 通过环境变量或该目录下的 `.env` 提供，不写入 `config.toml`。
* Codex 的内置模型目录主要提供 OpenAI 模型元数据。本配置通过 `model_catalog_json` 声明 Step 模型名称、上下文窗口和输入能力，使其在 `/model` 中可选；模型目录只在 Step 专用 profile 中启用。

## 安装 Codex CLI

安装 Codex CLI 0.154.0：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
npm install -g @openai/codex@0.154.0
```

检查安装版本：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
codex --version
```

预期输出为 `codex-cli 0.154.0`。

## 配置 Step Plan

### 确定配置目录

在终端执行以下命令，保留已有的 `CODEX_HOME` 设置；未设置时使用默认目录：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_HOME"
export CODEX_HOME="$(cd "$CODEX_HOME" && pwd)"
```

如需与日常配置分开，改用独立目录后再继续配置：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export CODEX_HOME="$HOME/.codex-step-plan"
mkdir -p "$CODEX_HOME"
```

请在同一终端中完成后续配置与启动。以后使用独立配置目录时，也需先设置对应的 `CODEX_HOME`。

### 添加 Provider

编辑 `$CODEX_HOME/config.toml`，合并以下配置，保留其他设置。若已存在 `[model_providers.stepfun]`，更新该表即可。

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[model_providers.stepfun]
name = "StepFun Step Plan"
base_url = "https://api.stepfun.com/step_plan/v1"
env_key = "STEP_API_KEY"
wire_api = "responses"
```

| 字段 | 说明 |
| - | - |
| `model_providers.stepfun` | Provider 标识，后续通过 `model_provider = "stepfun"` 引用。 |
| `base_url` | Step Plan 基础地址。Codex 自动追加 `/responses`，完整请求路径为 `/step_plan/v1/responses`。 |
| `env_key` | 提供 API Key 的环境变量名称，不是密钥本身。 |
| `wire_api` | 使用 Responses API，填写 `responses`。 |

Provider 定义必须放在用户级配置中。Codex 会忽略项目 `.codex/config.toml` 中的 `model_provider` 和 `model_providers`。自定义 Provider 也不能使用 `openai`、`ollama`、`lmstudio` 等保留标识。

### 设置 API Key

将 `YOUR_STEP_API_KEY` 替换为实际密钥，选择以下一种方式配置。

在启动 Codex 的终端中设置环境变量：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export STEP_API_KEY="YOUR_STEP_API_KEY"
```

也可编辑 `$CODEX_HOME/.env`，添加或更新以下内容，由 Codex 启动时加载：

```dotenv theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
STEP_API_KEY=YOUR_STEP_API_KEY
```

设置文件权限：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
chmod 600 "$CODEX_HOME/.env"
```

`.env` 以明文保存 API Key，请勿将该文件提交到代码仓库或分享给他人。

### 创建模型目录

1. 下载与 Codex CLI 0.154.0 对应的默认 Agent 指令，作为模型目录中的 `base_instructions`：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -fsSL https://raw.githubusercontent.com/openai/codex/rust-v0.154.0/codex-rs/protocol/src/prompts/base_instructions/default.md \
  -o "$CODEX_HOME/default.md"
```

2. 确认文件非空：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
test -s "$CODEX_HOME/default.md" && wc -c "$CODEX_HOME/default.md"
```

3. 生成 `$CODEX_HOME/step-catalog.json`：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
python3 - <<'PY'
import json
import os

home = os.environ["CODEX_HOME"]

with open(os.path.join(home, "default.md"), encoding="utf-8") as instructions_file:
    base_instructions = instructions_file.read()

def entry(slug, name, description, context_window, input_modalities):
    return {
        "slug": slug,
        "display_name": name,
        "description": description,
        "context_window": context_window,
        "input_modalities": input_modalities,
        "base_instructions": base_instructions,
        "visibility": "list",
        "supported_in_api": True,
        "priority": 1,
        "availability_nux": None,
        "upgrade": None,
        "default_reasoning_level": "medium",
        "supported_reasoning_levels": [
            {"effort": "low", "description": "较低推理强度"},
            {"effort": "medium", "description": "中等推理强度（默认）"},
            {"effort": "high", "description": "较高推理强度"},
        ],
        "supports_reasoning_summaries": True,
        "default_reasoning_summary": "auto",
        "support_verbosity": False,
        "default_verbosity": None,
        "apply_patch_tool_type": "freeform",
        "web_search_tool_type": "text",
        "shell_type": "shell_command",
        "truncation_policy": {"mode": "tokens", "limit": 10000},
        "supports_parallel_tool_calls": False,
        "supports_image_detail_original": False,
        "effective_context_window_percent": 95,
        "experimental_supported_tools": [],
        "supports_search_tool": False,
    }

models = [
    entry("step-5-preview", "Step 5 Preview", "StepFun 1M 多模态", 1000000, ["text", "image"]),
    entry("step-3.7-flash", "Step 3.7 Flash", "StepFun 256K", 256000, ["text", "image"]),
    entry("step-3.5-flash", "Step 3.5 Flash", "StepFun 256K", 256000, ["text"]),
]

catalog_path = os.path.join(home, "step-catalog.json")

with open(catalog_path, "w", encoding="utf-8") as catalog_file:
    json.dump({"models": models}, catalog_file, ensure_ascii=False, indent=2)

print("已生成:", catalog_path)
print("模型:", [model["slug"] for model in models])
PY
```

生成结果应包含 `step-5-preview`、`step-3.7-flash` 和 `step-3.5-flash`。可按账号权限增删 `entry(...)` 条目。模型目录字段与 Codex 版本相关，升级后应按目标版本重新检查。

### 创建 Step 专用配置

新建 `$CODEX_HOME/step.config.toml`。首次创建时可执行以下命令；文件已存在时，请合并配置，保留其他设置。

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
cat > "$CODEX_HOME/step.config.toml" <<EOF
model = "step-5-preview"
model_provider = "stepfun"
model_catalog_json = "$CODEX_HOME/step-catalog.json"
web_search = "disabled"
EOF
```

检查配置，确认 `model_catalog_json` 是绝对路径：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
cat "$CODEX_HOME/step.config.toml"
```

`--profile step` 会在基础 `config.toml` 之上加载 `step.config.toml`，并复用其中定义的 Provider。`model_catalog_json` 会替换启动时使用的模型目录，因此应保留在专用 profile 中。不带 `--profile step` 启动时，不加载该 profile。

## 启动 Codex CLI

1. 确认所需文件存在：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
ls "$CODEX_HOME"/config.toml \
   "$CODEX_HOME"/step.config.toml \
   "$CODEX_HOME"/step-catalog.json
```

2. 在项目目录中启动：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
codex --profile step
```

3. 核对当前模型为 `step-5-preview`、Provider 为 `stepfun`。输入 `/model`，检查是否可以选择模型目录中的 Step 模型。

恢复此前使用 Step Provider 创建的会话时，继续指定相同的 profile，将 `YOUR_SESSION_ID` 替换为实际会话 ID：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
codex resume --profile step YOUR_SESSION_ID
```

`/model` 切换当前 Provider 下的模型。需要使用其他 Provider 时，通过对应的 profile 启动独立会话。

## 接入 StepSearch MCP

[StepSearch](/docs/zh/guides/developer/search-mcp) 提供 `web_search` 和 `web_fetch`，用于联网搜索与网页内容获取。需要这些能力时，可通过 Step Plan 端点接入。

1. 确认已按前文配置 `STEP_API_KEY`，然后注册 MCP 服务：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
codex mcp add step-search \
  --url https://api.stepfun.com/step_plan/v1/mcp/web_search/mcp \
  --bearer-token-env-var STEP_API_KEY
```

2. 检查注册结果：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
codex mcp list
```

3. 重新启动 `codex --profile step`，通过 `/mcp` 检查服务与工具是否已加载，再发起一次搜索或网页抓取任务，核对工具调用记录及返回结果。

`codex mcp add` 使用当前 `CODEX_HOME`，配置不只作用于 `step` profile。如需与日常 MCP 设置分开，请使用独立配置目录。Step 专用 profile 通过 `web_search = "disabled"` 关闭内置网页搜索，搜索工具由 StepSearch MCP 提供。

## 验证接入

### 验证对话

在交互会话中输入 `请只回复 OK。`，预期返回 `OK`。也可在项目目录中执行只读验证：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
codex exec --profile step --sandbox read-only "请只回复 OK。" < /dev/null
```

### 验证工具调用

在独立测试目录中创建 `README.md`，内容为 `Codex Step Plan test`。从该目录启动 Codex，输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
读取 README.md，创建 hello.py，使其打印 "Hello, world!"。
使用本机可用的 Python 解释器运行 hello.py，并报告执行命令和实际输出。
不要修改 README.md 或其他已有文件。
```

根据提示确认必要的操作权限，核对文件读取、创建和命令执行记录。确认 `hello.py` 实际生成，输出为 `Hello, world!`，且 `README.md` 未被修改。

## 常见问题

> **Q: 启动后要求登录 ChatGPT 怎么办？**
>
> 核对 `CODEX_HOME`、`step.config.toml` 中的 `model_provider = "stepfun"`，以及启动命令是否包含 `--profile step`。确认用户级 `config.toml` 中存在对应 Provider，且 API Key 已通过环境变量或 `.env` 提供。使用独立配置目录时，在当前终端重新设置 `CODEX_HOME` 后启动。

> **Q: /model 中没有 Step 模型或出现 Model metadata not found 怎么办？**
>
> 检查所选 profile 的 `model_catalog_json` 是否指向有效的绝对路径，以及目录中的模型 ID 是否正确。修改后重启 Codex；若仍显示旧列表，退出 Codex，移除当前 `CODEX_HOME` 下的 `models_cache.json` 后重试。

> **Q: 模型目录报 missing field 怎么办？**
>
> 模型目录缺少当前 Codex 版本要求的字段。使用与目标版本匹配的结构重新生成 `step-catalog.json`，并确认 `default.md` 下载成功且非空。不要将其他版本的精简目录直接用于当前版本。

> **Q: 连接失败、持续重连或返回 401 怎么办？**
>
> 查看完整错误信息，检查网络连接、API Key 状态与模型权限。`base_url` 使用 `https://api.stepfun.com/step_plan/v1`，`wire_api` 使用 `responses`；确认 `env_key` 与实际环境变量名称一致，且密钥属于所用端点对应的账号。

> **Q: codex exec 一直等待标准输入怎么办？**
>
> 如果输出停留在 `Reading additional input from stdin...`，且无需通过标准输入提供内容，在命令末尾添加 `< /dev/null`。

> **Q: 回复为空或返回 incomplete 怎么办？**
>
> 检查服务端返回状态、错误详情与 Token 用量。推理消耗和输出预算不足都可能影响正文生成；确认具体原因后，再使用目标客户端版本与服务端支持的参数调整。

> **Q: MCP 已注册，但会话中没有搜索工具怎么办？**
>
> 核对注册与启动时的 `CODEX_HOME` 是否一致，并检查 `STEP_API_KEY`。通过 `codex mcp list` 检查配置，重启交互会话后用 `/mcp` 检查连接状态。若在 `codex exec` 中使用，也需单独确认该运行方式实际加载并调用了工具。


# Cursor
Source: https://platform.stepfun.com/docs/zh/guides/developer/integrations/cursor



本文介绍如何将 StepFun 模型接入 Cursor，在 Chat / Agent 中完成代码生成、文件修改等开发任务。

## 接入条件

### Cursor 账号要求

需要有效的 **Cursor 付费订阅**（例如 Pro 或 Teams），用于启用 BYOK（Bring Your Own Key，自带 API Key）。**Free / Hobby 免费账号不能通过本文方式在 Cursor 内置 Chat / Agent 中调用 Step 模型。**

### 安装 Cursor

从 Cursor 官网下载并安装编辑器。建议使用 **Cursor 3.15.20 或更高版本**。

### 选择计费方式

* **普通 API（按量付费）**：确认账户有可用余额或额度，且具备所用模型的调用权限。
* **Step Plan（订阅额度）**：确认 [Step Plan 订阅](https://platform.stepfun.com/step-plan)有效、额度可用，且具备所用模型的调用权限。

### 获取 API Key

前往 [StepFun 开放平台密钥管理](https://platform.stepfun.com/interface-key)页面创建 API Key。

## 配置 Cursor

> [!NOTE]
>
> 本配置用于 Chat / Agent；代码自动补全（Tab）仍使用 Cursor 内置模型。

> [!WARNING]
>
> **Override OpenAI Base URL** 是全局覆盖设置。开启后，走 OpenAI 协议的请求会统一发送至自定义端点。需要使用 Cursor 订阅内置模型时，请先[关闭 Override](#切回-cursor-内置模型)，再新建会话。

**1. 打开模型设置**

打开 **Cursor Settings**，进入 **Models** 页面。也可以通过命令面板搜索 `Cursor Settings` 打开设置。

**2. 配置连接**

在 Models 页面的连接配置区域填写以下内容（Base URL 以 Step Plan 为例）：

| 字段 | 填写内容 |
| - | - |
| OpenAI API Key | `<STEP_API_KEY>` |
| Use OpenAI API Key | `ON` |
| Override OpenAI Base URL | `ON` |
| Base URL | `https://api.stepfun.com/step_plan/v1` |

在 **OpenAI API Key** 字段中填写 Step API Key，用于请求认证。

> [!NOTE]
>
> 根据计费方式选择 Base URL：
>
> 普通 API（按量付费）：`https://api.stepfun.com/v1`\\
>
> Step Plan（订阅额度）：`https://api.stepfun.com/step_plan/v1`
>
> Base URL 不包含 `/chat/completions`；Cursor 会自动追加该路径。

**3. 添加自定义模型**

在 Models 页面添加自定义模型，**Model ID** 可填写 `step-5-preview`、`step-3.7-flash`、`step-3.5-flash-2603` 或 `step-3.5-flash`。

[`step-5-preview`](/docs/zh/guides/models/step-5-preview) 的模型上下文窗口为 **1M tokens**。

**4. 选择模型并新建会话**

打开 Chat 或 Agent 面板，选择刚添加的 Step 模型，并新建会话进行测试。

## 验证接入

### 文本连通

在新会话中输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请只回复 OK。
```

**预期结果**：返回 `OK`，且未出现 `401`、`403` 或协议错误。

### Agent 工具调用

在已安装 Python 的独立测试目录中，创建一个 `README.md` 文件，内容为 `Cursor Step Plan test`。在 Cursor 中打开该目录，使用选中了 Step 模型的新 **Agent** 会话，输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Read README.md in the current workspace.
Create a hello world script in Python named hello.py that prints exactly "Hello, world!".
Run the script with an available Python interpreter and report the command and output.
Do not modify README.md or any other files.
```

检查 Agent 提议的文件操作和命令后，再按需授权执行。

**预期结果**：

1. 会话中出现读取 `README.md`、创建 `hello.py` 和执行命令的真实工具调用记录。
2. 工作目录中实际生成 `hello.py`，可在编辑器中核对文件内容与变更。
3. 运行输出为 `Hello, world!`。

仅在对话中返回一段代码，不代表已完成 Agent 工具调用验证。

### 请求路由

在 [Step 开放平台](https://platform.stepfun.com)的用量或请求记录中，确认本次调用的模型 ID 与 Cursor 中的选择一致，计费通道与配置的普通 API 或 Step Plan Base URL 对应。

### 重启验证（可选）

完全退出并重新打开 Cursor，确认 Models 配置保留，并在新会话中使用同一模型重复文本连通测试。

## 切回 Cursor 内置模型

仅切换模型选择器，不会自动取消自定义 Base URL。

1. 在 **Cursor Settings → Models** 中关闭 **Override OpenAI Base URL**。
2. 按需关闭 **Use OpenAI API Key**。
3. 新建会话，选择要使用的 Cursor 内置模型。

## 常见问题

> **Q: 配置 API Key 后仍提示升级或达到用量上限怎么办？**
>
> 先在 Cursor Dashboard 确认当前登录账号的订阅状态：
>
> * **Free / Hobby**：免费账号不支持 BYOK，请先满足 [Cursor 账号要求](#cursor-账号要求)。
> * **有效付费订阅**：确认使用的是已订阅的 Cursor 账号、自定义 Step 模型及新会话。团队账号还需确认管理员允许 BYOK，并检查团队的使用限制；Step 账户的模型权限及余额或订阅额度按[所选计费方式](#选择计费方式)检查。

> **Q: 配置后提示 Connection error 怎么办？**
>
> 依次检查：
>
> 1. **Override OpenAI Base URL** 已开启，Base URL 与计费方式一致：普通 API 使用 `https://api.stepfun.com/v1`，Step Plan 使用 `https://api.stepfun.com/step_plan/v1`。
> 2. Base URL 没有误填 `/chat/completions` 等完整接口路径。
> 3. API Key 有效，且 **Use OpenAI API Key** 已开启。
> 4. Model ID 拼写正确，账号具备所选通道下的模型调用权限。
> 5. 当前网络可访问 `https://api.stepfun.com`；若使用代理，同时检查代理配置。

> **Q: 配置后提示 401 Incorrect API key 怎么办？**
>
> 检查以下项目：
>
> * Key 是否复制完整，是否包含多余空格或换行，是否已被撤销。
> * Key 是否来自当前中文站（`.com`）账号，是否误用了其他站点或服务商的密钥。
> * **Use OpenAI API Key** 是否为 `ON`。
>
> 重新粘贴完整 Key 并启用开关后，新建会话重试。权限或额度问题请按[所选计费方式](#选择计费方式)检查账户状态。

> **Q: 配置后提示 model not found / BAD\_MODEL\_NAME 怎么办？**
>
> 1. 确认 Model ID 填写正确，例如 `step-5-preview`，且账号具备所选通道下的模型调用权限。
> 2. 确认 Override 已开启，Base URL 与所选计费方式一致。
> 3. 在新建的 Chat / Agent 会话中选择该自定义模型。

> **Q: 为什么 Chat 可用，但 Agent 无法执行任务？**
>
> * 确认当前使用 **Agent** 模式，而不只是文本对话模式。
> * 确认选中的是自定义 Step 模型，不是 Auto，并用新会话重试最小 Agent 任务。
> * 检查 Cursor 是否在等待文件修改或终端命令授权；Python 示例还需要本机有可用的 Python 解释器。
> * 区分模型请求失败与工具执行失败：例如 Python 未安装或命令被拒绝，不代表模型连接失败。

若仍无法解决，联系[技术支持](/docs/zh/guides/contact-us)时提供 Cursor 版本、模型 ID、发生时间、脱敏后的错误信息和 Cursor Request ID。

获取 Cursor Request ID：在对应 Chat / Agent 会话右上角打开 **…** 菜单，选择 **Copy Request ID**。

## 相关文档

* [Step Plan 快速开始](/docs/zh/step-plan/quick-start)
* [Step 5 Preview 模型规格](/docs/zh/guides/models/step-5-preview)


# DeepSeek Harness
Source: https://platform.stepfun.com/docs/zh/guides/developer/integrations/deepseek-harness



DeepSeek Harness（`dsh`）是 DeepSeek 开源的 Agent Harness。本文介绍如何通过自定义 Provider 接入 Step 5 Preview，包括 Web UI 配置、配置文件、验证与常见问题。

> [!NOTE]
>
> dsh 目前处于开发者预览阶段，界面和配置可能随版本变化。本文按当前官方模型配置文档整理；运行前请阅读项目的[安全说明](https://github.com/deepseek-ai/deepseek-harness/blob/master/SAFETY.md)，只在可信工作目录中使用，并谨慎授权文件操作和命令执行。

## 配置速查

| 配置项 | 值 |
| - | - |
| Provider ID | `stepfun` |
| API protocol | `openai-completions` |
| Step Plan Base URL | `https://api.stepfun.com/step_plan/v1` |
| 按量付费 API Base URL | `https://api.stepfun.com/v1` |
| 模型 ID | `step-5-preview` |
| 上下文窗口 | 1,000,000 tokens |
| API Key | [控制台密钥管理](https://platform.stepfun.com/interface-key) |

## 前置条件

### 安装并启动 dsh

准备 Node.js 22.19+（22.x）或 24+ 和 npm，建议使用当前 LTS，并以 dsh 官方要求为准。然后在可信工作目录中运行：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
npx -y @deepseek-ai/dsh web
```

首次运行会下载所需包。本机启动时默认打开 `http://127.0.0.1:3080`；通过 SSH 启动时可能只打印地址。具体启动选项见 [dsh 官方仓库](https://github.com/deepseek-ai/deepseek-harness)。

### 准备 API Key

在[控制台](https://platform.stepfun.com/interface-key)创建 API Key。使用 Step Plan 前请确认[订阅](https://platform.stepfun.com/plan-subscribe)和模型权限；使用按量付费 API 时请确认账户余额及权限。不要将真实密钥提交到代码仓库或分享在截图中。

## 方式一：通过 Web UI 配置

> [!WARNING]
>
> 使用 Step Plan 订阅额度时，必须选择 `/step_plan/v1`，并确认订阅有效、具备对应模型权限。普通 `/v1` 是按量付费 API，不会因为已有 Step Plan 订阅而自动使用订阅额度。下文示例默认使用 Step Plan；按量付费用户请统一替换 Base URL。

**1. 打开模型设置**

在 dsh Web UI 中进入 **Settings → Models**，选择 **Add a custom provider**。

**2. 填写 Provider**

| 字段 | 填写内容 |
| - | - |
| Provider ID | `stepfun`，这是提供方标识，不是模型名 |
| Display name | `StepFun` |
| Base URL | `https://api.stepfun.com/step_plan/v1` |
| API protocol | `openai-completions` |
| API key | 您的 StepFun API Key |

Provider ID 保存后不能直接重命名；要使用新标识，请创建新的 Provider。

**3. 添加模型**

在模型列表中点击 **Add model**，将模型 ID 和显示名称都填为 `step-5-preview`。在 **Model options** 中将上下文窗口设为 `1000000`（1,000,000 tokens，输入时不加逗号）；需要图片输入时，在 **Input types** 中保留 **Text** 并选中 **Image**。

可选添加 `step-3.7-flash`，上下文窗口为 256,000 tokens（填写 `256000`）。模型规格分别见 [Step 5 Preview](/docs/zh/guides/models/step-5-preview) 和 [Step 3.7 Flash](/docs/zh/guides/models/step-3.7-flash)，可用模型以当前账户权限为准。

> [!WARNING]
>
> 模型 ID 不能为空。仅点击 Add model 而不填写 ID 会导致保存失败；Provider ID 应为 `stepfun`，模型 ID 是 `step-5-preview`。

**4. 保存并选择模型**

点击 **Create provider**，新建会话，在模型选择器中选择 StepFun 下的 `step-5-preview`，发送一条简单消息验证。已有会话可能保留之前使用的模型。

> [!NOTE]
>
> Web UI 保存的密钥存储在运行 dsh 的机器上的 `$DSH_HOME/.credentials.yaml` 中，配置只保留凭据引用；如果 dsh 部署在远程服务器上，密钥也保存在服务器上。调用模型时仍会将密钥作为认证信息发送给配置的 API 服务，请核对 Base URL。

## 方式二：通过配置文件

> [!WARNING]
>
> 使用 Step Plan 订阅额度时，必须选择 `/step_plan/v1`，并确认订阅有效、具备对应模型权限。普通 `/v1` 是按量付费 API，不会因为已有 Step Plan 订阅而自动使用订阅额度。下文示例默认使用 Step Plan；按量付费用户请统一替换 Base URL。

编辑 `~/.dsh/settings.yaml`。如果设置了 `DSH_HOME`，请使用该目录下的 `settings.yaml`。将以下配置合并到现有 `llm-pi-ai.providers` 中，不要覆盖其他 Provider 或重复创建同名 YAML 键。

```yaml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
llm-pi-ai:
  providers:
    stepfun:
      apiKeyEnv: STEPFUN_API_KEY
      api: openai-completions
      baseURL: https://api.stepfun.com/step_plan/v1
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: step-5-preview
          name: step-5-preview
          contextWindow: 1000000
          input: [text, image]
        - id: step-3.7-flash
          name: step-3.7-flash
          contextWindow: 256000
          input: [text, image]
```

`compat` 将系统指令按兼容的角色发送，并使用 `max_tokens` 指定输出限制；这些选项见 [dsh 请求兼容性文档](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/providers.md#request-compatibility)。`input` 声明 dsh 可发送的输入类型，不代表模型的全部模态能力。

### 设置凭据

选择以下一种方式：

* **Web UI（推荐）**：启动 dsh，进入 **Settings → Models**，编辑 `stepfun`，填入 API Key 并保存。
* **环境变量**：将 `YOUR_STEP_API_KEY` 替换为您的 API Key，在启动 dsh 的同一个终端中设置变量，再启动进程。以下命令适用于 macOS / Linux / WSL 的 Bash 或 Zsh：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export STEPFUN_API_KEY="YOUR_STEP_API_KEY"
npx -y @deepseek-ai/dsh web
```

> [!NOTE]
>
> `settings.yaml` 和通过 Web UI 保存的凭据通常在下一次请求生效，无需重启。终端中的新环境变量不会自动传入已经运行的进程；使用环境变量方式时，需要从已设置变量的终端重新启动 dsh。

## 验证配置

先确认 **dsh 新会话**选中了 `stepfun` 下的 `step-5-preview`，发送简单消息并检查返回。

如需单独排查 API 连通性，在终端设置 `STEPFUN_API_KEY` 后运行以下命令。仅在 Web UI 中保存密钥不会自动设置终端变量。

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl --silent --show-error --fail-with-body \
  --write-out '\nHTTP %{http_code}\n' \
  https://api.stepfun.com/step_plan/v1/chat/completions \
  -H "Authorization: Bearer $STEPFUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "step-5-preview",
    "messages": [{"role": "user", "content": "Say hello briefly."}],
    "max_tokens": 1024
  }'
```

返回 HTTP 200 且 JSON 中包含正常的 `choices` 表示这次 API 请求成功；它不能单独证明 dsh 的 Provider、凭据或会话选择正确。若输出被截断，可提高 `max_tokens` 后重试。测试调用会使用对应账户的额度。

## 常见问题

| 现象 | 排查方式 |
| - | - |
| `MISSING_CREDENTIAL` | 确认 `apiKeyEnv` 与 `STEPFUN_API_KEY` 一致，变量已传入 dsh 进程；或在 Web UI 中补填密钥。若旧环境变量仍存在，更新或移除它后重启，避免遮蔽 UI 保存的新密钥。 |
| 模型 ID 不能为空 | 模型 ID 是 API 调用时使用的模型标识：Step 5 Preview 填写 `step-5-preview`，Step 3.7 Flash 填写 `step-3.7-flash`。为每个新增模型填写对应 ID，或删除多余的空模型行。Provider ID 填写 `stepfun`，不要与模型 ID 混淆。 |
| `401 Unauthorized` | 检查密钥是否正确、有效，且属于当前 API 地址对应的平台账户。 |
| `404` / model not found | 检查 Base URL、`step-5-preview` 拼写以及账户模型权限；不要把完整 `/chat/completions` 路径填入 Base URL。 |
| 密钥和地址正确，但请求字段被拒绝 | 检查 YAML 的 `compat.supportsDeveloperRole: false` 和 `compat.maxTokensField: max_tokens`，然后新建会话重试。 |
| 新配置没有生效 | 检查 `DSH_HOME`、YAML 缩进及重复键；重新选择模型并新建会话。使用新环境变量时重启 dsh。 |
| 模型列表获取失败 | 模型发现依赖服务端列表接口；可以直接手动添加模型 ID，不必等待自动发现。 |

## 相关文档

* [Step 5 Preview](/docs/zh/guides/models/step-5-preview)
* [Step 3.7 Flash](/docs/zh/guides/models/step-3.7-flash)
* [Step Plan 快速开始](/docs/zh/step-plan/quick-start)


# Goose
Source: https://platform.stepfun.com/docs/zh/guides/developer/integrations/goose



Goose 是由 Block（前身为 Square）开发的开源 AI Agent 客户端。它通过自然语言支持代码生成、文件编辑、命令执行和项目分析等开发任务。通过配置 OpenAI Compatible 提供商，Goose 可以连接到 Step 模型，并在常见的开发工作流中使用本地工具。

本文档介绍将 Step API 与 Goose 集成的前置条件、配置步骤和基本验证方法。

## 概述

Goose 支持通过 OpenAI Compatible API 集成第三方大型语言模型。配置提供商后，您可以直接在 Goose 中使用 Step 模型进行对话任务、代码编辑和工具调用。

通过配置自定义提供商，Goose 可以使用 Step 模型实现以下功能：

* 自主任务执行：自动编辑文件并运行 Shell 命令。
* 代码库分析：理解项目结构并回答复杂的编程问题。
* 自动化工作流：结合本地工具链完成端到端的开发任务。

## 前置条件

开始之前，请确保满足以下要求。

### 安装 Goose

确保已安装 Goose 命令行工具或桌面客户端。

* [官方网站](https://block.github.io/goose/)

### 订阅 Step Plan

开始配置之前，请确保您的当前账户已有有效的 Step Plan 订阅。只有具备所需套餐或调用权限的账户才能正常使用模型调用和配额。

如需订阅或购买，请访问 [Step Plan 订阅](https://platform.stepfun.com/step-plan)

### 获取 Step API Key

登录 StepFun 开放平台获取用于身份验证的 API Key，并妥善保管。

### 确认连接信息

提前准备以下连接信息：

* Base URL：`https://api.stepfun.com/step_plan/v1`
* 协议类型：`OpenAI Compatible`

## 配置步骤

### 打开提供商设置

在 Goose 桌面客户端中，点击 `Settings`，选择 `Providers`，然后点击 `Add Provider`。

### 填写配置参数

在配置对话框中，输入以下信息：

* Provider Type：选择 `OpenAI Compatible`
* Display Name：输入 `StepFun`
* API URL：输入 `https://api.stepfun.com/step_plan/v1`
* API Key：粘贴您从 Step 平台获取的密钥
* Available Models：输入以下模型名称

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
<model_id>
```

> 说明：`<model_id>` 请填写当前账号在 Step Plan 下可用的模型。已验证示例：`step-5-preview`、`step-3.7-flash`、`step-3.5-flash-2603`、`step-3.5-flash`。文档列出的模型不构成全部可用名单。

配置完成后，Goose 即可通过该提供商调用 Step 模型。

## 测试集成

配置完成后，在 Goose 主聊天窗口切换至 `StepFun` 提供商下的任意模型，并使用以下示例进行验证。

### 基础对话测试

输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
你好，你是谁？
```

预期结果：返回由 StepFun 提供的模型身份回复。

### 工具能力测试

输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请列出我当前目录下的所有文件。
```

预期结果：Goose 调用本地目录列表工具，并使用 Step 模型对文件列表进行汇总。

### 代码编辑测试

输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
帮我创建一个名为 hello.py 的文件，输出当前时间。
```

预期结果：Goose 生成代码并将文件保存到本地磁盘。

## 常见问题

### 工具识别失败或连接超时

可能原因：当前网络环境可能无法直接访问 API 端点。

请检查以下内容：

* 代理或网络设置是否正确
* API URL 末尾是否误加了斜杠

### 模型列表为空

如果模型下拉列表为空，请确保已在 `Available Models` 中手动输入具体的模型标识符，例如：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
<model_id>
```

如果未输入任何模型标识符，下拉列表可能无法正确显示可用选项。

## 总结

通过 Goose 的 `OpenAI Compatible` 模式，开发者可以将 Step 模型的推理能力与 Goose 的本地工具链相结合，用于代码生成、文件操作和项目分析等任务。

建议使用 `<model_id>` 进行集成验证和日常开发任务。


# Hermes Agent
Source: https://platform.stepfun.com/docs/zh/guides/developer/integrations/hermes-agent



Hermes Agent 是由 Nous Research 开发的开源 AI Agent 框架，支持在终端环境中通过自然语言完成代码生成、文件编辑、任务自动化等开发任务。Hermes Agent 可以接入 Step 模型，在命令行或消息平台中调用推理能力。

本文档介绍如何在 Hermes Agent 中完成 Step API 的接入配置，并验证模型是否可用。

## 概述

Hermes Agent 适合在服务器或本地终端中运行的 AI 编程助手。完成配置后，您可以通过终端 TUI 或 Telegram 等消息平台与 Agent 对话，让它执行代码生成、文件操作、定时任务等自动化工作。

## 前置条件

### 操作系统

Hermes Agent 支持以下系统：

* Linux（推荐 Ubuntu/Debian）
* macOS
* Windows（需使用 WSL2）

### 安装 Hermes Agent

Hermes Agent 提供一键安装脚本，自动完成依赖安装和配置。

**通过安装脚本（推荐）：**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```

安装脚本会自动检测并安装以下组件：

* `uv`（Python 包管理器）
* `Python 3.9+`
* `Node.js`（部分技能需要）
* `ripgrep`、`ffmpeg` 等工具

安装完成后，重新加载 shell 配置：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
source ~/.bashrc   # Bash 用户
# 或
source ~/.zshrc    # Zsh 用户
```

验证安装：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
hermes --version
```

若返回版本号（如 `Hermes Agent v0.6.0`），则说明安装成功。

### 订阅 Step Plan

在开始配置前，请先确认当前账号已完成 Step Plan 订阅。只有在账号具备对应计划或调用权限后，后续模型调用与额度使用才会正常生效。

如需订阅或购买，请访问：[Step Plan 订阅](https://platform.stepfun.com/step-plan)

### 获取 Step API Key

在 [Step 开放平台](https://platform.stepfun.com/interface-key) 获取 API Key，用于身份认证和请求授权。建议通过控制台创建新的 Key，并避免将其硬编码进代码仓库。

推荐做法：

* 使用环境变量保存 Key
* 或通过本地配置文件管理 Key

## 配置步骤

Hermes Agent 通过环境变量或配置文件读取 API 服务地址和认证信息。

### 方式一：通过 Hermes Agent 的配置向导

如果您是首次安装或希望重新运行引导流程：

打开终端，执行以下命令：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
hermes setup
```

在引导过程中：

1. 当提示选择模型提供商时，选择 **StepFun Step Plan**后选择**China**。

2. 填入您在第一步获取的 **API Key**。\\

3. 选择您想要用的 Model ID。

### 方式二：配置文件修改

Hermes Agent 的配置文件位于 `~/.hermes/config.yaml`。

打开配置文件，找到 `model` 相关配置项，添加或修改以下内容：

```yaml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
model:
  provider: openai
  api_key: "YOUR_STEP_API_KEY"
  base_url: "https://api.stepfun.com/step_plan/v1"
  model: "<model_id>"
```

> **说明**：`<model_id>` 请填写当前账号在 Step Plan 下可用的模型。已验证示例：`step-5-preview`、`step-3.7-flash`、`step-3.5-flash-2603`、`step-3.5-flash`。文档列出的模型不构成全部可用名单。

### 选择模型

配置完成后，运行以下命令选择模型：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
hermes model
```

## 测试接入

完成配置后，启动 Hermes Agent 并发送测试消息：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
hermes
```

在对话界面中输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
hello
```

如果返回正常内容，说明 API 调用成功。

### 代码生成测试

输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Create a hello world script in Python
```

预期返回类似结果：

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
print("Hello, world!")
```

### 文件操作测试

输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
在当前目录创建一个名为 test.txt 的文件，内容为 "Hermes Agent test"
```

如果 Agent 成功创建文件，则说明模型调用链路正常。

## 常见问题

### 模型列表为空或无法加载

如果 `hermes model` 命令中未显示 Step 相关模型，请检查：

1. 当前网络是否能访问 `api.stepfun.com`。
2. Base URL 是否填写为 `https://api.stepfun.com/step_plan/v1`。
3. API Key 是否具有 Step Plan 权限。
4. Hermes Agent 是否为最新版本（`hermes update` 升级）。

### API Key 错误

如果出现以下报错：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
401 Incorrect API key
```

请检查：

* Key 是否复制完整
* Key 是否属于正确环境（Step Plan 对应 `.com` 域名）
* Base URL 是否指向 Step Plan 端点

### 连接超时或失败

请检查：

* 当前网络环境是否正常（如有代理需配置）
* API 端点是否可访问（`curl https://api.stepfun.com/step_plan/v1` 测试连通性）

### 模型返回错误

请确认 Model ID 是否填写正确，例如：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
<model_id>
```

推荐模型（已验证示例，请按当前账号权限替换）：

* `step-5-preview`（新一代旗舰多模态强推理，支持图片和视频理解）
* `step-3.7-flash`（高速多模态推理模型）
* `step-3.5-flash-2603`（Agent 优化版，推理更强）
* `step-3.5-flash`（标准版，响应更快）

## 高级配置（可选）

### 启用工具调用

Hermes Agent 支持自动工具调用。在 `~/.hermes/config.yaml` 中启用：

```yaml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
tools:
  enabled:
    - terminal
    - file
    - browser
    - code_execution
```

### 配置记忆系统

Hermes Agent 的持久记忆存储在 `~/.hermes/memories/` 目录。您可以通过自然语言让 Agent 记住重要信息，这些记忆会在后续对话中自动召回。

### 消息网关（Telegram/Discord）

如需在手机上通过 Telegram 与 Hermes Agent 对话，启动网关：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
hermes gateway start
```

首次运行会提示配置 `TELEGRAM_BOT_TOKEN` 和 `TELEGRAM_ALLOWED_USERS`，相关信息可在 Telegram 中通过 @BotFather 获取。

## 总结

完成环境变量或配置文件配置后，Hermes Agent 即可通过 Step API 在终端或消息平台中执行代码生成、文件编辑、任务自动化等开发任务。建议先用最小示例（如 hello world）验证连通性，再逐步探索技能创建、记忆管理和定时任务等高级功能。


# Kilo Code
Source: https://platform.stepfun.com/docs/zh/guides/developer/integrations/kilo-code



Kilo Code 是运行在 VS Code、Cursor 等编辑器中的编码 Agent，可连接不同模型提供方，执行代码修改、调试和终端任务。通过 Step Plan Provider，可在编辑器内使用 Step 模型。

## 接入条件

* 已安装 VS Code 或 Cursor。运行下方 Python 验证示例时，还需安装 Python 3。
* [Step Plan 订阅](https://platform.stepfun.com/step-plan)有效、额度可用，且具备所用模型的调用权限。
* 已在 [StepFun 开放平台密钥管理](https://platform.stepfun.com/interface-key)页面创建 API Key。

## 安装 Kilo Code

在编辑器扩展市场中搜索并安装 Kilo Code，扩展标识为 `kilocode.kilo-code`。以下步骤使用包含 `Providers` 和 `Models` 设置页的版本。

## 配置 Step Plan

### 连接内置 Provider

1. 打开 Kilo Code 设置，进入 `Providers`，选择 `StepFun Step Plan (China)`。
2. 填写 API Key，点击 `Submit` 保存。API Key 字段不添加 `Bearer ` 前缀或首尾空格。
3. 在 `Settings > Models > Default Model` 中，选择该 Provider 下的 Step 5 Preview，模型 ID 为 `step-5-preview`。
4. 保存后新建任务。使用内置 Provider 时，保留其模型预设参数。

### 使用自定义 Provider

如果当前版本没有 Step Plan 预设，或预设列表中没有目标模型，可通过 `Providers > Custom provider` 手动配置：

| 配置项 | 填写值 |
| - | - |
| `Provider ID` | `step-plan`。 |
| `Display name` | `Step Plan`。 |
| `Provider API` | `OpenAI Compatible`。 |
| `Base URL` | `https://api.stepfun.com/step_plan/v1`。 |
| `API key` | Step API Key，不包含 `Bearer ` 前缀。 |
| `Models` | 选择或添加 `step-5-preview`。 |

点击 `Submit` 后，在模型选择器中选择该自定义 Provider 下的模型。此配置使用 Chat Completions 协议，完整请求路径为 `/step_plan/v1/chat/completions`。

手动添加的模型还需提供上下文和输出容量信息。若当前配置文件中的自定义模型缺少这些字段，将以下内容合并到 `kilo.json` 或 `kilo.jsonc`，保留该 Provider 已有的连接与认证设置：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "provider": {
    "step-plan": {
      "models": {
        "step-5-preview": {
          "name": "Step 5 Preview",
          "limit": {
            "context": 1000000,
            "output": 65536
          }
        }
      }
    }
  }
}
```

上述容量配置适用于 [Step 5 Preview](/docs/zh/guides/models/step-5-preview)。切换到其他模型时，按对应模型规格调整。推理模型需要为推理与正文保留预算，过小的输出限制可能导致正文为空或提前结束。

## 接入 StepSearch MCP

[StepSearch](/docs/zh/guides/developer/search-mcp) 通过 Step Plan 端点提供 `web_search` 和 `web_fetch`，用于联网搜索与网页内容获取。

### 提供认证环境变量

完全退出编辑器后，在项目目录的终端中设置密钥并重新启动编辑器。将 `YOUR_STEP_API_KEY` 替换为实际密钥；Cursor 用户将 `code .` 替换为 `cursor .`。

**macOS / Linux / WSL**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export STEP_API_KEY="YOUR_STEP_API_KEY"
code .
```

**Windows PowerShell**

```powershell theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
$env:STEP_API_KEY = "YOUR_STEP_API_KEY"
code .
```

若编辑器命令不可用，先配置对应命令行入口。环境变量只对当前终端及其启动的进程生效；以后使用该 MCP 时，也需确保编辑器进程能够读取 `STEP_API_KEY`。

### 添加 MCP 服务

1. 在 Kilo Code 设置中打开 `MCP Servers`。
2. 编辑当前项目的 `kilo.json`。如果项目已有 `kilo.jsonc` 或 `.kilo/` 下的同名配置文件，请合并到现有文件中，保留其他设置：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "mcp": {
    "step-search": {
      "type": "remote",
      "url": "https://api.stepfun.com/step_plan/v1/mcp/web_search/mcp",
      "headers": {
        "Authorization": "Bearer {env:STEP_API_KEY}"
      },
      "oauth": false,
      "enabled": true
    }
  }
}
```

3. 保存后刷新或重新连接服务，检查 `step-search` 是否已连接，以及工具列表中是否包含 `web_search` 和 `web_fetch`。
4. 新建任务，调用其中一个工具完成搜索或网页抓取，按提示确认授权，并核对实际返回结果。

新版配置使用顶层 `mcp`、`type: "remote"` 和 `{env:STEP_API_KEY}` 环境变量引用。远程服务优先使用 Streamable HTTP，必要时回退到 SSE。该示例通过请求头认证，不使用 OAuth。

> [!WARNING]
>
> 请保留示例中的环境变量引用，不要将真实密钥写入项目配置后提交到代码仓库。任何获得该密钥的人都可能以您的权限发起请求并消耗额度。

## 验证接入

### 验证对话

新建任务并输入 `请只回复 OK。`，预期返回 `OK`。

### 验证工具调用

1. 在独立测试目录中创建 `README.md`，内容为 `Kilo Code Step Plan test`，然后在编辑器中打开该目录。
2. 新建任务，发送以下指令：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
读取 README.md，创建 hello.py，使其打印 "Hello, world!"。
使用本机可用的 Python 解释器运行 hello.py，并报告执行命令和实际输出。
不要修改 README.md 或其他已有文件。
```

3. 按提示批准必要的文件与命令操作，核对读取、编辑和执行记录。确认 `hello.py` 实际生成，输出为 `Hello, world!`，且 `README.md` 未被修改。

### 验证配置保存

重启编辑器后，检查 Provider 与模型选择是否保留，并重新发起一次简短对话。

## 常见问题

> **Q: 找不到 Step Plan Provider 或 Step 5 Preview 怎么办？**
>
> 更新 Kilo Code 扩展并检查 Provider 列表。也可通过 `Providers > Custom provider` 选择 `OpenAI Compatible`，填写 Step Plan Base URL，并手动添加 `step-5-preview`。保存后，选择该自定义 Provider 下的模型。

> **Q: 提示 Connection error 或返回 401 怎么办？**
>
> 查看完整错误信息，检查网络连接、Base URL、API Key 与模型权限。自定义 Provider 使用 `https://api.stepfun.com/step_plan/v1`；API Key 应完整、有效，且属于对应站点账号。根据服务端返回信息，分别排查认证、模型和请求参数。

> **Q: 回复为空或被截断怎么办？**
>
> 检查停止原因和输出预算。推理可能先消耗输出预算，过小的限制会影响正文生成。使用内置模型时先恢复其预设；使用自定义模型时检查容量与请求设置，再按实际错误调整。

> **Q: 旧版 Include max output tokens 设置如何处理？**
>
> `Include max output tokens` 和 `Max Output Tokens = -1` 属于旧版界面配置，不作为新版内置 Provider 的必填项。新版自定义模型使用 `limit.context`、`limit.output` 描述容量，请填写模型支持的有效值，不要直接将 `-1` 复制到 `limit.output`。

> **Q: 旧版 .kilocode/mcp.json 配置如何处理？**
>
> 当前流程使用 `kilo.json` 或 `kilo.jsonc` 中的 `mcp` 配置。旧版 `.kilocode/mcp.json` 中的 `mcpServers`、`streamable-http`、`disabled` 等字段不能直接混入新版示例；请按当前配置格式迁移，或使用与旧版扩展匹配的配置。

> **Q: MCP 中没有 step-search 或对应工具怎么办？**
>
> 检查配置是否位于当前项目实际加载的文件中，`type` 是否为 `remote`、`enabled` 是否为 `true`。确认编辑器进程可以读取 `STEP_API_KEY`，请求头使用 `Bearer {env:STEP_API_KEY}`。保存后重新连接，并查看服务日志。

> **Q: 模型只回复文字，没有执行操作怎么办？**
>
> 确认已打开目标项目，当前模式允许修改文件，并检查是否有等待批准的工具调用。按提示授权后继续；不需要为完成验证而开启全部自动批准选项。


# Oh My Pi
Source: https://platform.stepfun.com/docs/zh/guides/developer/integrations/oh-my-pi



Oh My Pi（OMP）是 Pi 的工作流扩展，通过 npm 包 `oh-my-pi` 安装，提供任务分类、角色指令和 Skill 加载能力。模型调用沿用 Pi 的 Provider 配置，通过 Anthropic Messages API 接入 Step Plan。

## 接入条件

* 已按 [Pi 接入指南](/docs/zh/guides/developer/integrations/pi)安装 Pi 0.87.1，并完成 Step Plan 配置与基础对话验证。
* 启动 Pi 的终端已设置 `STEP_API_KEY` 环境变量。

## 安装 OMP

1. 在终端中安装 `oh-my-pi` 0.2.0。

   ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
   pi install npm:oh-my-pi@0.2.0
   ```

2. 检查已安装的软件包。

   ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
   pi list
   ```

软件包列表应包含 `npm:oh-my-pi@0.2.0`。Pi 会在新会话中自动加载扩展。

## 配置编排器

如需自定义编排器名称和提示词模板，在项目根目录的 `.oh-my-pi.jsonc` 中合并以下配置，保留已有字段。文件不存在时创建该文件。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "orchestrator": {
    "agentName": "stepfun",
    "promptTemplate": "sisyphus"
  }
}
```

保存后，在已有 Pi 会话中执行 `/oh-my-pi-reload`，或重新启动 Pi。

## 启动 Pi

在项目目录的终端中执行：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
pi --provider stepfun --model step-5-preview
```

## 验证接入

### 检查扩展状态

在 Pi 会话中输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/oh-my-pi-doctor
```

诊断结果应显示 `Healthy`，且配置诊断无错误。

### 验证对话

在终端中执行：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
pi --provider stepfun --model step-5-preview --print "请只回复 OK。"
```

预期返回 `OK`。

### 验证工具调用

1. 在安装了 Python 的独立测试目录中创建 `README.md`，内容为 `Oh My Pi Step Plan test`。

2. 从该目录启动 Pi。

3. 在会话中输入以下任务。

   ```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
   读取 README.md，创建 hello.py，输出 Hello, StepFun!。
   使用本机可用的 Python 解释器运行 hello.py，并汇报执行命令和输出。
   不要修改其他文件。
   ```

4. 核对文件读取、创建和命令执行记录，确认生成的 `hello.py` 运行输出为 `Hello, StepFun!`。

### 验证角色调用

在同一测试目录的 Pi 会话中输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
调用 oh_my_pi_subagent 工具，请 oracle 评审 hello.py 的输出和可移植性。
只给出简短结论，不修改文件。
```

核对工具记录中包含 `oh_my_pi_subagent`，并确认当前会话返回评审结果。

### 核查请求通道

Pi 的 Step Plan 配置 Base URL 为 `https://api.stepfun.com/step_plan`，对应请求路径为 `/step_plan/v1/messages`。如需核查请求路由或计费归属，请提供请求时间、模型 ID 和 Request ID 联系技术支持。

## 常见问题

> **Q: 安装时找不到软件包怎么办？**
>
> npm 软件包源使用 `npm:` 前缀。请执行 `pi install npm:oh-my-pi@0.2.0`，安装后运行 `pi list` 检查结果。

> **Q: 可以为 oracle 单独指定模型吗？**
>
> 0.2.0 的 `oh_my_pi_subagent` 工具向当前会话返回角色指令，后续请求仍使用 Pi 当前选择的模型。该版本尚未实现通过 `agents.oracle.model` 或任务分类的 `model` 字段切换实际调用模型。选择模型时，请使用 Pi 的 `--provider` 和 `--model` 参数。

> **Q: 如何停用 OMP？**
>
> 在终端中执行 `pi remove npm:oh-my-pi@0.2.0`，然后重新启动 Pi。

> **Q: 认证、请求路径或上下文配置异常怎么办？**
>
> OMP 沿用 Pi 的模型和凭据配置。请按 [Pi 接入指南](/docs/zh/guides/developer/integrations/pi)检查 `STEP_API_KEY`、`models.json` 中的 `baseUrl` 和对应模型的 `contextWindow`。


# OpenCode
Source: https://platform.stepfun.com/docs/zh/guides/developer/integrations/open-code



Open Code 是一款运行在终端中的 AI Coding Agent，适合通过自然语言完成代码生成、代码修改和项目分析等开发任务。完成配置后，可以直接在终端中调用 Step 模型完成开发流程。本文档介绍 Open Code 接入 Step Plan 的准备条件、配置步骤与基础验证方法。

## 概述

Open Code 适合偏终端交互的开发工作流。Open Code 内置了 StepFun Provider，但默认 Base URL 指向普通付费 API（`/v1`）。要用上 Step Plan 订阅额度，**必须通过 `opencode.json` 将 Base URL 覆盖为 `step_plan/v1`**——这是本指南的核心配置点。

## 前置条件

### 开发环境

支持以下系统：

* macOS
* Linux
* Windows（推荐使用 WSL）

### 安装 Open Code

推荐使用 Open Code 官方安装脚本（macOS / Linux / WSL）：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -fsSL https://opencode.ai/install | bash
```

> [!TIP]
>
> 如果上述脚本下载较慢（脚本会从 GitHub release 资产拉取，国内网络偶尔会中断），或不希望使用 WSL，可改用以下方式：
>
> ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> # Homebrew（macOS / Linux）
> brew install anomalyco/tap/opencode
>
> # Chocolatey（Windows）
> choco install opencode
>
> # Scoop（Windows）
> scoop install opencode
>
> # npm 全局安装（跨平台）
> npm install -g opencode-ai
> ```

安装完成后，确认安装成功：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
opencode --version
```

### 订阅 Step Plan

在开始配置前，请先确认当前账号已完成 Step Plan 订阅。只有在账号具备对应计划或调用权限后，后续模型调用与额度使用才会正常生效。如需订阅或购买，请访问：[Step Plan 订阅](https://platform.stepfun.com/step-plan)

### 获取 Step API Key

访问 [Step 平台控制台](https://platform.stepfun.com/interface-key) 创建 API Key，复制并妥善保存。

## 配置步骤

Open Code 通过 `opencode.json` 配置文件管理 Provider，无需写入 `~/.zshrc`。

### 创建 opencode.json

创建 `~/.config/opencode/opencode.json`（全局配置，对所有项目生效）：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
mkdir -p ~/.config/opencode
```

写入以下内容：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "stepfun": {
      "api": "https://api.stepfun.com/step_plan/v1",
      "models": {
        "step-5-preview": { "name": "Step 5 Preview" }
      }
    }
  }
}
```

> [!WARNING]
>
> `provider.stepfun.api` 这一行**必须填写**。Open Code 内置的 StepFun Provider 默认指向 `https://api.stepfun.com/v1`（普通付费 API），不覆盖会导致请求走错端点、用不上 Step Plan 订阅额度。

### 设置环境变量

Open Code 通过 `STEPFUN_API_KEY` 环境变量读取 Step API Key。打开终端运行：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
echo 'export STEPFUN_API_KEY="YOUR_STEP_API_KEY"' >> ~/.zshrc
source ~/.zshrc
```

将 `YOUR_STEP_API_KEY` 替换为您在控制台创建的 Step API Key。

验证：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
echo $STEPFUN_API_KEY
```

若输出您的 API Key，则说明配置成功。

### 选择模型

在终端任意目录启动 Open Code：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
opencode
```

按下 `/` 输入 `/models` 调出模型列表，选择：

* `stepfun/step-5-preview`

选择后终端底部会显示当前模型，例如：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> build · step-5-preview
```

这表示当前会话已在使用 Step 模型。

## 测试接入

启动 `opencode` 后，输入简单任务进行验证：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Create a hello world script in Python
```

若接入成功，模型会返回类似内容：

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
print("Hello, world!")
```

## 常见问题

### 401 Incorrect API key

如果出现：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
401 Incorrect API key
```

请按顺序排查：

1. `STEPFUN_API_KEY` 是否已写入并 `source ~/.zshrc`，`echo $STEPFUN_API_KEY` 是否有输出。
2. Key 是否复制完整、首尾是否带空格或换行。
3. 控制台对应账号是否已订阅 Step Plan。

### 400 you have no active step plan subscription

如果出现：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
400 you have no active step plan subscription
```

当前账号尚未订阅 Step Plan。请到 [Step Plan 订阅](https://platform.stepfun.com/step-plan) 开通后重试。

### 请求很久没响应 / 没用上订阅额度

如果调用能成功返回内容，但发现：

* 响应时间异常长、或者
* Step Plan 订阅的 Credit 额度没有消耗、走的是按 token 付费

请确认 `~/.config/opencode/opencode.json` 中的 `provider.stepfun.api` 已正确指向 `https://api.stepfun.com/step_plan/v1`。Open Code 内置的 StepFun Provider 默认指向 `https://api.stepfun.com/v1`，不覆盖会走错端点。

### Provider 未显示 / 模型列表里找不到 StepFun

StepFun 只有在配置了凭证后才会出现在 `/models` 列表中。请检查：

1. 是否已配置 StepFun 凭证（设置 `STEPFUN_API_KEY` 环境变量、`opencode auth login`、或在 `opencode.json` 中配置 `provider.stepfun.options.apiKey`）。
2. `opencode.json` 文件路径与 JSON 格式是否正确（`opencode providers list` 可查看当前识别到的 Provider）。
3. 如果以上都没问题，Open Code 版本可能过低，运行 `opencode upgrade` 升级到最新版本后重试。

### 调用名（模型 ID）

在 Open Code 里指定模型时使用 `<provider>/<model>` 格式：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
stepfun/step-5-preview
stepfun/step-3.7-flash
stepfun/step-3.5-flash
stepfun/step-3.5-flash-2603
```

以上为已验证示例，请按当前账号在 Step Plan 下的可用模型替换，不构成全部可用名单。

## 总结

完成 `opencode.json`、`STEPFUN_API_KEY` 配置后，Open Code 即可通过 Step Plan 在终端中执行代码生成、文件编辑和项目分析等任务。建议先按「测试接入」一节在 TUI 中跑一次范例验证连通性，再继续补充您自己的终端开发工作流。


# OpenClaw
Source: https://platform.stepfun.com/docs/zh/guides/developer/integrations/openclaw



## 前置条件

在配置 OpenClaw 之前，确保您已经

* [订阅 Step Plan](https://platform.stepfun.com/step-plan)
* 登录 [platform.stepfun.com](https://platform.stepfun.com)，在控制台创建并获取 API Key。

## 安装 OpenClaw

如果您尚未安装 OpenClaw，请先完成安装。

在终端中运行以下命令：

**macOS / Linux / WSL2**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -fsSL https://openclaw.ai/install.sh | bash
```

**Windows**

```powershell theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
powershell -c "irm https://openclaw.ai/install.ps1 | iex"
```

**npm**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
npm i -g openclaw
```

## 配置阶跃模型

安装后会启动 Onboard 引导。如果已安装过 OpenClaw，可以通过以下命令重新启动 Onboard 引导：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
openclaw onboard
```

### 配置模型 API key

使用以下配置：

* 在 Model/auth provider 中选择 StepFun。
* 在 StepFun auth method 中选择 StepFun Step Plan API key。
* 在 Enter StepFun API key 中粘贴您的 API key。
* Model configured 会显示该认证方式下默认模型。
* 在 Default model 列表中，您可以选择保持默认或者选择另外的模型。

### 完成其他配置

接下来您可以根据自己的需求配置 channel、search、skills、hooks。
配置完成后可以选择在终端(TUI) 或者 Web UI 中启动。

### 验证

启动后您可以随便问一个问题，看界面中是否有 OpenClaw 的回应。

### 其他配置方式

**通过官方脚本快速配置**

#### macOS / Linux（Bash）

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -fsSL https://raw.githubusercontent.com/Zgh332358/openclaw-stepfun-installer/main/add_stepfun_smart.sh | bash 
```

#### Windows（PowerShell 管理员模式）

**注意**：必须在管理员模式的 PowerShell 下运行，否则脚本会提示并退出。

1. 右键点击 Windows 开始菜单，选择「终端管理员」或「Windows PowerShell (管理员)」

2. 执行以下命令：

```powershell theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
irm https://raw.githubusercontent.com/Zgh332358/openclaw-stepfun-installer/main/add_stepfun_smart.ps1 | iex
```

**手动编辑配置文件**

OpenClaw 的配置文件位于 `~/.openclaw/openclaw.json`。

使用您喜欢的编辑器打开它，在文件中添加或修改以下内容。以下按 Step 5 Preview 的窗口配置，`<model_id>` 填写 `step-5-preview`；若选择 `step-3.7-flash` 或 Step 3.5 Flash 系列，请同时将 `contextWindow` 改为 `256000`。`maxTokens: 8192` 是本示例的输出预算，不代表模型的最大输出能力。

```jsonc theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "stepfun/<model_id>" // <model_id> 可填写 step-5-preview、step-3.7-flash、step-3.5-flash-2603 或 step-3.5-flash
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "stepfun": {
        "baseUrl": "https://api.stepfun.com/step_plan/v1",
        "apiKey": "${STEP_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "<model_id>",
            "name": "<model_id>",
            "reasoning": true,
            "contextWindow": 1000000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}
```

> 说明：`<model_id>` 请填写当前账号在 Step Plan 下可用的模型。已验证示例：`step-5-preview`、`step-3.7-flash`、`step-3.5-flash-2603`、`step-3.5-flash`。文档列出的模型不构成全部可用名单。

## 常见问题

> **Q: 配置后提示 'Model is not allowed'**
>
> 如果您设置了 `agents.defaults.models`（模型允许列表），需要确保 `stepfun/<model_id>` 也被加入到该列表中，否则模型会被拦截。解决方法：
>
> ```jsonc theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> {
>   "agents": {
>     "defaults": {
>       "models": {
>         "stepfun/<model_id>": {
>           "alias": "Step Model"
>         }
>       }
>     }
>   }
> }
> ```
>
> 或者直接移除 `agents.defaults.models` 配置项以取消白名单限制。

> **Q: `api` 字段为什么选 `openai-completions`？**
>
> StepFun API 完整兼容 OpenAI 的 Chat Completions 请求格式。OpenClaw 在配置自定义 Provider 时支持两种 API 类型：
>
> * `openai-completions`：适用于兼容 OpenAI 格式的提供商（绝大多数第三方提供商）
> * `anthropic-messages`：适用于兼容 Anthropic Messages 格式的提供商
>
> StepFun 属于前者。

> **Q: Windows 上可以不用 WSL2 吗？**
>
> 不推荐。OpenClaw 依赖 Linux 工具链（`make`、`g++` 等）和 systemd 服务管理，原生 Windows 环境会遇到诸多兼容性问题。WSL2 是官方推荐的 Windows 使用方式。

## 参考链接

* [OpenClaw 官方文档](https://docs.openclaw.ai)
* [OpenClaw 模型配置文档](https://docs.openclaw.ai/concepts/model-providers)
* [OpenClaw Models CLI 文档](https://docs.openclaw.ai/concepts/models)
* [Step Plan 订阅](https://platform.stepfun.com/step-plan)


# Pi
Source: https://platform.stepfun.com/docs/zh/guides/developer/integrations/pi



Pi 是 earendil-works 开源的终端编码 Agent，支持文件读取、编辑和命令执行。通过自定义 Provider，可使用 Anthropic Messages 协议接入 Step Plan。

## 接入条件

* macOS、Linux 或 Windows，已安装 Node.js 22.19 或更高版本及 npm。
* [Step Plan 订阅](https://platform.stepfun.com/step-plan)有效、额度可用，且具备所用模型的调用权限。
* 已在 [StepFun 开放平台密钥管理](https://platform.stepfun.com/interface-key)页面创建 API Key。

在终端中执行以下命令，检查当前环境：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
node --version
npm --version
```

如果 Node.js 版本为 `v22.19.0` 或更高，且 npm 能正常输出版本号，可直接继续安装 Pi。

## 安装 Pi

安装 Pi 0.87.1：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.87.1
```

检查安装版本：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
pi --version
```

## 配置 Step Plan

### 设置 API Key

在启动 Pi 的终端中设置环境变量，将 `YOUR_STEP_API_KEY` 替换为实际密钥：

**macOS / Linux / WSL**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export STEP_API_KEY="YOUR_STEP_API_KEY"
```

**Windows PowerShell**

```powershell theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
$env:STEP_API_KEY = "YOUR_STEP_API_KEY"
```

### 添加模型

1. 打开 `~/.pi/agent/models.json`。如果设置了 `PI_CODING_AGENT_DIR` 时，请使用该目录下的 `models.json`。
2. 将以下 `providers.stepfun` 配置合并到文件中，保留其他 Provider。文件不存在时创建目录并保存以下 JSON。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "providers": {
    "stepfun": {
      "baseUrl": "https://api.stepfun.com/step_plan",
      "api": "anthropic-messages",
      "apiKey": "$STEP_API_KEY",
      "models": [
        { "id": "step-5-preview", "input": ["text", "image"], "contextWindow": 1000000 },
        { "id": "step-3.7-flash", "input": ["text", "image"], "contextWindow": 256000 }
      ]
    }
  }
}
```

| 字段 | 说明 |
| - | - |
| `providers.stepfun` | Provider 标识，启动时通过 `--provider stepfun` 选择。 |
| `baseUrl` | Step Plan 配置地址。Pi 自动追加 `/v1/messages`，最终路径为 `/step_plan/v1/messages`。 |
| `api` | `anthropic-messages` 指定 Anthropic Messages 协议。 |
| `apiKey` | `$STEP_API_KEY` 引用启动进程中的环境变量。 |
| `models[].input` | 允许客户端发送的输入类型。 |
| `models[].contextWindow` | 客户端使用的上下文窗口，填写整数 token 数。 |

[Step 5 Preview](/docs/zh/guides/models/step-5-preview) 的上下文窗口为 1M tokens，[Step 3.7 Flash](/docs/zh/guides/models/step-3.7-flash) 为 256K tokens。上述配置分别使用 `1000000` 和 `256000`。

### 设置默认模型

将以下字段合并到同一配置目录中的 `settings.json`：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "defaultProvider": "stepfun",
  "defaultModel": "step-5-preview"
}
```

## 启动 Pi

在项目目录的终端中执行：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
pi
```

也可在启动时指定 Provider 和模型：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
pi --provider stepfun --model step-5-preview
```

## 验证接入

### 检查模型配置

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
pi auth check --provider stepfun --json
pi --list-models stepfun
```

认证检查的 `status` 应为 `ready`，表示客户端能够解析凭据。模型列表应包含配置的模型 ID，Step 5 Preview 的上下文显示为 1M，Step 3.7 Flash 显示为 256K。

### 验证对话

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
pi --provider stepfun --model step-5-preview --print "请只回复 OK。"
```

预期返回 `OK`。

### 验证工具调用

在安装了 Python 的独立测试目录中创建 `README.md`，内容为 `Pi Step Plan test`。从该目录启动 Pi，输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
读取 README.md，创建 hello.py，输出 Hello, StepFun!。
使用本机可用的 Python 解释器运行 hello.py，并汇报执行命令和输出。
不要修改其他文件。
```

核对文件读取、创建和命令执行记录，确认目录中生成 `hello.py`，运行输出为 `Hello, StepFun!`。

### 核对用量

在 [StepFun 开放平台](https://platform.stepfun.com)的使用详情中，按请求时间核对模型 ID 和计费来源，确认调用使用 Step Plan。

## 常见问题

> **Q: 模型列表中没有 Step 模型怎么办？**
>
> 检查生效目录中的 `models.json` 是否为有效 JSON，以及 `providers.stepfun.models` 中的模型 ID。打开 `/model` 重新加载配置，或重启 Pi 后运行 `pi --list-models stepfun`。

> **Q: 无法解析 API Key 或认证失败怎么办？**
>
> 在启动 Pi 的同一终端中设置 `STEP_API_KEY`，检查密钥是否完整、有效，且属于所用端点对应的账号。若 `auth.json` 中已保存 `stepfun` 凭据，Pi 会优先使用该凭据，应一并核对其内容。

> **Q: 请求路径错误怎么办？**
>
> `api` 使用 `anthropic-messages`，`baseUrl` 填写 `https://api.stepfun.com/step_plan`。Pi 自动追加 `/v1/messages`，配置地址只保留到 `/step_plan`。

> **Q: 上下文窗口显示与模型规格不一致怎么办？**
>
> 检查对应模型的 `contextWindow`：`step-5-preview` 使用 `1000000`，`step-3.7-flash` 使用 `256000`。保存后重新加载模型列表并选择该模型。


# Roo Code
Source: https://platform.stepfun.com/docs/zh/guides/developer/integrations/roo-code



Roo Code 是运行在 VS Code、Cursor 等编辑器中的编码 Agent，支持文件编辑、终端命令执行和多步工具调用。通过 OpenAI Compatible Provider，可使用 Chat Completions API 接入 Step Plan。

## 接入条件

* 已安装 VS Code 或 Cursor。运行下方修复与测试示例时，还需安装 Python 3。
* [Step Plan 订阅](https://platform.stepfun.com/step-plan)有效、额度可用，且具备所用模型的调用权限。
* 已在 [StepFun 开放平台密钥管理](https://platform.stepfun.com/interface-key)页面创建 API Key。

## 安装 Roo Code

在编辑器扩展市场中搜索 Roo Code，确认扩展标识为 `RooVeterinaryInc.roo-cline`。配置适用于 Roo Code 3.54.0；上游仓库已归档，使用时需确认与当前编辑器的兼容性。

## 配置 Step Plan

### 配置连接

1. 打开 Roo Code 面板，进入设置中的 `Providers`。
2. 在 `API Provider` 中选择 `OpenAI Compatible`，填写以下参数：

| 配置项 | 填写值 |
| - | - |
| `API Provider` | `OpenAI Compatible` |
| `Base URL` | `https://api.stepfun.com/step_plan/v1` |
| `API Key` | Step API Key，不包含 `Bearer ` 前缀或首尾空格。 |
| `Model ID` | `step-5-preview` |

Roo Code 自动追加 `/chat/completions`，完整请求路径为 `/step_plan/v1/chat/completions`。Base URL 保留到 `/step_plan/v1`，不要替换为普通按量 API 地址。

Roo Code 3.54.0 仅支持 OpenAI 原生工具调用，没有 XML 回退。所选模型需要支持函数调用，以下使用 [Step 5 Preview](/docs/zh/guides/models/step-5-preview)。

### 确认模型参数

展开 `Model Configuration`，按 Step 5 Preview 的能力核对设置：

| 配置项 | 设置 | 说明 |
| - | - | - |
| `Enable streaming` | 开启 | 使用流式输出。 |
| `Context Window Size` | `1000000` | 客户端使用的上下文窗口。 |
| `Include max output tokens` | `Off` | 不在请求中额外发送输出上限。 |
| `Max Output Tokens` | `-1` | 配合上一项关闭使用，由服务端处理输出长度。 |
| `Image Support` | 开启 | 允许图像输入。 |

3.54.0 开启 `Include max output tokens` 时会发送 `max_completion_tokens`。本配置关闭该选项；不要只修改 `Max Output Tokens` 而遗漏开关。若需要主动限制输出，应为推理和正文保留足够预算。

切换到其他模型时，按其规格调整上下文与输入能力。保存配置后新建任务。

## 接入 StepSearch MCP

需要联网搜索或获取网页内容时，可配置 [StepSearch](/docs/zh/guides/developer/search-mcp)。该服务通过 Step Plan 端点提供 `web_search` 和 `web_fetch`。

1. 在 Roo Code 面板打开 `MCP Servers`，选择编辑全局 MCP 配置。
2. 合并以下内容，保留已有的其他服务，将 `YOUR_STEP_API_KEY` 替换为实际密钥：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "mcpServers": {
    "step-search": {
      "type": "streamable-http",
      "url": "https://api.stepfun.com/step_plan/v1/mcp/web_search/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_STEP_API_KEY"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}
```

3. 保存后重新连接服务，确认 `step-search` 已连接，且工具列表包含 `web_search` 和 `web_fetch`。
4. 新建任务，调用其中一个工具完成搜索或网页抓取，按提示批准调用，并检查返回结果。

Roo Code 的 URL 型 MCP 配置必须显式提供 `type`，此处使用 `streamable-http`，不能写成 Cline 的 `streamableHttp`。`alwaysAllow: []` 保留逐次批准。

MCP 配置以明文保存 API Key，请勿将含真实密钥的文件提交到代码仓库或分享给他人。

## 验证接入

### 验证对话

新建任务并输入 `请只回复 OK。`，预期返回 `OK`。

### 验证修复与测试

1. 创建独立测试目录，添加以下两个文件。其中 `calc.py` 故意包含加法错误。

`calc.py`：

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
def add(left, right):
    return left - right
```

`test_calc.py`：

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import unittest

from calc import add


class TestAdd(unittest.TestCase):
    def test_add(self):
        self.assertEqual(add(2, 3), 5)
```

2. 在编辑器中打开该目录，选择允许修改文件的 `Code` 模式，向 Roo Code 发送：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
只在当前目录工作。读取 calc.py 和 test_calc.py，修复导致 test_add 失败的错误。
运行 python3 -m unittest test_calc -v；如果失败，继续修复并重新测试。
不要修改 test_calc.py 或其他文件。最后报告修改内容、执行命令和测试结果。
```

3. 按提示批准必要的文件与命令操作。确认 `calc.py` 中的加法已修复，测试输出为 `OK`，且 `test_calc.py` 未被修改。

手动批准即可完成验证，无需开启全部自动批准选项。

### 验证配置保存

重启编辑器，检查 Provider 与模型选择是否保留，并重新发起一次简短对话。

## 常见问题

> **Q: 发送消息后一直显示 API Request... 怎么办？**
>
> 先检查扩展宿主日志，确认是否存在 `Could not find ripgrep binary`。VS Code 可通过命令面板中的 `Developer: Open Logs Folder` 打开日志目录，查看当前窗口的 `exthost/exthost.log`。只有出现该错误时，才按下一项处理 ripgrep；其他情况应根据实际网络、认证或请求错误排查。

> **Q: Roo Code 3.54.0 找不到 ripgrep 怎么办？**
>
> 3.54.0 的路径探测未覆盖部分新版 VS Code 的 `ripgrep-universal` 目录布局。更改工作区或用户配置目录不会改变扩展查找的编辑器安装路径。
>
> macOS 的 VS Code 可在确认日志报错后使用以下临时兼容方案。脚本会在安装目录新增软链接，自动识别 Apple Silicon 或 Intel，且不会覆盖已有路径。源文件不存在或安装目录不可写时，应停止处理，不要提升权限强制执行。
>
> ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> (
>   set -eu
>   APP="/Applications/Visual Studio Code.app/Contents/Resources/app"
>   case "$(uname -m)" in
>     arm64) ARCH="darwin-arm64" ;;
>     x86_64) ARCH="darwin-x64" ;;
>     *) printf '%s\n' 'Unsupported architecture'; exit 1 ;;
>   esac
>   RG="$APP/node_modules.asar.unpacked/@vscode/ripgrep-universal/bin/$ARCH/rg"
>   TARGET="$APP/node_modules/@vscode/ripgrep/bin/rg"
>   if [ ! -x "$RG" ]; then
>     printf '%s\n' 'Bundled ripgrep was not found at the expected path.'
>     exit 1
>   fi
>   if [ -e "$TARGET" ] || [ -L "$TARGET" ]; then
>     printf '%s\n' 'The target already exists; no changes were made.'
>     exit 1
>   fi
>   mkdir -p "$(dirname "$TARGET")"
>   ln -s "$RG" "$TARGET"
>   "$TARGET" --version
> )
> ```
>
> 完成后运行 `Developer: Reload Window`，重新发起任务。该命令只适用于上述 macOS VS Code 安装位置；Cursor 和其他系统需核对各自的安装路径。编辑器更新可能移除软链接，出现相同日志时再检查。

> **Q: 提示 Connection error 或返回 401 怎么办？**
>
> 检查网络连接、Base URL、API Key 与模型权限。Base URL 使用 `https://api.stepfun.com/step_plan/v1`；API Key 应完整、有效，且属于对应端点的账号。模型连接的 API Key 字段不加 `Bearer `，MCP 的 `Authorization` 请求头则需要该前缀。

> **Q: 回复为空、被截断或推理阶段没有正文怎么办？**
>
> 推理阶段可能暂时没有正文。若请求结束后仍无正文，查看停止原因、错误信息与输出设置。确认 `Include max output tokens` 已关闭；若主动设置预算，过小的值可能在正文生成前被推理消耗。

> **Q: 模型只回复文字，或工具调用失败怎么办？**
>
> 确认当前为 `Code` 等允许执行任务的模式，已打开目标目录，并批准了必要的操作。所选模型必须支持 OpenAI 原生工具调用；若返回工具错误，核对模型 ID 和完整错误信息，并以工具调用记录确认执行情况。

> **Q: MCP 中没有 step-search 或连接超时怎么办？**
>
> 检查配置位于 `mcpServers` 下，`type` 为 `streamable-http`，`disabled` 为 `false`，请求头包含完整密钥与 `Bearer ` 前缀。保存后重新连接，并检查网络与服务日志；超时需要区分认证、网络和传输问题，不能直接归因于客户端版本。


# Zed
Source: https://platform.stepfun.com/docs/zh/guides/developer/integrations/zed



Zed 是一款高性能代码编辑器，内置 AI Assistant 能力，并支持通过 OpenAI Compatible API 调用第三方大模型。通过配置自定义 API Endpoint，Zed 可以接入 Step 模型，在编辑器内完成对话、代码生成、代码解释和代码修改等任务。

## 概述

Zed 适合在轻量编辑器中直接使用 AI Assistant。完成接口配置后，即可在编辑器内调用 Step 模型完成常见编程辅助任务。

## 前置条件

### 安装 Zed

下载并安装 Zed 编辑器：[https://zed.dev](https://zed.dev)

安装完成后启动 Zed。

### 订阅 Step Plan

在开始配置前，请先确认当前账号已完成 Step Plan 订阅。只有在账号具备对应计划或调用权限后，后续模型调用与额度使用才会正常生效。

如需订阅或购买，请访问：[Step Plan 订阅](https://platform.stepfun.com/step-plan)

### 获取 Step API Key

在 [Step 开放平台](https://platform.stepfun.com) 获取 API Key，用于身份认证和请求授权。

## 配置步骤

### 打开 Agent Panel 设置

使用命令面板（`Cmd+Shift+P`），输入并执行：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
agent: open settings
```

### 添加 LLM Provider

在打开的界面中，找到 **LLM Providers** 区域，点击右侧的 **+ Add Provider** 按钮，在弹出的表单中填写以下信息：

* **Provider Name**：`StepFun`（自定义名称，可任意填写）
* **API URL**：`https://api.stepfun.com/step_plan/v1`
* **API Key**：填写在 Step 平台获取的 API Key
* **Model Name**：`<model_id>`

> 说明：`<model_id>` 请填写当前账号在 Step Plan 下可用的模型。已验证示例：`step-5-preview`、`step-3.7-flash`、`step-3.5-flash-2603`、`step-3.5-flash`。文档列出的模型不构成全部可用名单。

填写完成后，点击 **Save Provider** 保存。

## 测试接入

### 基础对话测试

在 Agent Panel 中输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
hello
```

如果返回正常内容，说明 API 调用成功。

### 代码生成测试

输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Write a python hello world program
```

预期返回类似结果：

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
print("Hello, world!")
```

### 代码解释测试

在代码文件中选中一段代码后输入：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
Explain this code
```

如果能收到解释结果，说明模型调用链路正常。

## 常见问题

### 无法连接 API

请检查：

* API URL 是否填写为 `https://api.stepfun.com/step_plan/v1`
* API Key 是否有效
* 当前网络是否可访问 API Endpoint

### 模型返回错误

请确认 Model Name 是否填写正确，例如：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
<model_id>
```

### AI 无响应

建议重新检查以下配置并重启 Zed：

* API URL
* API Key
* Model Name（`<model_id>`）

## 总结

完成 LLM Provider 配置后，Zed 即可通过 Step API 提供对话、代码生成和代码解释等辅助能力。建议先完成基础对话和最小代码示例测试，再投入实际开发使用。


# JSON Mode 与 JSON Schema 结构化输出
Source: https://platform.stepfun.com/docs/zh/guides/developer/json-mode



阶跃星辰大模型可以用于情感分析、信息提取和内容评分等应用场景。[Step 5 Preview](/docs/zh/guides/models/step-5-preview) 支持 JSON Mode 与 JSON Schema 结构化输出，您可以按业务需要选择输出方式。

## 选择输出方式

| 方式 | 请求参数 | 适用场景 |
| - | - | - |
| JSON Mode | `response_format: {"type": "json_object"}` | 需要可解析的 JSON，不要求由 API 约束具体字段和类型 |
| JSON Schema | `response_format.type: "json_schema"`，并设置 `json_schema.strict: true` | 需要按指定 Schema 约束字段、类型和必填项 |

在 prompt 中描述结构或放入 JSON Schema，可以引导 JSON Mode 的输出，但不等同于 API 层面的严格结构约束。需要严格结构约束时，请使用 `json_schema` 参数，而不只是将 Schema 写入 prompt。

## JSON Schema：通过 API 约束输出结构

以下用法适用于 `step-5-preview`、`step-3.7-flash`、`step-3.5-flash` 和 `step-3.5-flash-2603`。

将 `response_format.type` 设置为 `json_schema`，并在 `response_format.json_schema` 中填写：

* `name`：Schema 名称。
* `strict`：设置为 `true`，启用严格模式。
* `schema`：期望的 JSON 结构，包括属性、类型和必填字段。

以下示例使用 `step-5-preview` 提取姓名和年龄。Schema 直接通过 API 参数传入，无需在 prompt 中重复。将 `YOUR_STEP_API_KEY` 替换为您的 API Key，在终端设置 `STEPFUN_API_KEY` 环境变量，再执行请求；`$STEPFUN_API_KEY` 表示读取该变量的值。以下命令适用于 Bash 或 Zsh，使用按量付费 API。

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export STEPFUN_API_KEY="YOUR_STEP_API_KEY"

curl --silent --show-error --fail-with-body \
  https://api.stepfun.com/v1/chat/completions \
  -H "Authorization: Bearer $STEPFUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "step-5-preview",
    "messages": [{"role": "user", "content": "提取人物：王明 28 岁。"}],
    "stream": false,
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "person",
        "strict": true,
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "required": ["name", "age"],
          "properties": {
            "name": {"type": "string"},
            "age": {"type": "integer"}
          }
        }
      }
    },
    "max_tokens": 1024
  }'
```

`choices[0].message.content` 是包含 JSON 的字符串，解析后的结果示例为：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{"name": "王明", "age": 28}
```

本例通过 `required` 指定两个字段都必须返回，通过 `additionalProperties: false` 禁止额外字段。结构约束不代表提取内容在事实或业务含义上一定正确，应用仍需进行业务校验。完整参数说明见 [Chat Completions API](/docs/zh/api-reference/chat/chat-completion-create)。

## JSON Mode：返回可解析的 JSON

### 使用方法

在使用 JSON Mode 时，您需要做三件事：

1. 在 System Prompt 中明确要求返回 JSON，并描述预期结构；也可以放入 JSON Schema 作为提示词引导，但这不提供严格的 Schema 约束。
2. 请求时，设置 response\_format 为 `{ "type": "json_object" }`，从而来让大模型返回可解析的 JSON 结果。
3. 解析大模型返回的结果，并验证是否符合预期。符合预期后即可使用在业务系统中对接。

### 参考代码

以使用大模型进行评论的情感分析为例子，您可以参考如下代码，让大模型返回 JSON 结果。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

# 初始化 阶跃星辰 Client
STEPFUN_KEY = "YOUR_STEP_API_KEY"

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

# 在 System Prompt 中定义返回结果
system_prompt = """
你是一个评论分析师，会根据用户的输入，分析用户输入的情感，并给出评论的情感分析结果
## 分析规则
1. 如果用户的评论中包含了负面情感词汇，那么情感分析结果为 negative
2. 如果用户的评论中包含了正面情感词汇，那么情感分析结果为 positive
3. 如果用户的评论中没有包含正面或者负面情感词汇，那么情感分析结果为 neutral
## 正面情感词汇
- 好
- 棒
- 优秀
## 负面情感词汇
- 差
- 糟糕
- 糟
## 例子
### 例子 1
#### 输入内容
"这个产品真的很好，我很喜欢"
####  输出内容
{  
    "emotion": "positive",
    "score": 0.9,
    "reason": "用户评论中包含了正面情感词汇"
}
### 例子 2
#### 输入内容
"这个产品好垃圾，我很讨厌"
####  输出内容
{  
    "emotion": "negative",
    "score": 0.9,
    "reason": "用户评论中包含了负面情感词汇"
}
## 输入内容
用户的评论文本
## 输出内容
按照如下结构输出 JSON 结果

class Response:
    emotion: str # 用户评论的情感分析结果，可选项为 positive, negative, neutral
    score: float # 用户评论的情感分析得分，范围为 0 到 1 之间
    reason: str # 用户评论的情感分析结果的原因

"""

response = client.chat.completions.create(
  model="step-5-preview",
  messages=[
    {"role": "system", "content": system_prompt},
    {"role": "user", "content": "这个产品还行？"}
  ],
  response_format={ "type": "json_object" },
)

print(response)
```

### 可选：在 prompt 中使用 Schema 引导 JSON Mode

JSON Schema 可以描述输出字段、类型和必填项。在 JSON Mode 的 prompt 中加入 Schema，可以引导输出结构，但不提供严格约束。

以下 Schema 定义了一个包含 `url` 和 `notes` 两个必填字段的对象：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "用户输入解析",
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
     "description":"用户输入的 URL"
    },
    "notes": {
      "type": "string",
 "description":"用户对于输入的 URL 的评价"
    }
  },
  "required": [
    "url",
    "notes"
  ]
}
```

在您的 prompt 中加入 JSON Schema，并设置 `response_format: {"type": "json_object"}`，可以引导模型按预期结构输出。以下仍是提示词示例，不是 API 的 `json_schema` 参数用法：

```markdown theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
你是一个专业的文本处理工程师，会根据用户的输入，从中提取 URL 和 用户的评价内容，并以 JSON 的方式返回。

## 约束

- 你会以下方的 JSON Schema 的格式返回给用户

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "用户输入解析",
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
     "description":"用户输入的 URL"
    },
    "notes": {
      "type": "string",
 "description":"用户对于输入的 URL 的评价"
    }
  },
  "required": [
    "url",
    "notes"
  ]
}
```

## 注意事项

* 两种方式都需要先检查请求是否成功，以及 `finish_reason` 是否为 `stop`。如果为 `length`，输出可能因 `max_tokens` 限制而被截断，不能按完整 JSON 使用；可提高输出上限后重试。
* 对于请求失败、拒绝回答或没有可用 `content` 的情况，请单独处理，不要直接作为业务 JSON 解析。
* 解析 `choices[0].message.content` 后，仍需校验数据是否满足业务要求。使用 JSON Mode 时，还需自行检查字段、类型和必填项。
* JSON Mode 可以通过 prompt 中的输入输出示例改善结构遵循效果，但不应据此承诺严格符合 Schema。
* 如果通过代理或网关调用，请确认 `response_format` 及其嵌套字段完整传递到 API 服务端；客户端请求中包含该字段，不代表中间链路一定保留了它。


# 多轮对话上下文管理
Source: https://platform.stepfun.com/docs/zh/guides/developer/multiple-round



大模型相比于传统的模型，拥有支持用户自定义 Prompt、用户可传入上下文等优势，从而轻松实现大模型的人设锚定、多轮对话等能力。

在实际使用时，阶跃星辰的 Chat Completion API 支持传入一个数组作为 Message List 。您只需要按照用户沟通的顺序，将用户信息和大模型返回的信息，构建成数组用于调用大模型，即可轻松实现基于大模型的多轮对话能力。

### 实现多轮对话

想要实现多轮对话，您需要在自己的业务系统中存储对话和对话内容，以便于形成对话记录。

因此，您需要在业务系统中建设 Chat 和 Message 对象，并在业务系统中存储 Chat 和 Messages。

* 当用户开启对话时，则创建 Chat；
* 当用户发送消息时，则创建 Message，并按照创建时间正序查询 Message，并构建对话记录作为参数传递给大模型用于结合上下文生成内容；
* 当大模型返回信息时，同样创建 Message。

![](https://mintcdn.com/stepfun/ivZhb9pOE5X12y-g/images/multiple_round.jpeg?fit=max\&auto=format\&n=ivZhb9pOE5X12y-g\&q=85\&s=87d378595830a339778f63e86f4ab90f)

#### 代码示例

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI
from datetime import datetime

# 初始化 阶跃星辰 Client
STEPFUN_KEY = "YOUR_STEP_API_KEY"

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

# 定义数据结构

class Chat:
  id: str
  user_id: str

class Message:
  chat_id: str
  role : str # 可选值 system, user,assistant,tool
  content: str # 用户输入的信息 / 大模型返回的信息
  created_at: datetime

# 从数据库中提取数据

# messages_from_db = orm.order_by ("created_at","asc").first (5)

messages_from_db = [
  {
    "chat_id":"chat_1",
    "role":"system",
    "content":"你是阶跃星辰大模型助手",
    "created_at": "2024-01-01 10:01:00"
  },
  {
    "chat_id":"chat_1",
    "role":"user",
    "content":"今天天气怎么样？",
    "created_at": "2024-01-01 10:02:00"
  },
  {
    "chat_id":"chat_1",
    "role":"assistant",
    "content":"对不起，我不能回答你关于天气的问题。",
    "created_at": "2024-01-01 10:03:00"
  },
  {
    "chat_id":"chat_1",
    "role":"user",
    "content":"那你告诉我北京适合去旅游么？",
    "created_at": "2024-01-01 10:04:00"
  }
]

def clean_msg(msg):
  del msg["chat_id"]
  del msg["created_at"]
  return msg

messages_for_chat = [clean_msg (item) for item in messages_from_db]

# 调用补全接口进行补全

stream = client.chat.completions.create(
  model="step-5-preview",
  messages=messages_for_chat,
  stream=True,
)

# 对流式返回的内容进行打印 / 渲染输出

for chunk in stream:
  if chunk.choices[0].delta.content is not None:
    print(chunk.choices[0].delta.content, end="")
```

### 管理对话上下文

`step-5-preview` 支持 1M tokens 上下文；`step-3.7-flash` 和 Step 3.5 Flash 系列支持 256K。请按实际使用模型的上下文窗口管理历史记录，并为输出预留空间。对话历史也会计入输入 Token 和费用，因此应根据业务需要选择历史长度，而不是无条件传入全部记录。

* 一般日常的对话可以保留 10 轮对话记录；

* 对于某些需要深度沟通、对话的场景，则可以选择将完整对话记录交给大模型进行补全。

> **[引入 Prompt 缓存降低费用，提升推理速度](/docs/zh/guides/developer/prompt-cache)**

### 常见问题

* 如果要实现多轮对话的效果，需要在存储对话记录时，按时间记录，并在重新取出给大模型时，按照时间正序给出答案，以便于大模型正确的理解上下文。


# 从 OpenAI 迁移至阶跃星辰
Source: https://platform.stepfun.com/docs/zh/guides/developer/openai



## 前提条件

阶跃星辰大模型支持个人和企业调用，您可以在开放平台后台创建 API Key，并使用 API Key 调用。在测试模型能力时，除了通过 API 调用，您也可以通过体验中心快速体验阶跃星辰大模型。

> 在测试完成后， 您可以通过[联系我们](/docs/zh/guides/contact-us)联系阶跃星辰客服，我们将会为您提供和 OpenAI 对标的 TPM / RPM 限制，帮助您无缝迁移调用。

## 模型选择

阶跃星辰为开发者提供多种模型能力，您可以根据自己当前使用的模型，切换至阶跃星辰大模型。

### 推理与多模态模型

* `step-5-preview`：面向真实任务的新一代旗舰基模，支持文本、图片和视频输入，提供 1M tokens 上下文，适合编程、专业知识工作和多步骤 Agent 任务。
* `step-3.7-flash`：高速多模态推理模型，原生支持图片和视频理解，支持三档推理强度（low/medium/high），适合智能体、代码与多模态场景。
* `step-3.5-flash`：高速语言推理模型，顶尖推理能力与快速可靠的执行能力，适合逻辑推理、数学、软件工程、深度研究等复杂任务。

### 文生图模型

> [!NOTE]
>
> 文生图与图片编辑相关模型已于 2026 年 10 月 10 日下线，相应接口已同步停止服务。详见[图像模型下线公告](/docs/zh/announcements/image-model-retirement)。

## API 兼容

目前，阶跃星辰大模型兼容 OpenAI 的 API 规范，您可以直接使用 OpenAI 的 SDK 进行调用，如果您的应用已经在使用 OpenAI SDK 开发，那么可以以极低的成本进行迁移。

目前我们与 OpenAI 兼容的 API 如下：

* [Chat Completion](/docs/zh/api-reference/chat/chat-completion-create)
* [上传文件](/docs/zh/api-reference/files/create)
* [获取文件列表](/docs/zh/api-reference/files/list)
* [获取文件信息](/docs/zh/api-reference/files/retrieve)
* [获取文件内容](/docs/zh/api-reference/files/retrieve-content)
* [删除文件](/docs/zh/api-reference/files/delete)
* [获取模型列表](/docs/zh/api-reference/models/list)
* [查询单个模型信息](/docs/zh/api-reference/models/retrieve)

## SDK 迁移指南

### OpenAI Python SDK

从 OpenAI Python SDK 迁移时，您只需要将原本的 Client 初始化中的参数 `api_key` 替换为阶跃星辰的 API Key ，并新增 `base_url` 设置为 `https://api.stepfun.com/v1`，并在具体的模型设置中，设置为阶跃星辰大模型即可完成调用。

```python copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# 修改前
client = OpenAI(
    api_key="OPENAI_KEY"
)

# 修改后
client = OpenAI(
    api_key="YOUR_STEP_API_KEY",
    base_url="https://api.stepfun.com/v1"
)
```

### OpenAI TypeScript SDK

从 OpenAI TypeScript SDK 迁移时，您只需要将原本的 Client 初始化中的参数 `api_key` 替换为阶跃星辰的 API Key ，并新增 `base_url` 设置为 `https://api.stepfun.com/v1`，并在具体的模型设置中，设置为阶跃星辰大模型即可完成调用。

```typescript copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// 修改前
const openai = new OpenAI({
	apiKey: 'OPENAI_KEY',
})

// 修改后
const openai = new OpenAI({
	apiKey: 'YOUR_STEP_API_KEY',
	baseURL: 'https://api.stepfun.com/v1',
})
```

### LangChain

在使用 Langchain 开发应用时，您只需要修改 ChatOpenAI 初始化时的 `openai_api_key`、`openai_api_base` 和 `model_name` ，即可切换至阶跃星辰大模型。

```python copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from langchain.chat_models import ChatOpenAI
from langchain.prompts import PromptTemplate
from langchain.chains import LLMChain
from os import getenv
from dotenv import load_dotenv

load_dotenv()

template = """你是阶跃星辰大模型开发的智能助手，你会根据用户的问题，一步一步的思考并回答。用户的问题是：问题：{question}"""

prompt = PromptTemplate(template=template, input_variables=["question"])

# 修改前
# llm = ChatOpenAI(
#   openai_api_key=getenv("OPENAI_KEY"),
#   model_name="gpt-4o"
# )

# 修改后
llm = ChatOpenAI(
  openai_api_key=getenv("STEP_API_KEY"),
  openai_api_base="https://api.stepfun.com/v1",
  model_name="step-5-preview"
)

llm_chain = LLMChain(prompt=prompt, llm=llm)

question = "阶跃星辰大模型如何帮助企业员工提升效率"

print(llm_chain.run(question))
```

### LangChain.js

在使用 Langchain.js 开发应用时，您只需要修改 ChatOpenAI 初始化时的 modelName、openAIApiKey 和 basePath ，即可切换至阶跃星辰大模型。

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
// 修改前
const chat = new ChatOpenAI({
	modelName: 'gpt-4o',
	openAIApiKey: $OPENAI_KEY,
})

// 修改后

const chat = new ChatOpenAI(
	{
		modelName: 'step-5-preview',
		openAIApiKey: $STEP_API_KEY,
	},
	{
		basePath: 'https://api.stepfun.com/v1',
	},
)
```


# 静态托管 CLI 与 MCP
Source: https://platform.stepfun.com/docs/zh/guides/developer/page-hosting-cli-mcp



本指南面向在**生产环境**使用 StepFun 静态托管的开发者与 CI 集成方，覆盖 `steppage` 命令行工具（CLI）与 Page MCP Server 两种接入方式。二者共用同一把 Page 托管 API Key：CLI 面向人工操作与 CI/CD 流水线，MCP 面向 Claude 等 MCP 客户端、由模型直接调用。当前版本 1.0.0。

## 准备工作

两种方式都要求本机已安装 **Node.js 20 或更高版本**（安装脚本会做校验，低于 20 直接报错退出）。同时需要一把有效的 Page 托管 API Key，可在[阶跃星辰开放平台](https://platform.stepfun.com)控制台获取；CLI 与 MCP 都用这把 Key 认证，认证后仅能访问该 Key 拥有的站点。

## steppage CLI

### 安装

生产渠道通过 curl 一键脚本安装，脚本会下载自包含独立产物到 `~/.steppage/bin/`，并在 `~/.local/bin/steppage` 写入可执行包装器：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -fsSL https://dl.stepfun.com/steppage-cli/p/install.sh | bash
```

如需固定到某个版本，在命令前加 `VERSION` 环境变量（默认 `latest`）：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
VERSION=v1.0.0 curl -fsSL https://dl.stepfun.com/steppage-cli/p/install.sh | bash
```

若安装后提示 `~/.local/bin` 不在 PATH 中，将下面一行加入 shell 配置（如 `~/.zshrc`）后重开终端：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export PATH="$HOME/.local/bin:$PATH"
```

验证安装：`steppage --version`；查看全部命令：`steppage --help`。

### 认证

推荐先登录一次，校验并保存密钥。将示例中的 `YOUR_STEP_API_KEY` 替换为您的 Page 托管 API Key。`login` 会向服务端探测身份，成功后把密钥写入 `~/.steppage/config.json`（文件权限 600）：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
steppage login --key YOUR_STEP_API_KEY
steppage whoami   # 打印当前 key 对应的 uid
steppage logout   # 清除已保存的 key
```

在 CI 等无状态环境中可跳过 `login`，直接用环境变量 `STEPFUN_API_KEY` 提供密钥，所有命令都会自动读取。

### 快速开始：部署一个目录

一条 `deploy` 命令即可完成「构建产物 → 上传 → 发布版本」。首次部署用 `--name` 新建站点，加 `--go-live` 在发布同时上线：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
steppage deploy ./dist --name my-site --go-live
```

向**已有**站点发布新版本则用 `--site <id>`。`deploy` 接受一个目录（递归扫描）或单个 `.zip`。产物根目录若无 `index.html`，需用 `--root <file>` 指定站点首页，或用 `--no-root-page` 声明不提供首页；交互终端下会提示选择根文件，CI（非 TTY）下则直接报错要求显式传参。

### 命令参考

| 命令 | 说明 | 关键参数 |
| - | - | - |
| `login` | 校验并保存托管 API key | `--key YOUR_STEP_API_KEY`（不填则交互输入） |
| `logout` | 清除已保存的 API key | — |
| `whoami` | 打印当前 key 对应身份 | — |
| `deploy <path>` | 构建产物并发布 | `--site`、`--name`、`--root`、`--no-root-page`、`--go-live` |
| `list` | 列出您的站点 | — |
| `get` | 查看单个站点 | `--site`（必填） |
| `update` | 重命名站点或修改服务模式 | `--site`（必填）、`--name`、`--serving-mode`（可选值为 `spa` 或 `static`，后两者至少填一个） |
| `delete` | 删除站点（不可逆） | `--site`（必填）、`--yes`（跳过确认；非 TTY 必填） |
| `versions` | 列出站点版本 | `--site`（必填） |
| `promote` | 将暂存版本上线 | `--site`、`--version`（必填） |
| `rollback` | 回滚到较旧版本 | `--site`、`--version`（必填） |
| `preview mint` | 获取或创建某版本的持久预览链接 | `--site`、`--version`（必填） |
| `preview expiry` | 设置或清除预览链接过期时间 | `--site`、`--version`、`--expires`（可设为 `never`、小时数或天数，例如 `24h`、`7d`） |
| `preview revoke` | 撤销某版本的预览链接 | `--site`、`--version`（必填） |
| `config --show` | 打印解析后的环境、是否已配置 key 及配置文件路径 | — |

**全局选项**（可用于任意命令）：`--json` 让命令在 stdout 输出机读 JSON（错误仍走 stderr），便于 CI 解析；`-H, --header "Name: value"` 注入自定义 HTTP 请求头，可重复；`-v, --version` 打印版本。

### 典型工作流

\*\*预发布再上线。\*\*先发布但不上线，取预览链接验收，确认无误后再上线：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
steppage deploy ./dist --site 123                # 发布新版本（不上线）
steppage preview mint --site 123 --version 456   # 取预览链接验收
steppage promote --site 123 --version 456        # 验收通过后上线
```

\*\*回滚。\*\*线上版本出问题时，回滚到历史版本：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
steppage versions --site 123                  # 查历史版本
steppage rollback --site 123 --version 400    # 回滚到指定版本
```

\*\*CI 集成。\*\*流水线中设置 `STEPFUN_API_KEY` 免登录，并加 `--json` 解析结果：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export STEPFUN_API_KEY="YOUR_STEP_API_KEY"
steppage deploy ./dist --site 123 --go-live --json
```

`promote`、`rollback` 会改变线上版本，`delete` 不可逆。`delete` 在交互终端下需输入站点名二次确认，在无 TTY 的 CI 中必须显式加 `--yes` 才会执行。

## Page MCP Server

MCP Server 把上述部署、上线、回滚、巡检能力封装成 MCP 工具，供 Claude 等客户端由模型直接调用。它以 stdio 方式运行，**纯环境变量认证**（不读写任何配置文件），与 CLI 使用同一把 Page 托管 API Key。

### 安装

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -fsSL https://dl.stepfun.com/steppage-mcp/p/install.sh | bash
```

同样支持 `VERSION=v1.0.0` 固定版本。脚本安装产物到 `~/.steppage-mcp/bin/`，并在 `~/.local/bin/steppage-mcp` 写入包装器——这个路径就是要填给 MCP 客户端的命令。

### 配置 MCP 客户端

在客户端的 MCP 配置中，把 `command` 指向安装好的包装器，并通过 `env` 传入密钥。以 Claude 为例：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "mcpServers": {
    "steppage": {
      "command": "/Users/<you>/.local/bin/steppage-mcp",
      "env": {
        "STEPFUN_API_KEY": "YOUR_STEP_API_KEY"
      }
    }
  }
}
```

把 `<you>` 换成您的用户名（用绝对路径最稳妥）。`STEPFUN_API_KEY` 是唯一必填认证项。

### 工具参考

| 工具 | 说明 | 关键参数 |
| - | - | - |
| `page_deploy` | 构建并发布本地目录 / .zip，返回预览 URL（goLive 时附线上 URL） | `path`（必填）、`site`、`name`、`root`、`noRootPage`、`goLive` |
| `page_list_sites` | 列出当前 key 拥有的站点 | — |
| `page_get_site` | 查看单个站点 | `site`（必填） |
| `page_update_site` | 重命名站点或修改服务模式 | `site`（必填）、`name`、`servingMode`（可选值为 `spa` 或 `static`） |
| `page_delete_site` | 永久删除站点（不可逆） | `site`（必填） |
| `page_list_versions` | 列出站点版本 | `site`（必填） |
| `page_promote` | 将暂存版本上线 | `site`、`version`（必填） |
| `page_rollback` | 回滚到较旧版本 | `site`、`version`（必填） |
| `page_inspect` | 查看服务配置（含 header 规则）与版本列表 | `site`（必填） |
| `page_preview_mint` | 获取或创建持久预览链接 | `site`、`version`（必填） |
| `page_preview_expiry` | 设置或清除预览链接过期时间 | `site`、`version`、`expires`（可设为 `never`、小时数或天数，例如 `24h`、`7d`） |
| `page_preview_revoke` | 撤销预览链接 | `site`、`version`（必填） |
| `page_whoami` | 查看当前 key 对应身份 | — |

说明：ID 类参数均为数值型字符串，工具内部做了 bigint 安全处理；多文件产物若无 `index.html`，`page_deploy` 需传 `root` 或 `noRootPage`（MCP 无交互提示）。`page_promote`、`page_rollback`、`page_delete_site` 为破坏性操作，调用前请确认。

## 环境变量与语言

| 变量 | 适用 | 说明 |
| - | - | - |
| `STEPFUN_API_KEY` | CLI + MCP | Page 托管 API Key。CLI 可用它免 `login`；MCP 的唯一认证方式 |
| `STEPPAGE_OVERSEA` | CLI + MCP | 设为真值时输出英文（海外）；默认中文（国内）。安装脚本已按区域预置默认值 |
| `VERSION` | 安装脚本 | 固定安装版本，如 `v1.0.0`；默认 `latest` |

## 故障排查

| 现象 | 处理 |
| - | - |
| 安装报 Node 版本过低或找不到 node | 安装 / 升级到 Node.js 20+ 后重跑脚本 |
| `steppage: command not found` | `~/.local/bin` 未在 PATH：加 `export PATH="$HOME/.local/bin:$PATH"` 并重开终端 |
| API Key 被服务器拒绝 | 确认 API Key 有效且填写正确；重新执行 `login` 或检查 `STEPFUN_API_KEY` |
| 部署报缺少 index.html | 用 `--root <file>` 指定首页，或 `--no-root-page` 声明不提供首页 |
| CI 中 delete 无反应 / 报错 | 非 TTY 环境删除必须加 `--yes` |


# Prompt 优化
Source: https://platform.stepfun.com/docs/zh/guides/developer/prompt



Prompt Engineering 是用户与模型之间的重要桥梁。优化提示对于的模型推理结果至关重要。通过从简单到复杂的案例展示，将帮助开发者掌握提示词的使用，以提升大语言模型在文本总结、推理和转换等基础自然语言处理任务中的能力。

### Prompt（提示词）设计原则

#### 原则一：编写清晰且具体的指令

##### 1. 明确的表达

* **模糊指令**：❌

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
讲讲艺术。
```

用户的需求不清晰，可能导致模型产生各种艺术形式的泛泛介绍。

* **明确指令**：✅
  ```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  请解释印象派绘画的特点，并列举三位著名的印象派画家。
  ```
  明确指出需要讨论的艺术流派（印象派）和具体的输出要求（特点和画家），避免模型产生不相关的内容。

##### 2. 详尽的指令

* **简略指令**：❌
  ```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  解释经济学。
  ```
  过于宽泛，无法明确用户的具体需求。
* **详细指令**：✅
  ```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  请解释供需理论，特别是如何通过供需平衡影响商品价格。举例说明供给过剩和需求不足时的价格变化。
  ```
  提供了具体的经济学概念（供需理论）和要求（影响及举例），确保模型提供详细且相关的信息。

##### 3. 巧用分隔符

* **无分隔符**：❌
  ```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  分析这段文本并总结观点
  ```
  无法分辨哪部分是需要分析的文本，哪部分是指令，容易引起误解。
* **使用分隔符**：✅
  ```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  请分析以下文本，文本内容存在 XML 标签 <TEXT></TEXT > 中：<TEXT > 文本内容 </TEXT > 并总结主要观点。
  ```
  使用 XML 标签清晰地将需要分析的文本和指令区分开，避免混淆，确保模型正确理解和处理任务。

##### 4. 考虑特殊情况

* **无条件检查**：❌
  ```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  请列出文本中的错误。
  ```
  未指明错误类型，可能导致结果不符合预期。
* **有条件检查**：✅
  ```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  检查以下文本是否包含语法错误，如果有，请指出并纠正；如果没有，请说明没有错误。
  ```
  指明先检查语法错误的存在与否，再决定下一步行动，确保模型按要求执行。

##### 5. 使用少样本（Few-Shot-Prompt）帮助大模型理解

* **无示例**：❌
  ```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  解释隐喻的使用。
  ```
  语调和风格不明确，模型可能无法理解具体要求。
* **提供示例**：✅
  ```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  以下是对话示例，请解释隐喻的使用：
  < 人甲 >: 如何才能成为优秀的领导？
  < 人乙 >: 就像一艘船的船长，需要在风暴中稳住航向，指引船员们前进。
  ```
  提供一个对话样本，展示预期的语调和风格，帮助模型理解任务要求和输出格式。

#### 原则二：给模型时间去思考

在设计提示词时，为语言模型提供充足的推理时间非常重要。与人类一样，语言模型在解决复杂问题时也需要时间。如果让模型匆忙得出结论，结果可能不准确。例如，若仅提供书名和一句简介让模型推断一本书的主题，可能得不到理想的答案。因此，我们应在提示词中指引模型进行深入思考，例如先列出问题的各种看法，再得出最终结论。通过逐步推理，模型能更好地进行逻辑思维，输出更准确的结果。

##### 1. 指定完成任务的步骤

下面是一个示例，我们描述了西游记的故事，并给出以下 prompt 指导模型操作：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请按照以下步骤分析文本并给出最终的结果。
        1.        用一句话概括文本内容。
        2.        将概括翻译成英文。
        3.        列出故事中的人名。
        4.        输出包含概括和人名个数的 JSON 对象。
文本内容如下：
孙悟空和猪八戒一起前往花果山摘桃子。他们一路上嘻嘻哈哈，孙悟空蹦蹦跳跳地在前面带路，猪八戒则慢悠悠地跟在后面。到了花果山后，孙悟空灵活地爬上树摘桃子，猪八戒在树下等得着急，就自己到处找桃子。结果猪八戒不小心掉进了一个小水坑，弄得一身泥水，孙悟空看到后哈哈大笑。最后他们带着摘到的桃子一起回到了唐僧所在的地方。
```

模型输出：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
1. 概括：孙悟空和猪八戒去花果山摘桃子，猪八戒掉进小水坑，最后他们带着桃子回到唐僧处。
2. 翻译：Sun Wukong and Zhu Bajie went to Huaguo Mountain to pick peaches. Zhu Bajie accidentally fell into a small puddle. Finally, they returned to where Tang Seng was with the picked peaches.
3. 人名：孙悟空、猪八戒
4. 输出：{"summary": "孙悟空和猪八戒去花果山摘桃子，猪八戒掉进小水坑，最后他们带着桃子回到唐僧处。", "num_names": 2}
```

##### 2. 指导模型自主思考（吴恩达反思工作流）

在设计提示词时，我们可以要求语言模型先自行思考再下结论。例如，假设我们要模型判断一个数学问题的解答是否正确，仅提供问题和解答是不够的。相反，我们可以先让模型自己解决问题，再与提供的解答进行比较。这能帮助模型更好地理解问题，做出更准确的判断。接下来给出了三步反思 prompt。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请按照以下步骤分析问题并给出最终的结果。
               第一步：请按照你对问题的理解给出答案。
               第二步：请验算答案的准确性，若准确则直接输出答案，若错误，请给出解决问题的建议。
               第三步：请根据建议的方式，解决问题。并再次按照第二步方式验算答案或者给出解决问题的建议。
问题内容：
笼子里有若干只鸡和兔子，共有 35 个头和 94 只脚。问笼子里有几只鸡和兔子？
```

模型推理

第一轮直接解答：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
鸡有 21 只，兔子有 14 只。（假设模型答错了）
```

第二轮验算答案的正确性：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
鸡有 21 只 * 2 只腿 / 每鸡 等于 42 只腿
兔子 14 只 * 4 只腿 / 每兔 等于 56 只腿
总计 42+56=98 只腿
根据题干中笼子里有 94 只腿，跟验算的结果 98 只腿不相等，答案错误。请使用代数并一步一步推理解答问题。
```

第三轮模型一步一步推理解答：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
设鸡有 x 只，兔有 y 只。
1. 首先根据头的数量可得方程：
  - x + y = 35，即 y = 35 - x。
2. 然后根据脚的数量可得方程：
  - 2x + 4y = 94。
  - 将 y = 35 - x 代入 2x + 4y = 94 可得：
  - 2x + 4 (35 - x) = 94。
  - 展开式子得：2x + 140 - 4x = 94。
  - 移项得：2x - 4x = 94 - 140。
  - 合并同类项得：-2x = -46。
  - 解得：x = 23。
  - 把 x = 23 代入 x + y = 35，得 23 + y = 35，解得 y = 12。
  - 经过验算，答案正确，所以鸡有 23 只，兔子有 12 只。
```

### 常用 Prompt 参考

#### 文本分析

##### 1. 情感分析

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
## 角色
- 你是一位情感分析师

## 目标
- 对给定文本进行情感分析，识别并分类情感倾向为正面、负面或中性，用于市场分析、客户反馈或舆情监控。判断情感倾向的标准如下：正面情感倾向包括表达喜爱、满意、赞扬等的词汇；负面情感倾向包括表达不满、抱怨、批评等的词汇；中性情感倾向是对事物客观的描述，不带有明显的情感色彩。

## 限制
- 输出结果仅为情感倾向的类别：正面、负面、中性。

## 输出
- 输出格式：情感倾向类别

## 工作流程
1. 读取并理解给定的文本：文本内容存在 XML 标签 < TEXT></TEXT > 中，<TEXT > 这里填入需要进行情感分析的内容 </TEXT>。
2. 根据文本内容，判断其情感倾向。
3. 输出判断出的情感类别（例如：正面、负面或中性）。
```

##### 2. 文档分析

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
## 角色
- 你是一位文档分析师

## 目标
- 高效准确地处理和分析大量文档，提炼出文档的核心内容，生成清晰准确的文档摘要并提取关键信息。

## 限制
- 输出内容仅包含文档摘要和关键信息，不包含其他多余信息。

## 输出
- 输出格式：文档摘要和关键信息

## 工作流程
1. 读取并理解给定的文本，文本内容存在 XML 标签 < TEXT></TEXT > 中：<TEXT > 这里填入需要分析的文本 </TEXT>。
2. 基于对文档内容的理解，运用简洁明了的语言生成高度概括的摘要，突出核心要点。
3. 精准提取文档中的关键信息，涵盖重要事实、准确数据或合理结论等。
4. 按照规定格式输出文档摘要和关键信息。
```

##### 3. 文本翻译

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
## 角色
- 你是一位翻译专家

## 目标
- 高效准确地将文本从一种语言翻译成另一种语言，并确保翻译结果的准确性和自然流畅性。

## 限制
- 输出内容应符合目标语言的语法和文化背景，不包含多余或偏离原意的内容。

## 输出
- 输出格式：最终翻译

## 工作流程
1. 读取并理解给定的文本，文本内容存在 XML 标签 < TEXT></TEXT > 中：<TEXT > 这里填入需要翻译的文本 </TEXT>。
2. 进行初步翻译，确保翻译结果在语义上与原文一致。
3. 将输出的翻译结果与原文对照，提出修改建议。修改建议应包括改进翻译准确性、流畅性、文化适应性等方面。
4. 基于修改建议对翻译的结果进行修正，并生成最终翻译。
5. 输出最终翻译。
```

### 注意事项

在开发和使用大模型时，需注意其生成虚假知识的风险，即 “幻觉” 现象。尽管模型掌握了丰富的知识，它们仍可能会编造看似真实但实则虚假的信息。

为应对这一问题，开发者一方面可以通过优化 Prompt 设计来减少幻觉，例如引用原句来追踪信息来源，或者使用上文提到的反思工作流。另一方面可以使用阶跃大模型提供的 Tool call 工具，Tool call 可以扩展语言模型的功能，使其能够执行额外的操作，如搜索信息、计算、访问数据库等。


# Prompt 缓存
Source: https://platform.stepfun.com/docs/zh/guides/developer/prompt-cache



在开发大模型的多轮对话和固定场景人设问答时，会将用户的输入和大模型的回答构建成对话历史传递在整个对话中，而随着对话轮次增加，整个对话过程中的重复内容也会逐渐增多。

Prompt 缓存可复用请求中的重复前缀。缓存命中的输入 Token 按对应模型的缓存命中单价计费，单价见 [API 定价](/docs/zh/guides/pricing/details#文本与多模态模型)。

## 缓存支持模型

目前 `step-5-preview`、`step-3.7-flash`、`step-3.5-flash`、`step-3.5-flash-2603`、`step-1o-turbo-vision` 等模型支持 Prompt 缓存，其他模型的支持情况请以对应模型文档和定价表为准。

## Prompt 缓存的基础原理

当请求超过 256 个 Token 时，缓存会自动启用。当您发起一次 API 请求时，会执行如下操作：

1. **缓存查询**：根据您的请求的 Prompt 的前缀，查询当前的 Prompt 是否有系统的缓存。

2. **缓存命中**：如果命中系统的缓存，系统将会使用缓存，并加上本次请求中缓存不包含的内容，进行推理。

3. **缓存未命中**：如果未命中系统的缓存，系统将会进行正常的推理并在处理完成后，将 Prompt 前缀进行缓存，以供下次请求使用。

在包含多 Example、多轮次对话、长上下文或背景信息的场景下，缓存命中率会更高，帮助开发者提升系统整体性能，优化成本。

缓存淘汰采用最近最少使用（LRU）策略，在系统请求高峰期，不使用的缓存会更容易被逐出；在系统请求低峰期，缓存则会拥有更长的生命周期。

## 如何判断自己是否使用了 Prompt 缓存

在调用 Chat API 进行补全时，如果 `response.usage.cached_tokens` 大于 0，则表明该请求命中缓存，其值为命中的输入 Token 数。字段为 0 时表示未命中缓存。

以下为用量字段的示意响应，实际返回内容以请求结果为准：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "id": "22ebae159c8f10c8657253671c8f7f17.6de8d4f65f5ba3dddeb693a1aa83de1e",
    "object": "chat.completion",
    "created": 1730963954,
    "model": "step-5-preview",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "xxx"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "cached_tokens": 512,
        "prompt_tokens": 591,
        "completion_tokens": 120,
        "total_tokens": 711
    }
}
```

以上面这个请求结果为例，输入总量仍为 591 Token，其中 512 Token 按缓存命中单价计费，剩余 591 - 512 = 79 Token 按缓存未命中单价计费。缓存不会减少实际输入 Token 数，也不意味着命中部分免费。输入费用为 `(79 × 缓存未命中单价 + 512 × 缓存命中单价) / 1,000,000`，其中单价的单位为元 / 1M tokens；输出 Token 另行计费。

## 什么样的内容会进入缓存

在进行缓存时，**会以 256 个 Token 作为最小单元开始进行缓存**，当您的 Prompt 长度少于 256 个 Token 时，将不会命中缓存。

具体可缓存的信息会包含如下内容：

* **对话信息**：完整的对话数组会进入到缓存系统当中，其中包含 System Prompt、User Message 以及 Assistant Message。

* **图片信息**：用户消息中包含的图片信息也会进入缓存当中，但需要保证前后使用的是相同的图片。

* **视频信息**：用户消息中包含的视频信息也会进入缓存当中，但需要保证前后使用的是相同的视频。

* **工具调用信息及其结果**：对话信息中的工具调用信息及其调用结果也会参与到缓存当中。

## 最佳实践

* 在 Prompt 的开头使用静态或者重复的内容，而在整个 Prompt 结尾放置动态的内容；
* 监控不同 Prompt 的 Cached Token 和 Prompt Token 的比重、延迟、命中率，来优化 Prompt 结构；
* 近期未使用的缓存会被系统逐出，因此，尽可能保持 Prompt 前缀的稳定，以获得更高的缓存命中率。
* 对于较长的 Prompt，可以放在系统流量非高峰期进行，以减少缓存被逐出的次数，获得更高的缓存命中率。

## 如何对缓存进行排查

如果您的请求没有按照您的预期进行缓存，您可以按照如下的思路进行排查：

1. 确保缓存的部分在每次调用过程中都始终保持一致；
2. 检查是否两次请求间隔时间太长，以避免缓存失效；
3. 验证是否提供了至少 256个 Token 作为输入。

## 常见问题

### 缓存是否影响模型的推理的效果？

缓存不会影响模型的推理效果，每次生成都会使用完整的 Prompt 进行推理。

### 我是否需要为 Prompt 缓存额外付费？

无需单独开通付费缓存功能。未命中的输入 Token（包括首次写入缓存的内容）按缓存未命中单价计费，命中的输入 Token 按缓存命中单价计费。具体单价见 [API 定价](/docs/zh/guides/pricing/details#文本与多模态模型)。

### 我是否可以手动清除 Prompt 缓存？

目前不提供手动清除缓存的能力。您可以通过修改 Prompt 来使请求不命中缓存；

### 我是否可以让我的请求始终命中缓存？

目前我们不提供保证始终命中的 Prompt 缓存，如果您有相关诉求，可以通过联系我们和我们取得联系，确认您的场景和问题。


# 实时对话
Source: https://platform.stepfun.com/docs/zh/guides/developer/realtime



> 如果您是 Realtime API 的新手，可尝试 [stepfun-realtime-api](https://www.npmjs.com/package/stepfun-realtime-api)。

本指南将介绍使用 Realtime API 时模型功能（如音频生成、文本生成、函数调用）所需的事件流程，以及如何理解实时会话的状态。
在模型生成响应的过程中，服务器会发出多个生命周期事件。您可以监听这些事件（如 `response.text.delta`），在响应生成时向用户提供实时反馈。
服务器发出的事件完整列表见[Realtime API 事件列表](/docs/zh/api-reference/realtime/chat)，它们按大致的发出顺序排列，同时包含文本生成相关的客户端事件。

## 实时语音到语音会话

实时会话是模型与连接的客户端之间的有状态交互。会话的关键组成部分包括：

* **会话（Session）** 对象：控制交互参数，如使用的模型、生成输出的语音、其他配置等。
* **对话（Conversation）**：表示当前会话中生成的用户输入项和模型输出项。
* **响应（Responses）**：模型生成的音频或文本项，会被添加到对话中。

**输入音频缓冲区与 WebSocket**

如果使用 WebSocket 处理音频，需要通过发送包含 base64编码音频的 JSON 事件，手动与**输入音频缓冲区**交互。

所有这些组件共同构成了实时会话。您将使用客户端事件更新会话状态，并监听服务器事件以响应会话中的状态变化。

如需手动建立连接，也可通过 WebSocket 直接对接。

## 快速开始:创建 WebSocket 语音链路

通过 WebSocket 连接需使用以下连接信息：

| 类别 | 详情 |
| - | - |
| URL | wss\://api.stepfun.com/v1/realtime |
| 查询参数 | model：需连接的实时模型，比如 `step-audio-2`/`step-audio-2-mini`/`step-1o-audio` |
| 请求头 | Authorization: Bearer YOUR\_STEP\_API\_KEY |

以下是多个通过上述连接信息初始化 WebSocket 连接的示例，可用于对接 Realtime API：

### 示例1：使用 ws 模块（Node.js 环境）

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import WebSocket from 'ws'

// 连接地址（需替换为实际要使用的模型ID）
const url = 'wss://api.stepfun.com/v1/realtime?model=step-1o-audio'
// 初始化WebSocket连接
const ws = new WebSocket(url, {
	headers: {
		Authorization: 'Bearer ' + process.env.STEPFUN_API_KEY, // 从环境变量中获取标准API密钥
	},
})

// 监听“连接成功”事件
ws.on('open', function open() {
	console.log('已连接到服务器。')
})

// 监听“接收消息”事件
ws.on('message', function incoming(message) {
	console.log(JSON.parse(message.toString())) // 解析并打印接收的消息
})
```

### 示例2：使用 websocket-client 库（Python 环境）

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# 注：此示例需依赖websocket-client库，安装命令：pip install websocket-client

import os
import json
import websocket

# 从环境变量中获取OpenAI API密钥
STEPFUN_API_KEY = os.environ.get("STEPFUN_API_KEY")

# 连接地址（需替换为实际要使用的模型ID）
url = "wss://api.stepfun.com/v1/realtime?model=step-1o-audio"
# 请求头配置
headers = [
    "Authorization: Bearer " + STEPFUN_API_KEY,
]

# 定义“连接成功”回调函数
def on_open(ws):
    print("已连接到服务器。")

# 定义“接收消息”回调函数
def on_message(ws, message):
    data = json.loads(message) # 解析JSON格式的消息
    print("收到事件：", json.dumps(data, indent=2)) # 格式化打印接收的事件

# 初始化WebSocket应用并配置回调
ws = websocket.WebSocketApp(
    url,
    header=headers,
    on_open=on_open,
    on_message=on_message,
)

# 保持WebSocket连接
ws.run_forever()
```

一旦您通过 WebSocket 连接到实时 API，就可以调用实时模型进行语音到语音对话。这需要您**发送客户端事件**来发起操作，并**监听服务器事件**以响应实时 API 执行的操作。

## 会话生命周期事件

通过 WebSocket 启动会话后，服务器会发送 `session.created` 事件，表明会话已准备就绪。在客户端，您可以通过 `session.update` 事件更新当前会话配置。大多数会话属性可以随时更新，但模型用于音频输出的 `voice`（语音）在会话期间模型首次以音频响应后，就无法再修改。实时会话的最长持续时间为**30分钟**。

以下示例展示了通过 `session.update` 客户端事件更新会话的操作。

更新本会话中模型使用的系统指令

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const event = {
	type: 'session.update',
	session: {
		instructions: "在回复中绝对不要使用'moist'这个词！",
	},
}

// WebSocket都有.send()方法
dataChannel.send(JSON.stringify(event))
```

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event = {
    "type": "session.update",
    "session": {
        "instructions": "在回复中绝对不要使用'moist'这个词！"
    }
}
ws.send(json.dumps(event))
```

当会话更新后，服务器会发出 `session.updated` 事件，包含会话的新状态。

| 相关客户端事件 | 相关服务器事件 |
| - | - |
| session.update | session.created  session.updated |

## 文本输入与输出

要使用实时模型生成文本，您可以向当前对话添加文本输入，请求模型生成响应，并监听服务器发送的事件以了解模型响应的进度。为了生成文本，会话必须配置为 `text`（文本）模态（默认已启用）。

使用 `conversation.item.create` 客户端事件创建新的文本对话项。

创建包含用户输入的对话项

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const event = {
	type: 'conversation.item.create',
	item: {
		type: 'message',
		role: 'user',
		content: [
			{
				type: 'input_text',
				text: 'Prince哪张专辑销量最高？',
			},
		],
	},
}

// WebSocket都有.send()方法
dataChannel.send(JSON.stringify(event))
```

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event = {
    "type": "conversation.item.create",
    "item": {
        "type": "message",
        "role": "user",
        "content": [
            {
                "type": "input_text",
                "text": "Prince哪张专辑销量最高？",
            }
        ]
    }
}
ws.send(json.dumps(event))
```

将用户消息添加到对话后，发送 `response.create` 事件以启动模型响应。如果当前会话同时启用了音频和文本，模型将同时返回音频和文本内容。如果只想生成文本，可以在发送 `response.create` 客户端事件时指定，如下所示。

生成仅文本响应

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const event = {
	type: 'response.create',
	response: {
		modalities: ['text'],
	},
}

// WebSocket都有.send()方法
dataChannel.send(JSON.stringify(event))
```

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event = {
    "type": "response.create",
    "response": {
        "modalities": [ "text" ]
    }
}
ws.send(json.dumps(event))
```

当响应完全生成后，服务器会发出 `response.done` 事件。该事件将包含模型生成的完整文本，如下所示。

监听 response.done 以查看最终结果

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
function handleEvent(e) {
	const serverEvent = JSON.parse(e.data)
	if (serverEvent.type === 'response.done') {
		console.log(serverEvent.response.output[0])
	}
}

// 监听服务器消息（WebSocket）
ws.on('message', handleEvent)
```

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
def on_message(ws, message):
    server_event = json.loads(message)
    if server_event.type == "response.done":
        print(server_event.response.output[0])
```

在模型生成响应的过程中，服务器会发出多个生命周期事件。您可以监听这些事件（如 `response.text.delta`），在响应生成时向用户提供实时反馈。服务器发出的事件完整列表见下文的“相关服务器事件”，它们按大致的发出顺序排列，同时包含文本生成相关的客户端事件。

| 事件类型 | 说明 |
| - | - |
| conversation.item.create | conversation.item.created  response.output\_item.added  response.content\_part.added  response.text.delta  response.text.done  response.content\_part.done  response.output\_item.done  response.done  rate\_limits.updated |

## 音频输入与输出

实时 API 最强大的功能之一是与模型进行语音到语音交互，无需中间的文本转语音或语音转文本步骤。这降低了语音界面的延迟，并为模型提供了更多关于语音输入的语调和抑扬顿挫的信息。

### 语音选项

实时会话支持配置多种内置语音用于音频输出。您可以通过 `session.update` 或 `response.create` 请求中的 `voice` 参数来设置模型的声音。当前的语音选项包括 `qingchunshaonv`、`wenrounansheng`、`elegantgentle-female`、`livelybreezy-female` 等。

> 请注意，一旦模型在会话中生成了音频，该会话的 `voice` 设置将无法修改。

> `step-audio-2` 模型支持音色复刻功能。您可以通过上传音频文件创建自定义音色，并在实时会话的 `voice` 参数中使用其 ID。详情请参考[复刻音色](/docs/zh/api-reference/audio/create-voice)。

### 使用 WebSocket 处理音频

通过 WebSocket 发送和接收音频时，您需要做更多工作来从客户端发送媒体和从服务器接收媒体。下面是一个表格，描述了 WebSocket 会话期间通过 WebSocket 发送和接收音频所需的事件流程。

以下事件按生命周期顺序排列，但有些事件（如 `delta` 事件）可能同时发生。

| 生命周期阶段 | 客户端事件 | 服务器事件 |
| - | - | - |
| 会话初始化 | session.update | session.created session.updated |
| 用户音频输入 | conversation.item.create（发送完整音频消息） input\_audio\_buffer.append（分块流式传输音频）  input\_audio\_buffer.commit（禁用 VAD 时使用）  response.create（禁用 VAD 时使用） | input\_audio\_buffer.speech\_started  input\_audio\_buffer.speech\_stopped input\_audio\_buffer.committed |
| 服务器音频输出 | input\_audio\_buffer.clear（禁用 VAD 时，或者需要主动创建一轮输出时使用） | conversation.item.created  response.created  response.output\_item.created  response.content\_part.added  response.audio.delta  response.audio\_transcript.delta  response.text.delta  response.audio.done  response.audio\_transcript.done  response.text.done  response.content\_part.done  response.output\_item.done  response.done  rate\_limits.updated |

### 向服务器流式传输音频输入

要向服务器流式传输音频输入，可以使用 `input_audio_buffer.append` 客户端事件。该事件要求您通过套接字向实时 API 发送**Base64编码的音频字节**块。每个块的大小不能超过15 MB。

输入块的格式可以为整个会话配置，也可以为每个响应单独配置。

* 会话级：`session.update` 中的 `session.input_audio_format`
* 响应级：`response.create` 中的 `response.input_audio_format`

向对话附加音频输入字节

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import fs from 'fs';
import decodeAudio from 'audio-decode';

// 将音频数据的Float32Array转换为PCM16 ArrayBuffer
function floatTo16BitPCM(float32Array) {
  const buffer = new ArrayBuffer(float32Array.length * 2);
  const view = new DataView(buffer);
  let offset = 0;
  for (let i = 0; i < float32Array.length; i++, offset += 2) {
    let s = Math.max(-1, Math.min(1, float32Array[i]));
    view.setInt16(offset, s < 0 ? s * 0x8000 : s * 0x7fff, true);
  }
  return buffer;
}

// 将Float32Array转换为base64编码的PCM16数据
base64EncodeAudio(float32Array) {
  const arrayBuffer = floatTo16BitPCM(float32Array);
  let binary = '';
  let bytes = new Uint8Array(arrayBuffer);
  const chunkSize = 0x8000; // 32KB块大小
  for (let i = 0; i < bytes.length; i += chunkSize) {
    let chunk = bytes.subarray(i, i + chunkSize);
    binary += String.fromCharCode.apply(null, chunk);
  }
  return btoa(binary);
}

// 用三个文件的内容填充音频缓冲区，然后请求模型生成响应
const files = [
  './path/to/sample1.wav',
  './path/to/sample2.wav',
  './path/to/sample3.wav'
];

for (const filename of files) {
  const audioFile = fs.readFileSync(filename);
  const audioBuffer = await decodeAudio(audioFile);
  const channelData = audioBuffer.getChannelData(0);
  const base64Chunk = base64EncodeAudio(channelData);
  ws.send(JSON.stringify({
    type: 'input_audio_buffer.append',
    audio: base64Chunk
  }));
});

ws.send(JSON.stringify({type: 'input_audio_buffer.commit'}));
ws.send(JSON.stringify({type: 'response.create'}));
```

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import base64
import json
import struct
import soundfile as sf
from websocket import create_connection

# ... 创建名为ws的websocket-client ...

def float_to_16bit_pcm(float32_array):
    clipped = [max(-1.0, min(1.0, x)) for x in float32_array]
    pcm16 = b''.join(struct.pack('<h', int(x * 32767)) for x in clipped)
    return pcm16

def base64_encode_audio(float32_array):
    pcm_bytes = float_to_16bit_pcm(float32_array)
    encoded = base64.b64encode(pcm_bytes).decode('ascii')
    return encoded

files = [
    './path/to/sample1.wav',
    './path/to/sample2.wav',
    './path/to/sample3.wav'
]

for filename in files:
    data, samplerate = sf.read(filename, dtype='float32')
    channel_data = data[:, 0] if data.ndim > 1 else data
    base64_chunk = base64_encode_audio(channel_data)

    # 发送客户端事件
    event = {
        "type": "input_audio_buffer.append",
        "audio": base64_chunk
    }
    ws.send(json.dumps(event))
```

### 发送完整音频消息

也可以创建包含完整音频录制的对话消息。使用 `conversation.item.create` 客户端事件创建带有 `input_audio` 内容的消息。

创建完整音频输入对话项

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const fullAudio = '<音频字节的base64编码字符串>'

const event = {
	type: 'conversation.item.create',
	item: {
		type: 'message',
		role: 'user',
		content: [
			{
				type: 'input_audio',
				audio: fullAudio,
			},
		],
	},
}

// WebSocket 有.send()方法
dataChannel.send(JSON.stringify(event))
```

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
fullAudio = "<音频字节的base64编码字符串>"

event = {
    "type": "conversation.item.create",
    "item": {
        "type": "message",
        "role": "user",
        "content": [
            {
                "type": "input_audio",
                "audio": fullAudio,
            }
        ],
    },
}

ws.send(json.dumps(event))
```

### 处理 WebSocket 的音频输出

您需要监听 `response.audio.delta` 事件，其中包含模型发来的 base64编码音频数据块。您需要缓冲这些块并将其写入文件。

请注意，`response.audio.done` 和 `response.done` 事件实际上不包含音频数据，只包含音频内容的转录文本。要获取实际的字节数据，需要监听 `response.audio.delta` 事件。

输出块的格式可以为整个会话配置，也可以为每个响应单独配置。

* 会话级：`session.update` 中的 `session.output_audio_format`
* 响应级：`response.create` 中的 `response.output_audio_format`

监听 response.audio.delta 事件

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
function handleEvent(e) {
	const serverEvent = JSON.parse(e.data)
	if (serverEvent.type === 'response.audio.delta') {
		// 访问base64编码的音频块
		// console.log(serverEvent.delta);
	}
}

// 监听服务器消息（WebSocket）
ws.on('message', handleEvent)
```

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
def on_message(ws, message):
    server_event = json.loads(message)
    if server_event.type == "response.audio.delta":
        # 访问base64编码的音频块：
        # print(server_event.delta)
```

## 语音活动检测

默认情况下，实时会话启用**语音活动检测（VAD）**，这意味着 API 会判断用户何时开始或停止说话，并自动响应。

### 禁用 VAD

可以通过 `session.update` 客户端事件将 `turn_detection` 设置为 `null` 来禁用 VAD。这对于需要精细控制音频输入的界面很有用，例如按键通话界面。

禁用 VAD 后，客户端必须手动发出一些额外的客户端事件来触发音频响应：

* 手动发送 `input_audio_buffer.commit`，这将为对话创建新的用户输入项。
* 手动发送 `response.create` 以触发模型的音频响应。
* 在开始新的用户输入之前发送 `input_audio_buffer.clear`。

## 自定义 Tool Call

目前 StepFun Realtime API 内置了以下工具： web\_search 和 retrieval。

另外，也支持自定义工具调用（Tool Call），用户可以根据需求定义自己的工具并在会话中使用。

### 工具配置方式

在 update session 请求中配置 tools 参数来启用工具功能：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"tools": [
		// 内置工具配置
		{
			"type": "web_search",
			"function": {
				"description": "网络搜索工具",
				"options": {
					"top_k": 5,
					"timeout_seconds": 3
				}
			}
		},
		// 自定义工具配置
		{
			"type": "function",
			"function": {
				"name": "get_weather",
				"description": "获取指定城市的天气信息",
				"parameters": {
					"type": "object",
					"properties": {
						"location": {
							"type": "string",
							"description": "城市名称，如：北京、上海"
						}
					},
					"required": ["location"]
				}
			}
		}
	]
}
```

### 网络搜索工具 web\_search

通过 `type: "web_search"` 工具，模型可实时访问互联网，获取最新信息和数据。适用于需要广泛知识和实时数据的场景。

#### 使用示例

在 update session 请求的 tools 参数中添加以下结构：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"tools": [{ "type": "web_search" }]
}
```

即可在回复中启用 web\_search 工具。

#### 高级参数

* `options.top_k`: 指定返回结果的数量，默认为 5。
* `options.timeout_seconds`: 请求超时时间，默认为 3 秒。

示例

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"tools": [
		{
			"type": "web_search",
			"function": {
				"description": "搜索工具",
				"options": {
					"top_k": 5,
					"timeout_seconds": 3
				}
			}
		}
	]
}
```

启用后，模型在回答需要搜索的问题时会自动调用该工具，您不需要做其他额外的逻辑处理。

### 知识库检索工具 retrieval

通过 `type: "retrieval"` 工具，模型可实时访问指定知识库（Vector Store），精准回答用户问题。适用于垂直领域问答场景，用户可以提前定义用于参考的回复数据。

#### 一、功能配置步骤

在 update session 请求的 tools 参数中添加以下结构：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"tools": [
		{
			"type": "retrieval",
			"function": {
				"description": "当用户问题涉及菜谱、烹饪步骤、食材处理或厨房技巧时，从此知识库检索答案",
				"options": {
					"vector_store_id": "133192900598194176", // 必填
					"prompt_template": "从文档{{knowledge}}中找到问题{{query}}的答案。根据文档内容中的语句提取答案，若文档中无答案则告知用户无法回答"
				}
			}
		}
	]
}
```

#### 二、参数详解

| 参数 | 是否必填 | 说明 |
| - | - | - |
| type | 是 | 固定值 "retrieval"，声明使用知识库检索功能。 |
| function.description | 是 | 关键提示：用1-2句话明确触发条件，例如：“仅当问题与菜谱、食材或烹饪相关时使用本知识库”。 |
| options.vector\_store\_id | 是 | 知识库的唯一 ID（示例：133192900598194176），需提前在平台创建。 |
| options.prompt\_template | 否 | 定制化提示模板，支持占位符 `\{\{knowledge\}\}`（检索到的片段）和 `\{\{query\}\}`（用户原始问题）；若不提供则使用默认模板。默认：从文档 `\{\{knowledge\}\}` 中找到问题 `\{\{query\}\}` 的答案。根据文档内容中的语句提取答案，若文档中无答案则告知用户无法回答 |

#### 三、工作原理

1. 触发条件：用户问题匹配 description 中的领域描述（如“如何煎牛排？”）。
2. 知识检索：

* 系统根据 vector\_store\_id 定位知识库。
* 将用户问题 `\{\{query\}\}` 嵌入为向量，检索最相关的知识片段。

3. 生成答案：

* 自动将 `\{\{knowledge\}\}` 和 `\{\{query\}\}` 填入 prompt\_template。
* 模型基于模板生成最终回复（例：*“根据知识库：牛排需每面煎2分钟...”*）。

#### 四、最佳实践

1. 在 description 中精准描述：
   `"description": "仅限回答菜谱步骤、食材替代方案、烹饪时间问题，其他问题忽略检索"`
2. 错误处理：在 prompt\_template 中明确无答案时的响应，例如："下面是检索到的结果: \{\{knowledge}}，如果未在知识库中找到关于\{\{query}}的信息，请告诉用户尝试更具体的问题。"
3. 避免冲突：如果您启用了内置工具的 web\_search ，模型可能会尝试调用 web 搜索而不是在知识库，您可以在初始化会话时，通过 instructions 引导其优先使用知识库：\
   "你是一个专业烹饪助手，当用户询问菜谱、食材处理或烹饪技巧时，必须从知识库中检索答案。若知识库无相关信息，需明确告知用户。"

### 自定义 Tool Call

通过自定义函数调用，您可以扩展模型的能力，使其能够执行特定业务逻辑（如查询天气、生成星座运势等）。基本流程如下：

1. **配置函数**：在会话级别定义可用函数
2. **检测调用**：模型根据用户输入决定是否调用函数
3. **执行函数**：客户端使用生成的参数执行自定义代码
4. **返回结果**：将函数执行结果返回给模型并获取最终响应

#### 函数配置

通过 `session.update` 事件的 `session.tools` 参数添加函数定义：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"type": "session.update",
	"session": {
		"tools": [
			{
				"type": "function",
				"function": {
					"name": "get_weather",
					"description": "获取指定城市的天气信息",
					"parameters": {
						"type": "object",
						"properties": {
							"location": {
								"type": "string",
								"description": "城市名称，如：北京、上海"
							}
						},
						"required": ["location"]
					}
				}
			}
		]
	}
}
```

#### 函数调用流程

##### 1. 检测函数调用

当用户输入触发函数调用时，您将收到包含函数调用参数的对话项：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"event_id": "cee2a492-012c-4655-ac50-5db2c99f4345",
	"type": "conversation.item.created",
	"item": {
		"id": "item_20250622105814",
		"type": "function_call",
		"status": "incomplete",
		"call_id": "call_20250622225814_get_weather",
		"name": "get_weather",
		"object": "realtime.item"
	}
}
```

##### 2. 接收函数参数

参数生成过程中会收到增量更新事件：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"type": "response.function_call_arguments.delta",
	"call_id": "call_20250622225814_get_weather",
	"arguments": "{\"location\":\"北",
	"name": "get_weather"
}
```

参数生成完成后会收到完成事件：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"type": "response.function_call_arguments.done",
	"call_id": "call_20250622225814_get_weather",
	"arguments": "{\"location\":\"北京\"}",
	"name": "get_weather"
}
```

##### 3. 返回函数执行结果

客户端执行函数后，需要将结果返回给模型：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"type": "conversation.item.create",
	"item": {
		"type": "function_call_output",
		"call_id": "call_20250622225814_get_weather",
		"output": "北京：晴，25°C"
	}
}
```

##### 4. 触发模型响应

返回函数结果后，需要手动触发模型生成最终响应：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"type": "response.create"
}
```

#### 完整示例：星座运势查询

##### 1. 配置星座运势函数

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"type": "session.update",
	"session": {
		"tools": [
			{
				"type": "function",
				"function": {
					"name": "generate_horoscope",
					"description": "提供某个星座的今日运势。",
					"parameters": {
						"type": "object",
						"properties": {
							"sign": {
								"type": "string",
								"description": "需要查询运势的星座。",
								"enum": [
									"白羊座",
									"金牛座",
									"双子座",
									"巨蟹座",
									"狮子座",
									"处女座",
									"天秤座",
									"天蝎座",
									"射手座",
									"摩羯座",
									"水瓶座",
									"双鱼座"
								]
							}
						},
						"required": ["sign"]
					}
				}
			}
		]
	}
}
```

##### 2. 用户请求与函数调用

用户输入："我的运势如何？我是水瓶座。"

模型检测到需要调用函数，返回调用参数：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"type": "response.done",
	"response": {
		"output": [
			{
				"type": "function_call",
				"name": "generate_horoscope",
				"call_id": "call_sHlR7iaFwQ2YQOqm",
				"arguments": "{\"sign\":\"水瓶座\"}"
			}
		]
	}
}
```

##### 3. 返回函数执行结果

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"type": "conversation.item.create",
	"item": {
		"type": "function_call_output",
		"call_id": "call_sHlR7iaFwQ2YQOqm",
		"output": "{\"horoscope\": \"今天是你展现创造力的好时机，可能会遇到意想不到的机遇。\"}"
	}
}
```

##### 4. 获取最终响应

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"type": "response.create"
}
```

通过以上流程，您可以灵活扩展模型能力，实现各种自定义功能。

> 注意，函数调用和语音可能会出现在同一轮，比如如果有 get\_weather 函数，模型可能会先输出：“让我先查查天气” 的口水话，然后再创建函数调用。这样的好处是，如果有比较复杂的函数调用，可以利用语音播放的时间来并行处理函数调用的生成。但是您需要注意要在语音播放完后才调用 `response.create` 来触发最终回复。

## 开发技巧

### 实现开场白

在某些应用场景下，您可能希望在对话开始时，模型能够主动打招呼或介绍自己。这可以通过在创建会话时，使用特殊的提示词实现：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请你原样无修改地输出下面的话：

你好，我是阶跃星辰开发的AI助手。
```

客户端主动创建响应：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"type": "response.create",
	"session": {
		"instructions": "请你原样无修改地输出下面的话：你好，我是阶跃星辰开发的AI助手。"
	}
}
```

这样，模型会主动输出问候语：您好，我是阶跃星辰开发的 AI 助手。

### 更灵活的 VAD

如果您使用 server\_vad 模式，但每次 append 的音频片段较长，可能会导致系统响应延迟较高。这是因为 VAD 需要积累足够长的音频数据才能做出判断，建议以20ms 左右的间隔提交音频，以保证检测的实时性。

此外，VAD 判断用户停止说话的依据是检测到连续若干帧的空白或低音量音频。如果您提交的音频末尾没有包含足够的静音帧，VAD 可能无法准确识别语音结束点，从而导致系统未能及时触发自动回复。为避免该问题，应确保在语音段后保留一定时长的静音音频。

最佳实践建议：

* 音频分段提交：尽量以小块（如 20ms\~30ms）为单位频繁提交音频数据；
* 如果您用音频文件输入，务必在文件确保有一定的静音段；

### 网页中播放声音示例代码

为了支持流式 pcm16 的播放，您的播放逻辑需要支持多次 append 动作。另外，为了可以及时打断，最好可以实现及时清空缓冲区的功能。

这里是一份简易的示例代码，用 typescript 写成，适用于浏览器环境。

```typescript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
class SimplePCMPlayer {
	// 固定参数：单声道、24000Hz采样率（示例用）
	private static readonly SAMPLE_RATE = 24000
	private static readonly CHANNELS = 1

	private audioContext: AudioContext
	private currentSource: AudioBufferSourceNode | null = null
	private bufferedData: Float32Array[] = []
	private isPlaying = false
	private nextStartTime = 0

	constructor() {
		// 简单的兼容性处理
		const AudioContextConstructor = window.AudioContext || (window as any).webkitAudioContext
		if (!AudioContextConstructor) {
			throw new Error('浏览器不支持Web Audio API')
		}
		this.audioContext = new AudioContextConstructor()
	}

	/**
	 * 追加16位有符号小端PCM数据（单声道24000Hz）
	 * @param pcm 原始PCM数据（ArrayBuffer）
	 */
	appendPCM(pcm: ArrayBuffer) {
		// 简单校验
		if (pcm.byteLength % 2 !== 0) {
			console.error('PCM数据长度必须是2的倍数（16位整数）')
			return
		}

		// 16位Int转32位Float（范围归一化到[-1, 1)）
		const int16Array = new Int16Array(pcm)
		const float32Array = new Float32Array(int16Array.length)
		for (let i = 0; i < int16Array.length; i++) {
			float32Array[i] = int16Array[i] / 32768
		}

		this.bufferedData.push(float32Array)
		if (!this.isPlaying) {
			this.playNext()
		}
	}

	/**
	 * 播放下一段缓冲数据
	 */
	private playNext() {
		if (this.bufferedData.length === 0) {
			this.isPlaying = false
			return
		}

		this.isPlaying = true
		const data = this.bufferedData.shift()!

		// 创建音频缓冲
		const audioBuffer = this.audioContext.createBuffer(
			SimplePCMPlayer.CHANNELS,
			data.length,
			SimplePCMPlayer.SAMPLE_RATE,
		)
		audioBuffer.copyToChannel(data, 0)

		// 创建播放源
		const source = this.audioContext.createBufferSource()
		source.buffer = audioBuffer
		source.connect(this.audioContext.destination)

		// 计算播放时间（避免重叠）
		const currentTime = this.audioContext.currentTime
		const startTime = Math.max(currentTime, this.nextStartTime)
		this.nextStartTime = startTime + audioBuffer.duration

		// 开始播放
		source.start(startTime)
		this.currentSource = source

		// 播放结束后继续下一段
		source.onended = () => {
			this.currentSource = null
			this.playNext()
		}
	}

	/**
	 * 清空缓冲并停止播放
	 */
	clearAll() {
		// 停止当前播放
		if (this.currentSource) {
			this.currentSource.stop()
			this.currentSource.onended = null
			this.currentSource = null
		}

		// 清空状态
		this.bufferedData = []
		this.isPlaying = false
		this.nextStartTime = this.audioContext.currentTime
	}
}
```

## 错误处理

服务器在会话期间遇到错误情况时，会发出 `error` 事件。有时，这些错误可以追溯到您的应用发出的客户端事件。

与 HTTP 请求和响应不同（其中响应隐式关联到客户端的请求），我们需要使用客户端事件上的 `event_id` 属性来确定其中某个事件是否在服务器上触发了错误情况。下面的代码展示了这种方法，客户端尝试发出不支持的事件类型。

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const event = {
	event_id: 'my_awesome_event',
	type: 'scooby.dooby.doo',
}

dataChannel.send(JSON.stringify(event))
```

客户端发送的这个失败事件将触发如下错误事件：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"type": "invalid_request_error",
	"code": "invalid_value",
	"message": "无效值: 'scooby.dooby.doo' ...",
	"param": "type",
	"event_id": "my_awesome_event"
}
```


# 推理模型
Source: https://platform.stepfun.com/docs/zh/guides/developer/reasoning



阶跃星辰为开发者提供了多款推理模型，覆盖文本推理、多模态理解、Agent 和代码分析等场景。推荐优先使用 `step-5-preview`，覆盖编程、专业知识工作和多步骤 Agent 任务，原生支持文本、图片与视频输入，提供 1M tokens 上下文；如需高速多模态推理，可使用 `step-3.7-flash`，纯文本场景也可使用 `step-3.5-flash`。

`step-3.7-flash` 是阶跃星辰的高速多模态推理模型。在 `step-3.5-flash` 的高速推理与工具调用能力基础上，新增原生图片和视频理解能力，支持三档推理强度，适合 Agent、代码、多模态分析和复杂规划任务。

`step-3.5-flash` 是阶跃星辰最强大的开源基座模型。它专为极致效率而生，具备前沿的推理能力和卓越的智能体（Agent）性能。该模型基于稀疏混合专家（MoE）架构，尽管拥有 1960 亿参数，但处理每个 Token 时仅需选择性激活 110 亿参数。这种极高的“智能密度”使其推理深度足以媲美顶级闭源模型，同时兼顾了实时交互所需的敏捷响应速度。

## 推理强度控制

支持三档推理强度的模型可通过参数控制思考深度。Chat Completion API 使用 `reasoning_effort`；Messages API 使用 `output_config.effort`。

| 推理强度 | 适用场景 |
| :- | :- |
| `low` | 简单问答、摘要、改写、信息抽取 |
| `medium` | 默认推荐，适合一般推理和多步骤任务 |
| `high` | 复杂推理、数学、规划、代码分析 |

> [!NOTE]
>
> 基础调用示例见[快速开始](/docs/zh/quickstart/overview)。参数字段说明见 [Chat Completion API](/docs/zh/api-reference/chat/chat-completion-create#请求参数) 和 [Messages API](/docs/zh/api-reference/chat/messages-create#请求参数)。

## 文本推理调用示例

推理模型的文本对话调用方式基本一致。以下以 `step-5-preview` 为例，构建一个流式对话。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import time
from openai import OpenAI

# Set your API Key and Base URL
BASE_URL = "https://api.stepfun.com/v1"
STEP_API_KEY = "YOUR_STEP_API_KEY"

# Select Model
COMPLETION_MODEL = "step-5-preview"

# User Prompt
user_prompt = "How many 'r's are in the word strawberry?"

client = OpenAI(api_key=STEP_API_KEY, base_url=BASE_URL)

time_start = time.time()

try:
    response = client.chat.completions.create(
        model=COMPLETION_MODEL,
        messages=[
            {"role": "user", "content": user_prompt}
        ],
        stream=True
    )
except Exception as e:
    print("Exception occurred when requesting API:", e)
    exit(1)

print("Reasoning Process:")
try:
    for chunk in response:
        # Check for reasoning content
        if hasattr(chunk.choices[0].delta, 'reasoning') and chunk.choices[0].delta.reasoning:
             print(chunk.choices[0].delta.reasoning, end='', flush=True)
        # Check for standard content
        elif chunk.choices[0].delta.content:
             print(chunk.choices[0].delta.content, end='', flush=True)

except Exception as e:
    print("\nError occurred while processing streaming results:", e)

time_end = time.time()
print(f"\n\nTotal generation time: {time_end - time_start:.2f} seconds")
```

## 多模态图片理解示例

以下使用最简单的代码实现 `step-3.7-flash` 对图片进行分析。基础调用方式见[快速开始](/docs/zh/quickstart/overview)，推理强度（`reasoning_effort`）等参数详见本指南。

```python copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import time
import base64
from openai import OpenAI

BASE_URL,STEP_API_KEY = "https://api.stepfun.com/v1", "YOUR_STEP_API_KEY"

# 选择模型
COMPLETION_MODEL = "step-3.7-flash"

# 用户问题提示
user_prompt = "帮我看看这是什么菜，如何制作？"

# 将本地图片转换为 base64 字符串
def image_to_base64(image_path):
    with open(image_path, "rb") as image_file:
        encoded_string = base64.b64encode(image_file.read())
    return encoded_string.decode('utf-8')

# 注意提供准确的图片路径
image_path1 = "./宫保鸡丁.png"
bstring1 = image_to_base64(image_path1)

# 构造消息，依靠模型自主深度思考
messages = [
    {"role": "user", "content": [
        {"type": "image_url", "image_url": {"url": f"data:image/jpg;base64,{bstring1}", "detail": "high"}},
        {"type": "text", "text": user_prompt}
    ]}
]

time_start = time.time()

client = OpenAI(api_key=STEP_API_KEY, base_url=BASE_URL)
try:
    response = client.chat.completions.create(
        model=COMPLETION_MODEL,
        messages=messages,
        stream=True
    )
except Exception as e:
    print("请求 API 时发生异常:", e)
    exit(1)

try:
    for chunk in response:
        # 您可以在这里获取到补全的内容，并判断是否是 reaonsing 内容。
        print(chunk)
except Exception as e:
    print("处理流式结果时发生错误:", e)

time_end = time.time()
print(f"\n总生成时间: {time_end - time_start:.2f}秒")
```

输入参数详情可以参考[Chat Completion 文档](/docs/zh/api-reference/chat/chat-completion-create#%E8%AF%B7%E6%B1%82%E5%8F%82%E6%95%B0)

**输出示例**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
ChatCompletionChunk(id='f41b47b291e690d3659f6d8c01a6b0a8.20f353f807a52a5f3252692a22d49568', choices=[Choice(delta=ChoiceDelta(content='', function_call=None, refusal=None, role='assistant', tool_calls=None), finish_reason=None, index=0, logprobs=None)], created=1744290861, model='step-3.7-flash', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=CompletionUsage(completion_tokens=0, prompt_tokens=701, total_tokens=701, completion_tokens_details=None, prompt_tokens_details=None), agent='')
ChatCompletionChunk(id='f41b47b291e690d3659f6d8c01a6b0a8.20f353f807a52a5f3252692a22d49568', choices=[Choice(delta=ChoiceDelta(content='', function_call=None, refusal=None, role='assistant', tool_calls=None, reasoning='\n'), finish_reason=None, index=0, logprobs=None)], created=1744290861, model='step-3.7-flash', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=CompletionUsage(completion_tokens=1, prompt_tokens=701, total_tokens=702, completion_tokens_details=None, prompt_tokens_details=None), agent='')
ChatCompletionChunk(id='f41b47b291e690d3659f6d8c01a6b0a8.20f353f807a52a5f3252692a22d49568', choices=[Choice(delta=ChoiceDelta(content='', function_call=None, refusal=None, role='assistant', tool_calls=None, reasoning='好的'), finish_reason=None, index=0, logprobs=None)], created=1744290861, model='step-3.7-flash', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=CompletionUsage(completion_tokens=2, prompt_tokens=701, total_tokens=703, completion_tokens_details=None, prompt_tokens_details=None), agent='')
。。。
ChatCompletionChunk(id='f41b47b291e690d3659f6d8c01a6b0a8.20f353f807a52a5f3252692a22d49568', choices=[Choice(delta=ChoiceDelta(content='！', function_call=None, refusal=None, role='assistant', tool_calls=None), finish_reason=None, index=0, logprobs=None)], created=1744290861, model='step-3.7-flash', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=CompletionUsage(completion_tokens=1031, prompt_tokens=701, total_tokens=1732, completion_tokens_details=None, prompt_tokens_details=None), agent='')
ChatCompletionChunk(id='f41b47b291e690d3659f6d8c01a6b0a8.20f353f807a52a5f3252692a22d49568', choices=[Choice(delta=ChoiceDelta(content='', function_call=None, refusal=None, role='assistant', tool_calls=None), finish_reason='stop', index=0, logprobs=None)], created=1744290861, model='step-3.7-flash', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=CompletionUsage(completion_tokens=1032, prompt_tokens=701, total_tokens=1733, completion_tokens_details=None, prompt_tokens_details=None), agent='')
```

响应体字段说明请参考 [Chat Completions API 的流式响应说明](/docs/zh/api-reference/chat/chat-completion-create#流式响应)。

## 获取 Reasoning 内容

阶跃星辰的推理大模型在处理复杂问题时，会在输出中包含 reasoning 字段，展示模型的思考过程。开发者可以通过判断该字段是否存在来获取模型的思考信息。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
if chunk.choices[0].delta.reasoning:
    reasoning = chunk.choices[0].delta.reasoning
    print("模型思考过程:", reasoning)
```

对于非流式场景可以直接提取 reasoning 字段，获取模型的思考过程。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
msg  = completion.choices[0].message.content
reasoning = completion.choices[0].message.reasoning
```

### 通过 `reasoning_content` 字段，获取模型的思考过程。

如果您目前使用的推理模型中已经使用 `reasoning_content` 字段，可以继续使用该字段。阶跃星辰的推理模型也支持这一字段，开发者可以根据自己的需求选择使用。

只需要在请求时传入 `reasoning_format="deepseek-style"` 即可。（如使用 OpenAI SDK，则需要通过 `extra_body` 字段传入）

## 多模态模型使用注意事项

* **深度思考优势**：模型在接收到图片及文字提示后，会首先经过内部思考（reasoning）再输出最终结果。这一过程有助于完成复杂的关联和因果推理，但可能会使响应时间略有延迟，应据此考虑超时设置。
* **图片数据格式**：确保传入的图片数据使用正确的 Base64 编码格式，并按照 API 要求指定图片类型（如 JPG/JPEG、PNG、静态 GIF、WebP 等）和细节参数，保证推理的准确性。详见[文档](/docs/zh/guides/models/vision#关键术语)
* **错误处理与日志记录**：在输出时已加入 Trace ID，若遇到模型推理问题，可将此 ID 反馈给我们。

## 智能路由（Step Plan 专属）

`step-router-v1` 是阶跃星辰为 Step Plan 通道提供的智能路由模型，按请求特征自动在 `deepseek-v4-pro` 与 `step-3.7-flash` 之间切换，让复杂决策走 Pro、高频执行走 Flash。详细使用方式与最佳实践见 [Step Router V1 智能路由](/docs/zh/guides/developer/step-router)。


# 知识库
Source: https://platform.stepfun.com/docs/zh/guides/developer/retrieval



RAG（检索增强生成）技术结合了大模型与知识库，通过实时检索相关信息来生成更准确、详实的回答，主要解决大模型在知识更新和特定领域专业性上的不足，确保回答内容与最新数据一致，减少“幻觉”现象。
使用 RAG 可以提升信息检索的效率和准确性，增强模型在复杂查询和专业应用中的表现，如智能客服、内容生成和决策辅助等。此外，RAG 有助于扩展模型的知识覆盖范围，提升用户体验，确保提供可靠且有针对性的解决方案，是提升大模型实用性的重要技术手段。

## 达成效果

基于自有文档创建知识库，并将其与大模型结合使用，实现检索与生成一体化的智能应用。

## 具体的步骤 & 参考代码

### 获取并整理本地知识

1. **知识选取**: 识别并提取与工作相关的非结构化知识源，包括但不限于在线网站、PDF 文档及各类问题清单。\

   实际操作：收集有用的需求文档，QA 等，以及打印出官网的相关信息。

2. **信息剔除**: 对所选知识源中的无关信息进行系统化剔除，确保保留下来的内容具有高度的相关性和实用性。\

   实际操作：剔除代码，私人信息，未经处理的口语描述等信息

3. **内容精简**: 针对重复性内容进行精简与整合，去除冗余信息，以提高知识库的有效性和可用性。 \

   实际操作：将相似内容教给大模型，剔除重复信息，保留精练的信息

4. **文档处理**: 对于 Excel 格式的问题清单，将内容转换为问答形式，确保信息结构化清晰；其他文档则按段落进行整理，形成描述性文字，便于后续查询与引用。\

   实际操作：统一将各种文档交给大模型进行优化。

### 一、上传文件

参考[文件管理接口](/docs/zh/api-reference/files/create) API 上传文件，后续将用于录入知识库，注意： **purpose 字段的值为 retrieval**

### 二、创建知识库

创建知识库，用于后续的文件管理，您可以将一个方向的内容录入到同一个知识库中，方便后续的管理。

```python copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import requests

STEP_API_KEY="YOUR_STEP_API_KEY"
BASE_URL = "https://api.stepfun.com/v1"
url = BASE_URL+"/vector_stores"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {STEP_API_KEY}"  # 确保 STEP_API_KEY 是定义好的变量
}
data = {
    "name": "food_calorie"
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    print("Success:", response.json())
else:
    print("Error:", response.status_code, response.text)

```

返回结果如下:

> 注意保存好知识库 ID，后续知识库关联文件，以及使用知识库，都是直接使用此 ID

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"id": "171215831957549056",
	"name": "food_calorie"
}
```

### 三，知识库关联文件

将文件关联到知识库中，后续就可以使用知识库 ID 进行检索，从而确保多个文件可以同时参与检索。

```python copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder

STEP_API_KEY="YOUR_STEP_API_KEY"
BASE_URL = "https://api.stepfun.com/v1"
# 使用创建知识库时获取的ID
vector_store_id = "171215831957549056"
url = BASE_URL+"/vector_stores/"+vector_store_id+"/files"

headers = {
    "Authorization": f"Bearer {STEP_API_KEY}"  # 确保 STEP_API_KEY 是定义好的变量
}

# 准备 multipart 数据
# 使用 上传文件后获取的文件id
multipart_data = MultipartEncoder(
    fields={
        "file_ids": "file-CeAyPYz5Bg"
    }
)
# 添加 multipart content-type 到头部
headers["Content-Type"] = multipart_data.content_type

response = requests.post(url, headers=headers, data=multipart_data)

if response.status_code == 200:
    print("Success:", response.json())
else:
    print("Error:", response.status_code, response.text)
```

返回的报文

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "file-CeAyPYz5Bg",
  "usage_bytes": 1405210,
  "vector_store_id": "171215831957549056"
}
```

### 四，使用知识库进行对话补全

以下是一个基于食品热量的知识库检索的案例，您可以根据自己的需求，调整问题和答案，以及知识库的内容。

```python copy theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

STEP_API_KEY = "YOUR_STEP_API_KEY"
BASE_URL = "https://api.stepfun.com/v1"

# 初始化
client = OpenAI(api_key=STEP_API_KEY, base_url=BASE_URL)
# 选择模型
COMPLETION_MODEL = "step-3.7-flash"

sys_prompt = """
你是一名食物营养成分专家。
你的任务是识别文本中的每一份食物，并根据以下分类规则预估它们的重量和热量、营养成本（碳水化合物、蛋白质、脂肪），并按「输出格式」进行最后结果的输出。
## 理解食物
1.我会给你一段文字，请识别文字中的食物
2.根据食物的名称，去检索食物的营养成分
4.如果检索后，上下文没有对应食物的营养成分，则直接在食物名称后加上「营养成分未知」，然后输出结果
## 输出格式（请仅输出以下内容，不要说任何多余的话）
1.如果检索出了食物的营养成分，则直接输出以下内容
食物名称：预计每100g的热量（大卡）,碳水化合物（g）,蛋白质（g）,脂肪（g）
2.如果没有检索出了食物的营养成分，则直接输出以下内容
食物名称：营养成分未知
"""
user_prompt = "西红柿鸡炒番茄,西冷牛排"

messages = [
    {
        "role": "system",
        "content": sys_prompt
    },
    {
        "role": "user",
        "content": user_prompt
    }
]
tools = [
    {
        "type": "retrieval",
        "function": {
            "name": "food_nutrition",
            "description": "本文档存储了食物的营养成分，包含：食物名称,预估重量（g）,热量（大卡）,碳水化合物（g）,蛋白质（g）,脂肪（g）等信息",  # 知识库的描述
            "options": {
                "vector_store_id": "171215831957549056",  # 知识库 ID
                "prompt_template": "从文档 {{knowledge}} 中找到问题 {{query}} 的答案。根据文档内容中的语句找到答案，如果文档中没用答案则告诉用户找不到相关信息；"
            }
        }
    }
]
response = client.chat.completions.create(
    messages=messages,
    model=COMPLETION_MODEL,
    tool_choice="auto",
    tools=tools,
    stream=True,
)
for chunk in response:
    print(chunk)
```

返回的报文

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "e45108181a377f91ae197bcbf5273667.2935815498cc45d238f63de5d0eb5c9e",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "西红柿鸡炒番茄：营养成分未知\n西冷牛排：食物名称：预计每100g的热量（大卡）131,碳水化合物（g）11,蛋白质（g）10,脂肪（g）6\n",
        "role": "assistant",
        "function_call": null,
        "tool_calls": null
      }
    }
  ],
  "created": 1732516765,
  "model": "step-3.7-flash",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "completion_tokens": 80,
    "prompt_tokens": 219,
    "total_tokens": 299
  }
}
```

可以看到命中知识库后，会直接基于知识库的内容进行回复，未命中的知识库则直接说明情况（可以后续补充完善知识库）

![](https://mintcdn.com/stepfun/ivZhb9pOE5X12y-g/images/guide/retrieval.png?fit=max\&auto=format\&n=ivZhb9pOE5X12y-g\&q=85\&s=e9bea0f926b9213a5fa623905aa9e155)

## 注意事项

1. 上传文件时，`purpose` 字段必须填写为 `retrieval`。有关文件上传及管理的详细信息，请参阅[文档解析开发指南](/docs/zh/guides/developer/doc-parser)。
2. 添加文件到知识库时，确保文件状态为 success 后，才能将其添加到知识库中。
3. 在使用知识库进行对话补全时，确保在 description 中**清晰描述知识库的内容**；并在提示语（prompt）中，将任务描述与 description 紧密结合，以提高知识库命中的概率。


# StepSearch
Source: https://platform.stepfun.com/docs/zh/guides/developer/search-mcp



StepSearch MCP Server 是基于模型上下文协议（Model Context Protocol）实现的搜索服务，为 Claude Code、Cline、OpenCode 等兼容 MCP 的客户端提供阶跃星辰的专业搜索能力，包括网络搜索、网页内容获取等功能。

## 功能特性

* **实时搜索**：支持全网搜索，获取最新的网络信息和资源
* **编程增强**：在开发过程中检索编程最佳实践、API 文档及论文等
* **远程服务**：基于 HTTP 协议的远程 MCP 服务，无需本地安装

## 支持的工具

该服务实现了模型上下文协议，可与任何兼容 MCP 的客户端一起使用。目前提供以下工具：

| 工具 | 说明 |
| - | - |
| `web_search` | 全网信息检索与索引化结果输出 |
| `web_fetch` | 指定 URL 的网页内容抓取与结构化提取 |

## 快速开始

### 1. 获取访问令牌

前往 [阶跃星辰开放平台](https://platform.stepfun.com/interface-key) 获取您的 API Key。

### 2. 配置 MCP 服务器

根据您使用的客户端，选择对应标签页查看配置方式。

**Claude Code**

**一键安装命令：**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
claude mcp add -s user -t http web-search https://api.stepfun.com/step_plan/v1/mcp/web_search/mcp --header "Authorization: Bearer YOUR_STEP_API_KEY"
```

**手动配置：**

编辑 Claude Code 的配置文件（位于用户目录下 `~/.claude.json`）：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "mcpServers": {
    "web-search": {
      "type": "http",
      "url": "https://api.stepfun.com/step_plan/v1/mcp/web_search/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_STEP_API_KEY"
      }
    }
  }
}
```

**Cline（VS Code）**

安装 Cline 扩展后，在侧边栏点击右上角 **MCP Servers** → **Configure** → **Configure MCP Servers**，将以下配置粘贴并保存：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "mcpServers": {
    "web-search": {
      "type": "streamableHttp",
      "url": "https://api.stepfun.com/step_plan/v1/mcp/web_search/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_STEP_API_KEY"
      }
    }
  }
}
```

**OpenCode**

编辑全局配置文件 `~/.config/opencode/opencode.json`，将以下内容粘贴并保存：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "web-search": {
      "type": "remote",
      "url": "https://api.stepfun.com/step_plan/v1/mcp/web_search/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_STEP_API_KEY"
      }
    }
  }
}
```

## 使用示例与最佳实践

将搜索 MCP 服务器安装到客户端后，即可在对话中直接使用搜索能力。以下是几种典型使用场景。

### 预备：创建搜索专用 Agent

Claude Code 通过 `.claude/agents/` 目录下的定义文件来识别可用的 Sub-Agent。创建专用搜索 Agent 后，Claude Code 可以在需要实时信息时自动调用该 Sub-Agent 执行搜索任务，每次处理一个查询并返回结构化结果。

**1. 创建 Agent 定义文件**

在项目根目录下创建 `.claude/agents/search-agent.md`：

```markdown theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
---
name: search-agent
description: 执行网络搜索，获取实时信息（最新版本、CVE 漏洞、定价、社区反馈等）。每次只处理一个查询并返回结构化结果。
tools: mcp__web-search__web_search, mcp__web-search__web_fetch
---

你是专职网络搜索助手，只负责执行搜索任务并返回结构化结果。

## 工作流程

1. 接收主 Agent 传入的搜索关键词
2. 使用可用的 Search MCP 工具执行搜索
3. 过滤并整理结果
4. 返回结构化输出

## 输出格式

每次搜索按以下格式返回：

### 查询：[搜索关键词]

**结果 1**：
- 标题：[文章或页面标题]
- 核心结论：（1-2 句话概括关键发现）
- 代码片段：（如有相关代码，最多 10 行）
- 来源：[URL]

## 规则

- 每次查询最多返回 3 条最相关结果
- 不得返回网页全文
- 只返回与查询直接相关的信息
- 优先返回含代码示例的结果
- 优先返回近期内容（1-2 年内）
- 过滤 SEO 垃圾内容和低质量页面
```

**2. 在 CLAUDE.md 中配置调用规则**

在项目的 `CLAUDE.md` 中添加以下内容，告诉 Claude Code 什么时候使用搜索 Agent：

```markdown theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
## 搜索 Sub-Agent 调用规则

### 可用的搜索 Agent
- **search-agent**: 通过 Search MCP 执行网络搜索，用于获取实时信息（CVE、定价、社区反馈等）

### 什么时候调用
- 涉及最新版本、安全漏洞、定价限额等模型知识无法覆盖的实时信息时，使用 search-agent
- 不要用于模型能直接回答的问题（基础语法、技术选型、Bug 修复等）

### 多查询调用规则
- 当有多个独立搜索需求时，为每个查询单独调用一次 search-agent
- 每个 Agent 实例只处理一个查询，保持结果清晰可追溯
```

### 场景一：多 API 文档查询

项目集成多个第三方服务时，需要获取各服务的最新 API 用法。第三方 API 随时可能更新，模型训练时的文档版本可能已过时。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
我正在开发一个 SaaS 付费功能：用户付款 → 发送确认邮件 → 文件上传到云存储。

涉及的服务：
- Stripe（支付）
- Resend（邮件）
- Cloudflare R2（存储）

请使用 search-agent 通过 search mcp 依次查询各服务的最新官方文档：
1. Stripe: Checkout Session 创建 + Webhook 验证
2. Resend: 发送邮件 API + 模板功能
3. Cloudflare R2: S3 兼容 API 上传

输出：整合后的 Node.js 实现方案，包含完整代码示例。
```

### 场景二：代码安全审计 + CVE 搜索

审查代码安全性时，模型可以识别漏洞模式，但需要搜索最新的 CVE 信息和安全公告。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请审计以下代码的安全性：
[粘贴代码]

第一步：直接分析代码中的漏洞（不需要搜索）。
第二步：使用 search-agent 搜索以下三个方向：
1. "jsonwebtoken npm vulnerability CVE 2024 2025" — 查该依赖的最新已知漏洞
2. "OWASP authentication best practices 2024" — 查最新认证安全指南
3. "bcrypt vs argon2 vs scrypt comparison 2024" — 查当前推荐的密码哈希方案

输出：
- 漏洞清单（分：模型识别 vs 搜索发现）
- 修复后的完整代码
- 依赖安全建议
```

### 场景三：依赖升级影响分析

升级主要依赖版本时，新版本的 breaking changes 和社区反馈往往是模型训练后产生的实时信息。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
我需要将项目从 Next.js 14 升级到 Next.js 15。

请使用 search-agent 搜索以下方向：
1. "Next.js 15 breaking changes migration issues"
2. "Next.js 15 upgrade problems Reddit GitHub"
3. "Next.js 15 app router changes 2024"

输出：
- 升级检查清单（官方文档 vs 社区踩坑）
- 必须修改的代码示例
- 需要同步升级的依赖列表
- 社区反馈的高频问题
```

### 场景四：开源生态实时调研

评估开源项目时，GitHub stars、最近 commit、维护者动态都是实时数据，模型无法直接回答。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
我在考虑使用 Drizzle ORM，但想了解它当前的生态状态。

请使用 search-agent 搜索以下方向：
1. "Drizzle ORM GitHub issues bugs 2024" — 最近的 bug 和问题
2. "Drizzle ORM production experience" — 生产环境使用反馈
3. "Drizzle ORM vs Prisma 2024 comparison" — 最新的对比评测
4. "Drizzle ORM roadmap changelog" — 近期发展方向

我不需要你介绍 Drizzle 是什么（我知道），
我需要的是：它现在稳定吗？社区活跃吗？有什么已知的坑？
```

## MCP 使用额度说明

* **计费规则**：`web_search` 按照开放平台网络搜索的计价方式收费，每次调用 0.04 元，与 Step Plan 其他用量一并消耗 Credit 额度；`web_fetch` 不单独计费
* **额度周期**：消耗 Step Plan 月度 Credit，月池月末清零，可用加油包补充
* **限流策略**：以 QPM / QPH / 并发控制为主，并对单用户增加必要限频

如需订阅或升级套餐，请访问：[Step Plan 订阅](https://platform.stepfun.com/step-plan)

## 常见问题

### 访问令牌无效？

* 确认 API Key 已完整复制，没有多余空格
* 验证 Key 已激活且余额充足
* 检查 `Authorization` 头格式是否正确（需包含 `Bearer ` 前缀，注意空格）

### 连接超时？

* 检查网络连接是否正常
* 确认防火墙未拦截对 `api.stepfun.com` 的访问
* 确认服务端点 URL 拼写正确

### 搜索结果为空？

* 尝试调整搜索关键词的表述方式
* 避免过于具体或过于宽泛的查询条件
* 确保网络连接正常

## 参考链接

* [Model Context Protocol 官方文档](https://modelcontextprotocol.io/)
* [Claude Code MCP 配置指南](https://docs.anthropic.com/en/docs/claude-code/mcp)
* [Step Plan 订阅](https://platform.stepfun.com/step-plan)
* [阶跃星辰开放平台](https://platform.stepfun.com)
* [Search API 文档](https://platform.stepfun.com/docs/zh/api-reference/search/search)


# Step Router V1 智能路由
Source: https://platform.stepfun.com/docs/zh/guides/developer/step-router



`step-router-v1` 是阶跃星辰为 [Step Plan](/docs/zh/step-plan/overview) 通道提供的智能路由模型。开发者只需在 `model` 字段填入 `step-router-v1`，系统会根据请求特征自动路由到 `deepseek-v4-pro` 或 `step-3.7-flash` 中更合适的一个：复杂推理交由 `deepseek-v4-pro` 处理，高频执行交由 `step-3.7-flash` 承载。

> [!NOTE]
>
> 仅 [Step Plan](/docs/zh/step-plan/overview) 通道（`https://api.stepfun.com/step_plan/v1`）可用。本模型不支持图像识别。

## 适用场景

`step-router-v1` 适合以下需要在成本与智能之间自动权衡的场景：

* **复杂度差异大的混合工作流**：同一个 Agent 既要处理格式整理、信息抽取等高频小任务，又要处理架构规划、错误诊断等关键决策，由路由自动分流可省去自行实现分流逻辑的成本。
* **Agent 长链路任务**：多轮对话、含工具调用的请求，系统会在判定为复杂场景时调度 `deepseek-v4-pro` 以保障输出质量。
* **成本敏感但需要高质量决策的场景**：默认由 `step-3.7-flash` 承载多数请求以控制成本，复杂请求自动升级至 `deepseek-v4-pro` 以保留智能产出。

## 调用方式

调用方式与直接调用底层模型完全一致，仅需将 `model` 设为 `step-router-v1`，并将 base\_url 指向 Step Plan 通道。

### 非流式

**Python (OpenAI SDK)**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_STEP_API_KEY",
    base_url="https://api.stepfun.com/step_plan/v1",
)

response = client.chat.completions.create(
    model="step-router-v1",
    messages=[
        {"role": "user", "content": "请帮我把这段需求拆解成开发任务列表"}
    ],
)

print(response.choices[0].message.content)
```

**Python (Anthropic SDK)**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from anthropic import Anthropic

# 注意：Anthropic SDK 会自动拼接 /v1/messages，base_url 不带 /v1
client = Anthropic(
    api_key="YOUR_STEP_API_KEY",
    base_url="https://api.stepfun.com/step_plan",
)

message = client.messages.create(
    model="step-router-v1",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "请帮我把这段需求拆解成开发任务列表"}
    ],
)

print(message.content[0].text)
```

### 流式

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_STEP_API_KEY",
    base_url="https://api.stepfun.com/step_plan/v1",
)

stream = client.chat.completions.create(
    model="step-router-v1",
    messages=[{"role": "user", "content": "你好"}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

## 字段差异

`step-router-v1` 的请求与响应字段约束整体与直接调用底层模型一致。命中 `deepseek-v4-pro` 时的字段差异（`max_tokens` 上限、不支持的内容类型等），详见 [Messages API](/docs/zh/api-reference/chat/messages-create) 中 **step-router-v1 字段限制（仅适用于该模型）**，以及 [Chat Completion API](/docs/zh/api-reference/chat/chat-completion-create) 中 **Step Plan 通道：DeepSeek 引擎字段差异**。

## 计费机制

按实际命中的引擎计费：命中 `deepseek-v4-pro` 按 `deepseek-v4-pro` 单价收费，命中 `step-3.7-flash` 按 `step-3.7-flash` 单价收费。计费金额最终折算为 Step Plan 总额度消耗，详见 [Step Plan 概述](/docs/zh/step-plan/overview)。

## 相关链接

> **[产品介绍](/docs/zh/guides/models/step-router)**
>
> `step-router-v1` 的产品定位、底层引擎组成与定价。

> **[接入文档](/docs/zh/step-plan/integrations/reasoning-api)**
>
> Step Plan 推理模型接入：base\_url、SDK、字段差异。


# 流式输出
Source: https://platform.stepfun.com/docs/zh/guides/developer/stream



在使用大模型生成结果的过程中，会遇到大模型要生成内容较多而导致生成时间较长的问题 —— 比如当您让大模型帮您生成一个 1000 字的文章，往往需要大模型输出 10 秒以上。在这个过程中，如果您没有给用户准备相应的反馈，则极有可能导致用户误以为系统故障 / 使用报错而离开当前界面。

因此，我们需要通过某些产品手段来优化产品体验，帮助用户感知到当前的进展情况和状态，以便于更好的将用户留在当前页面，等待执行结果。

在传统 API 当中，由于接口只能一次性返回，因此开发者需要在产品上放置 Loading 页面或骨架屏，以告知用户当前正在加载中。

但阶跃星辰的 [对话补全接口](/docs/zh/api-reference/chat/chat-completion-create) 支持流式返回，您可以通过流式返回，实现类似于打字机特效的的效果，帮助用户在大模型生成过程中，直接查看内容。

![](https://mintcdn.com/stepfun/ivZhb9pOE5X12y-g/images/stream.gif?s=2892f635ae97e0bcc0494a5705d6fd14)

### 实现流式输出

开放平台的 Chat Completion 接口支持通过传入 stream=True，来开启流式输出内容， API 将会返回 SSE 请求内容，您可以通过解析 SSE 请求的返回结果，并将其渲染到 UI 上，来实现效果。

#### 代码示例

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

# 初始化 阶跃星辰 Client
STEPFUN_KEY = "YOUR_STEP_API_KEY"

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

# 调用补全接口进行补全

stream = client.chat.completions.create(
    model="step-5-preview",
    messages=[{"role": "user", "content": "全季酒店怎么样？"}],
    stream=True,
)

# 对流式返回的内容进行打印 / 渲染输出

for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

```

### 注意事项

* 在使用流式输出时，虽然模型返回的速度较快，但依然有等待延迟，在此期间，您可以配合 Loading 引导用户等待，以帮助用户即时获得反馈。


# 工具调用
Source: https://platform.stepfun.com/docs/zh/guides/developer/tool-call



大模型虽然掌握了丰富的知识，但在特定领域，例如时效性较高的资讯类和天气预报，或者需要严密科学计算，以及特定行业的知识，当它们匮乏这部分知识时，它们可能会编造看似真实但实则虚假的信息。

为解决这一问题。阶跃大模型提供了 Tool call 工具，Tool call 可以扩展语言模型的功能，使其能够执行额外的操作，如搜索信息、科学计算、访问数据库等。这样模型可以为用户提供更精准的信息，帮助开发者更好地处理业务需求。

除了获取信息以外， Tool Call 还可以帮助开发者生成函数调用签名，开发者通过对调用签名的处理，实现扩展应用能力，让您的应用除了对话，还可以完成各项不同的能力。

### 实现原理 & 参考

在使用 Tool Call 时，我们可以选择两个方向来思考 Tool Call 帮助我们扩展应用能力：

* 使用 Tool Call 获取大模型自身训练不包含的信息，丰富上下文，精确回答内容；
* 使用 Tool Call 操作本地应用程序，执行特定业务操作。

![](https://mintcdn.com/stepfun/ivZhb9pOE5X12y-g/images/tool_call.jpeg?fit=max\&auto=format\&n=ivZhb9pOE5X12y-g\&q=85\&s=7c8a235c4ace3e198467a444cee565e8)

前者主要通过 Tool Call 调用预定义好的函数，以获得更加精确的信息，帮助大模型补全上下文，从而生成更加精确的回答。
后者则是通过 Tool Call 调用本地应用程序，执行特定的业务操作，以实现更加丰富的功能。

#### 使用 Tool Call 获取信息

这里我们以助手类应用的常见技能 —— 查询天气为例，我们需要构建一个可以通过自然语言，查询天气的能力。

您需要做以下四步：

* 第一步，需要准备好查询天气接口的地址和密钥，构造查询天气的 Function；
* 第二步，构建 get\_weather 工具定义查询天气 Function 的功能；
* 第三步，阶跃大模型识别用户查询天气的意图时，根据提示语给出查询参数；
* 第四步，使用大模型返回的参数调用查天气接口，获取准确的天气信息。

参考代码：以 Python 为例

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI
import requests
import json

# 初始化 查询天气的接口参数，这里我使用的是高德查询天气接口，各位开发者可以按需自行选择供应商进行实现
get_weather_url = "https://restapi.amap.com/v3/weather/weatherInfo?parameters"
get_weather_key = "YOUR_GAODE_API_KEY"
COMPLETION_MODEL= "step-5-preview"

# 初始化 阶跃星辰 Client
STEPFUN_KEY = "YOUR_STEP_API_KEY"
client = OpenAI(base_url="https://api.stepfun.com/v1", api_key=STEPFUN_KEY)

# 初始化查询天气的函数
def get_weather(city):
    params = {
        "city": city,
        "key": get_weather_key,
        "extensions": "base",  # 获取实时天气
    }
    response = requests.get(url=get_weather_url, params=params)  # 实时天气
    if response.status_code == 200:
        data = response.json()
        print(data)
        # weather = data.get ('lives')[0].get ('weather')  # 当前天气现象
        # temperature = data ['lives'][0].get ('temperature')  # 当前温度
        # print ( f"{city} 现在的天气是 {weather} 温度是 {temperature}°C.")
    else:
        print("对不起，我无法获取这个地点的天气。")

# 构建 get_weather 函数说明
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称（必须为汉字）"}
                },
                "required": ["city"],
            },
        },
    }
]

# 调用补全接口进行补全
def query_weather(prompt):
    completion = client.chat.completions.create(
        model=COMPLETION_MODEL,
        messages=[{"role": "user", "content": prompt}],
        ## 自动选择是否调用外部函数
        tool_choice="auto",
        tools=tools,
    )
    # print (completion.choices [0].message.content.strip ())
    print(completion)
    # 判断是否命中查询天气 Function
    if completion.choices[0].message.content.strip() == "":
        if completion.choices[0].message.tool_calls[0].function.name == "get_weather":
            # 获取参数
            city_name = json.loads(
                completion.choices[0].message.tool_calls[0].function.arguments
            )
            # 调用 Function
            get_weather(city_name["city"])
        else:
            print("未命中查询天气 Tool")
    else:
        print("抱歉出错了")
        # print (completion.choices [0].message.content.strip ())

# 查询天气
query_weather("上海现在的天气怎么样？")

```

返回结果：

```jsonc theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# 返回值结果
# 首先大模型通过意图识别到需要调用 Tool Call，所以在 tool_calls 里给出了需要调用的函数名称，以及参数
{
    "id": "291c59ebf4017a937a2a42a8ed52581f.c2669ebc05a491c70f821b4e568b6433",
    "object": "chat.completion",
    "created": 1722505763,
    "model": "step-5-preview",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "",
                "tool_calls": [
                    {
                        "id": "call_brg23SRcTgmpm_V0jfP-iA",
                        "type": "function",
                        "function": {
                            "name": "get_weather",
                            "arguments": "{\"city\": \" 上海 \"}"
                        }
                    }
                ]
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "cached_tokens": 48,
        "prompt_tokens": 94,
        "completion_tokens": 16,
        "total_tokens": 110
    }
}
# 接着使用大模型给出的参数调用查询天气接口，获得准确的天气
{
    "status": "1",
    "count": "1",
    "info": "OK",
    "infocode": "10000",
    "lives": [
        {
            "province": "上海",
            "city": "上海市",
            "adcode": "310000",
            "weather": "晴",
            "temperature": "37",
            "winddirection": "西北",
            "windpower": "≤3",
            "humidity": "42",
            "reporttime": "2024-08-02 10:01:14",
            "temperature_float": "37.0",
            "humidity_float": "42.0"
        }
    ]
}

# 继续拼接作为上下文信息放入 Messages，让大模型进行补全。
```

#### 使用 Tool Call 执行任务

当应用需要扩展其能力，不仅仅是获取数据时，则可以通过 Tool Call 能力，为您的应用增加一些神奇的能力，从而帮助用户更进一步展示不同的能力。

这里我们同样以助手类应用为例，我们可以实现一个通过自然语言发送电子邮件的能力。您需要做以下几步：

* 第一步，在本地构建出一个发送邮件的 Function ，并实现发送邮件相关功能；
* 第二步，构建 send\_email 工具定义发送邮件的功能；
* 第三步，阶跃大模型识别用户发送邮件的意图时，根据提示语给出查询参数；
* 第四步，使用大模型返回的参数调用发送电子邮件。

##### 参考代码：以 Python & Swift 为例

本地的发送邮件的 Function

```swift theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
func sendEmail (subject:String, body: String, recipient: String) {
    // 调用 MFMailComposeViewController 来发送邮件
}
```

服务端调用阶跃星辰大模型的参考代码

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

# 初始化 阶跃星辰 Client
STEPFUN_KEY = "YOUR_STEP_API_KEY"
client = OpenAI(base_url="https://api.stepfun.com/v1", api_key=STEPFUN_KEY)

# 构建 sendEmail 函数说明
tools = [
    {
        "type": "function",
        "function": {
            "name": "sendEmail",
            "description": "这个函数可以用于向特定的用户发送包含特定内容的电子邮件",
            "parameters": {
                "type": "object",
                "properties": {
                    "subject": {
                        "type": "string",
                        "description": "邮件的标题，不可以超过 255 个字",
                    },
                    "body": {
                        "type": "string",
                        "description": "邮件内容，不可以超过 4096 个字",
                    },
                    "recipient": {"type": "string", "description": "收件人"},
                },
                "required": ["subject", "body", "recipient"],
            },
        },
    }
]

# 调用阶跃星辰 API 生成接口调用方法
def get_call_sign(user_input):
    completion = client.chat.completions.create(
        model=COMPLETION_MODEL,
        messages=[{"role": "user", "content": user_input}],
        ## 自动选择是否调用外部函数
        tool_choice="auto",
        tools=tools,
    )
    if completion.choices[0].message.content.strip() == "":
        if completion.choices[0].message.tool_calls[0].function.name == "sendEmail":
            # 获取参数
            arguments = json.loads(
                completion.choices[0].message.tool_calls[0].function.arguments
            )
            # 触发本地调用函数
            send_to_client("sendEmail", arguments)

```

#### 注意事项

* 构造 Tool 的时候请注意将 Function 的 description 描述清楚，以便于大模型清晰的知道 Function 的功能，这样能提高命中率；
* Function 入参的 description 也需要备注清楚（建议说明入参是中文还是英文），以便于大模型生成有效的参数供使用。


# 故障排查
Source: https://platform.stepfun.com/docs/zh/guides/developer/troubleshooting



为了方便用户快速定位问题，阶跃星辰在[异常处理](/docs/zh/guides/developer/exception)中提供了常见问题的处理建议。如果您在使用过程中遇到无法解决的问题，建议您先查看该页面的内容

但在您无法通过自助排查解决问题的情况下，您可以通过[联系我们](/docs/zh/guides/contact-us)的方式与我们取得联系。请在联系时提供以下信息，以便我们更快地定位问题：

## Chat API

如果您使用的是 [Chat API](/docs/zh/api-reference/chat/chat-completion-create) / [文生图](/docs/zh/api-reference/images/image)/[图生图](/docs/zh/api-reference/images/image2image)/[图片编辑](/docs/zh/api-reference/images/edits)/[音频生成](/docs/zh/api-reference/audio/create-audio)/[复刻音色](/docs/zh/api-reference/audio/create-voice)/[音频转写](/docs/zh/api-reference/audio/transcriptions)，请提供以下信息：

* 返回响应头 Header 中的 `X-Trace-Id` 字段。
* 生成结果中的 ID，即下方示例中的 `b7b56af0-52a6-483f-a589-948182676a1b`

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"id": "b7b56af0-52a6-483f-a589-948182676a1b",
	"object": "chat.completion",
	"created": 1709893411,
	"model": "step-3.7-flash",
	"choices": [
		{
			"index": 0,
			"message": {
				"role": "assistant",
				"content": "你好！阶跃星辰是一家专注于人工智能技术的公司，致力于开发和提供各种AI解决方案。我们的人工智能技术涵盖了自然语言处理、计算机视觉、机器学习等领域，旨在帮助用户在各个行业和领域中提高效率和创造价值。\n\n我们提供多种AI产品和服务，包括智能客服、虚拟助手、智能推荐、智能审核等。这些产品和服务可以应用于多个行业，如金融、零售、教育、医疗等。通过使用我们的AI技术，用户可以更好地理解和分析数据，提供个性化的服务和体验，提高决策效率和准确性。\n\n我们注重用户数据的安全和隐私保护，严格遵守相关法律法规和行业标准。我们相信，人工智能技术应该为人类创造更多的福祉，而不是带来负面的影响。我们将继续努力，为用户提供更加智能、高效、安全的AI解决方案。"
			},
			"finish_reason": "stop"
		}
	],
	"usage": {
		"prompt_tokens": 83,
		"completion_tokens": 176,
		"total_tokens": 259
	}
}
```

## Realtime API

如果您使用的是 [Realtime API](/docs/zh/api-reference/realtime/chat)，请提供以下信息：

* `session.created` 和 `session.updated` 中的 `session.id` 字段,即下方示例中的 `sess_001`

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"event_id": "event_def",
	"type": "session.created",
	"session": {
		"id": "sess_001",
		"object": "realtime.session",
		"model": "step-1o-audio",
		"modalities": ["text", "audio"],
		"instructions": "你是由阶跃星辰提供的AI聊天助手，你擅长中文，英文，以及多种其他语言的对话。",
		"voice": "linjiajiejie",
		"input_audio_format": "pcm16",
		"output_audio_format": "pcm16",
		"max_response_output_tokens": "4096"
	}
}
```

## 流式生成音频 api

如果您使用的是 [流式生成音频 API](/docs/zh/api-reference/audio/ws-audio)，请提供以下信息：

* 任一事件中的 `session_id` 字段，即下方示例中的 `01956e7388477cfcbdc3aaabf364bc70`

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"event_id": "01956e73888c7953896a6e176bf3d760",
	"type": "tts.connection.done",
	"data": {
		"session_id": "01956e7388477cfcbdc3aaabf364bc70"
	}
}
```


# 音频合成
Source: https://platform.stepfun.com/docs/zh/guides/developer/tts



阶跃星辰为开发者提供了语音互动模型，开发者可以使用阶跃星辰的语音互动模型来完成音频生成、[音色复刻](/docs/zh/api-reference/audio/create-voice)、[语音识别](/docs/zh/api-reference/audio/transcriptions)的能力，帮助开发者可以在自己的应用中除了实现标准的大模型的理解能力，还可以实现语音交互。

## 快速开始

### 快速生成一段音频

复制如下代码，您可以快速生成一段音频文件。

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl --location 'https://api.stepfun.com/v1/audio/speech' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $STEP_API_KEY" \
--data '{
    "model":"step-tts-mini",
    "input":"智能阶跃，十倍每一个人的可能",
    "voice":"cixingnansheng"
}'\
--output "step.mp3"
```

## 场景与官方音色推荐

阶跃星辰为开发者提供了七大场景数十种官方推荐音色，您可以在这里试听不同的音色，并在 API 当中调用。
但我们强烈建议您通过 [音色复刻](/docs/zh/api-reference/audio/create-voice) 的能力，定制您的专属音色。`step-tts-2` 具备业界领先的复刻性能，且复刻音色可 0 成本支持全部情绪、风格控制。

### 1. 营销场景

营销场景需要音色具有感染力、说服力和亲和力，能够有效传递产品价值并激发购买欲望。`step-tts-2` 特色在于能够给出饱满的情绪，给用户以信任感和专业度，让营销内容更具吸引力。

| 推荐模型 | 推荐音色 | Voice-id | 合成示例 |
| :- | :- | :- | :- |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 活力轻快 | livelybreezy-female | [我们的在线课程帮助数千人实现了职业突破，下一个成功的就是您！](https://static-openapi.stepfun.com/static/platform-docs/resource/1764227859773_6r0lga.wav) [精致的设计，贴心的细节，让每一件产品都成为您生活中的艺术品。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764227873237_xbptdq.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 正派青年 | zhengpaiqingnian | [限时优惠仅剩最后3天！现在购买即可享受买一送一超值福利，错过不再有！](https://static-openapi.stepfun.com/static/platform-docs/resource/1764227897199_sz9mse.wav) [想象一下，每天清晨被温暖的阳光唤醒，我们的智能窗帘为您开启美好的一天。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764227907908_w73z24.wav) |

### 2. 客服场景（电话催收等）

客服场景需要音色亲切、耐心、专业，能够有效安抚用户情绪并提供清晰解决方案。我们提供两种类型的客服音色，`step-tts-2` 音质突出、情绪饱满、真人感强，前四个推荐音色非常适合电话场景。

| 推荐模型 | 推荐音色 | Voice-id | 合成示例 |
| :- | :- | :- | :- |
| `stepaudio-2.5-tts` / `step-tts-2` | 爽快男声 | shuangkuainansheng | [【催收场景】您好，请问是张先生吗？这里是催债公司客服，关于您账户尾号1788的款项，想跟您做个温馨提醒，目前已经逾期5天了。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764232419372_cjweb4.wav) [感谢您的来电，我是客服专员张明，工号2087，请问怎么称呼您？](https://static-openapi.stepfun.com/static/platform-docs/resource/1764232431616_d45kct.wav) [关于您查询的账单问题，我这边可以看到具体明细，现在为您详细说明。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764232439733_ucrkox.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` | 干练女声 | ganliannvsheng | [【催收场景】孙女士，这次逾期可能会对您的个人信用记录产生负面影响，我们希望能协助您避免这个问题。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764232450294_e3wqt8.wav) [您好，欢迎致电客户服务中心，我是您的专属客服李静，很高兴为您服务。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764232467535_p2pu4n.wav) [请您提供一下手机号码和身份证后四位，我来为您核实账户信息。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764232485079_rarrcy.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` | 亲和女声 | qinhenvsheng | [【催收场景】如果目前全额还款有压力，我们可以先安排处理一部分，比如先还3万元，剩余部分我们再协商一个方案，您看可以吗？](https://static-openapi.stepfun.com/static/platform-docs/resource/1764232648658_g46auz.wav) [听到您的情况我很关切，请相信我们会尽全力帮助您。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764232658059_p1hw59.wav) [这个情况确实比较特殊，请允许我请示主管后给您回电解答。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764232666804_uxi2nq.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` | 活力女声 | huolinvsheng | [【催收场景】“您说‘马上处理’具体是指今天下午几点前呢？我需要记录一个确切的时间点，以便后续为您跟进服务。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764232752142_umr3gn.wav) [很高兴能为您解决问题，祝您有美好的一天，再见！](https://static-openapi.stepfun.com/static/platform-docs/resource/1764232784129_7y8d7t.wav) [我们的服务时间是早8点到晚10点，欢迎再次来电。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764232765549_zhtxfv.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 气质温婉 | elegantgentle-female | [您的满意是我们最大的追求，感谢您选择我们的服务。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764232963968_2lpzrh.wav) [我完全理解您的情况，让我们一起来看看如何最好地解决这个问题。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764232975950_nb22zj.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 活力轻快 | livelybreezy-female | [您的满意是我们最大的追求，感谢您选择我们的服务。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764233092953_7uj9hs.wav) [我完全理解您的情况，让我们一起来看看如何最好地解决这个问题。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764233081037_2uelez.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 温柔男声 | wenrounansheng | [非常理解您的心情，我们会尽快为您解决这个问题。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764233106756_zi400x.wav) [您的订单已经处理完成，预计明天下午就能送达，请您注意查收。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764233116023_vvny08.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 经典女声 | jingdiannvsheng | [您的满意是我们最大的追求，感谢您选择我们的服务。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764233202847_b14wof.wav) [我完全理解您的情况，让我们一起来看看如何最好地解决这个问题。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764233185685_fx2jym.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 温柔熟女 | wenroushunv | [您的满意是我们最大的追求，感谢您选择我们的服务。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764233217617_grbf54.wav) [我完全理解您的情况，让我们一起来看看如何最好地解决这个问题。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764233227812_ca92c6.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 甜美女声 | tianmeinvsheng | [您的满意是我们最大的追求，感谢您选择我们的服务。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764233448772_4id5xn.wav) [我完全理解您的情况，让我们一起来看看如何最好地解决这个问题。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764233457923_qdn6vq.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 清纯少女 | qingchunshaonv | [您的满意是我们最大的追求，感谢您选择我们的服务。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764233506642_dd78q1.wav) [我完全理解您的情况，让我们一起来看看如何最好地解决这个问题。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764233498003_buc059.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 元气男声 | yuanqinansheng | [非常理解您的心情，我们会尽快为您解决这个问题。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764233516928_rpphje.wav) [您的订单已经处理完成，预计明天下午就能送达，请您注意查收。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764233522624_r33ce3.wav) |

### 3. 有声书场景

有声书需要音色富有表现力、感染力，能够生动展现不同角色和情节氛围。我们的 TTS 特色在于细腻的情感表达和多变的语音风格，让听众沉浸于故事世界。

| 推荐模型 | 推荐音色 | Voice-id | 合成示例 |
| :- | :- | :- | :- |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 儒雅男士 | ruyananshi | [“老人的眼中闪烁着智慧的光芒，缓缓道出那个埋藏千年的秘密。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231706722_cerhao.wav) [“狂风呼啸，海浪拍打着船舷，水手们紧紧抓住缆绳，与命运抗争。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231727050_6znwwg.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 温柔女声 | wenrounvsheng | [“魔法森林中，精灵们跳着轻盈的舞蹈，星光为她们点亮前路。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231734698_puka7d.wav) [她轻轻抚摸着那本旧日记，泪水模糊了字迹，回忆如潮水般涌来。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231740416_syoeyy.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 温柔公子 | wenrougongzi | [“月光洒在古老的城堡上，远处传来狼群的嚎叫，令人不寒而栗。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231762453_68oj6b.wav) [“他深吸一口气，推开了那扇尘封已久的大门，命运的齿轮开始转动。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231771111_0r0h3f.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 磁性男声 | cixingnansheng | [月光洒在古老的城堡上，远处传来狼群的嚎叫，令人不寒而栗。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231784986_xvr1ij.wav) [“他深吸一口气，推开了那扇尘封已久的大门，命运的齿轮开始转动。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231791652_9d9uy1.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 元气少女 | yuanqishaonv | [“花园里的玫瑰在晨露中绽放，散发着淡淡的香气，宛如少女的脸颊。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231810865_xiz5jk.wav) [“她轻轻抚摸着那本旧日记，泪水模糊了字迹，回忆如潮水般涌来。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231820537_fz8979.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 正派青年 | zhengpaiqingnian | [“月光洒在古老的城堡上，远处传来狼群的嚎叫，令人不寒而栗。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231834824_31a18s.wav) [“他深吸一口气，推开了那扇尘封已久的大门，命运的齿轮开始转动。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231842616_3y3jsx.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 元气男声 | yuanqinansheng | [“老人的眼中闪烁着智慧的光芒，缓缓道出那个埋藏千年的秘密。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231882851_ha2oe6.wav) [“狂风呼啸，海浪拍打着船舷，水手们紧紧抓住缆绳，与命运抗争。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231889066_vty0d3.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 播音男声 | boyinnansheng | [“月光洒在古老的城堡上，远处传来狼群的嚎叫，令人不寒而栗。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231898586_yvqsfk.wav) [“他深吸一口气，推开了那扇尘封久的大门，命运的齿轮开始转动。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231903863_n0rq6k.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 深沉男音 | shenchennanyin | [“月光洒在古老的城堡上，远处传来狼群的嚎叫，令人不寒而栗。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231909638_diuypc.wav) [“他深吸一口气，推开了那扇尘封已久的大门，命运的齿轮开始转动。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764231916499_zk19wv.wav) |

### 4. 情感陪伴场景

情感陪伴需要音色温暖、柔和、富有同理心，能够给予用户心理慰藉和支持。我们的 TTS 特色在于细腻的音色温柔动听，情绪感染力强，可为您的用户营造出安全、舒适的交流氛围。

| 推荐模型 | 推荐音色 | Voice-id | 合成示例 |
| :- | :- | :- | :- |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 气质温婉 | elegantgentle-female | [“我在这里陪着你，无论快乐还是忧伤，我们都一起面对。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764230170888_rpysp8.wav) [“你的坚强让我感动，但也要记得适时地让自己休息一下。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764230185710_01rt1x.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 活力轻快 | livelybreezy-female | [“生活中总会有不如意的时候，但美好的事物永远值得期待。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764230220618_qbsx4o.wav) [“说出来会好受一些，我永远是你忠实的听众和朋友。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764230236362_tfyy2l.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 温柔男声 | wenrounansheng | [“今天过得怎么样？如果有什么心事，我很愿意倾听。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764230277656_1jj8at.wav) [“每个人都会有感到迷茫的时候，这很正常，你并不孤单。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764230256668_9lhgua.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 温柔公子 | wenrougongzi | [“深呼吸，放松心情，我相信你有能力面对任何挑战。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764230295150_t7wi3h.wav) [“你的感受很重要，感谢你愿意与我分享内心的想法。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764230307812_0gi9a8.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 经典女声 | jingdiannvsheng | [“我在这里陪着你，无论快乐还是忧伤，我们都一起面对。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764230324896_hhowz6.wav) [“你的坚强让我感动，但也要记得适时地让自己休息一下。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764230343351_k3vj3k.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 亲切女声 | qinqienvsheng | [早上好呀，今天天气真不错，适合出去走走。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764230361427_d9rn3n.wav) [观众朋友们，大家好！欢迎收看今天的新闻播报。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764230377953_9uheoc.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 甜美女声 | tianmeinvsheng | [“生活中总会有不如意的时候，但美好的事物永远值得期待。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229581488_9bjx0x.wav) [“说出来会好受一些，我永远是你忠实的听众和朋友。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229591698_yk6d1a.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 磁性男声 | cixingnansheng | [“今天过得怎么样？如果有什么心事，我很愿意倾听。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229600823_8hr2u3.wav) [“每个人都会有感到迷茫的时候，这很正常，你并不孤单。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229613085_i8q5vt.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 元气少女 | yuanqishaonv | [“我在这里陪着你，无论快乐还是忧伤，我们都一起面对。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229624319_gy96i6.wav) [“你的坚强让我感动，但也要记得适时地让自己休息一下。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229636363_rl7puv.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 邻家姐姐 | linjiajiejie | [“生活中总会有不如意的时候，但美好的事物永远值得期待。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229893983_biv5nz.wav) [“说出来会好受一些，我永远是你忠实的听众和朋友。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229906559_3bkhy1.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 儒雅男士 | ruyananshi | [“今天过得怎么样？如果有什么心事，我很愿意倾听。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229965580_i9iwog.wav) [“每个人都会有感到迷茫的时候，这很正常，你并不孤单。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229990027_178cz8.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 深沉男音 | shenchennanyin | [“深呼吸，放松心情，我相信你有能力面对任何挑战。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229487791_a43xpe.wav) [“你的感受很重要，感谢你愿意与我分享内心的想法。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229478620_pgi8xr.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 温柔女声 | wenrounvsheng | [“我在这里陪着你，无论快乐还是忧伤，我们都一起面对。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229464183_kpaxa8.wav) [“你的坚强让我感动，但也要记得适时地让自己休息一下。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229454546_dxzd93.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 软萌女声 | ruanmengnvsheng | [“生活中总会有不如意的时候，但美好的事物永远值得期待。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229441268_p9xrn8.wav) [“说出来会好受一些，我永远是你忠实的听众和朋友。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229433217_mzc9eo.wav) |

### 5. 语音助手场景

语音助手需要音色清晰、自然、高效，能够准确理解并响应用户指令。我们的 TTS 特色在于韵律自然，情绪饱满，让您的语音助手既专业又亲切。

| 推荐模型 | 推荐音色 | Voice-id | 合成示例 |
| :- | :- | :- | :- |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 气质温婉 | elegantgentle-female | [“您要查询的航班信息已经找到，需要我为您详细说明吗？”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228832095_29ybp3.wav) [“已为您设置明天早上7点的闹钟，祝您晚安。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228840760_7lfeif.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 活力轻快 | livelybreezy-female | [正在搜索您需要的资料，找到3个相关结果，现在为您展示。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228850379_g5udri.wav) [今天北京天气晴朗，气温25度，适合外出活动。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228867575_iogyx5.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 清纯少女 | qingchunshaonv | [“您要查询的航班信息已经找到，需要我为您详细说明吗？”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228890474_009vob.wav) [“电量不足，建议连接充电器，以保持最佳使用体验。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228880711_uo1s1z.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 元气少女 | yuanqishaonv | [“新消息来自张经理：‘项目方案已通过，辛苦了！’”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228956977_jkgzvk.wav) [“正在搜索您需要的资料，找到3个相关结果，现在为您展示。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228942094_6cgojl.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 邻家姐姐 | linjiajiejie | [“您要查询的航班信息已经找到，需要我为您详细说明吗？”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228982358_2c8eqk.wav) [“电量不足，建议连接充电器，以保持最佳使用体验。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228972645_kzl33n.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 儒雅男士 | ruyananshi | [“已为您设置明天早上7点的闹钟，祝您晚安。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229029290_58c9et.wav) [“今天北京天气晴朗，气温25度，适合外出活动。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229015620_qu5naz.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 机灵少女 | jilingshaonv | [“新消息来自张经理：‘项目方案已通过，辛苦了！’”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229042857_sbtid3.wav) [“正在搜索您需要的资料，找到3个相关结果，现在为您展示。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229055562_gz7tjs.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 软萌女声 | ruanmengnvsheng | [“您要查询的航班信息已经找到，需要我为您详细说明吗？”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229191918_0u5rmk.wav) [“电量不足，建议连接充电器，以保持最佳使用体验。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229207559_ifljss.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 邻家妹妹 | linjiameimei | [“新消息来自张经理：‘项目方案已通过，辛苦了！’”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229220926_vubdhb.wav) [“正在搜索您需要的资料，找到3个相关结果，现在为您展示。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229230493_3vr4dl.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 知性姐姐 | zhixingjiejie | [“您要查询的航班信息已经找到，需要我为您详细说明吗？”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229251134_r2dv2t.wav) [“电量不足，建议连接充电器，以保持最佳使用体验。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764229242754_6j194i.wav) |

### 6. 视频配音场景

视频配音需要音色富有表现力、节奏感和画面感，能够与视频内容完美融合。我们的 TTS 特色在于精准的情绪表达和语音节奏控制，增强您视频的感染力。

| 推荐模型 | 推荐音色 | Voice-id | 合成示例 |
| :- | :- | :- | :- |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 邻家姐姐 | linjiajiejie | [“细腻的手工，精致的工艺，每一件作品都承载着匠人的心血与智慧。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228368225_q6vf14.wav) [“美食是文化的载体，味蕾的记忆，让我们开启这段舌尖上的旅程。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228358790_54hsjm.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 邻家妹妹 | linjiameimei | [“在这个快节奏的时代，偶尔慢下来，发现生活中被忽略的美好。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228406946_msnk7y.wav) [“爱与温暖，成长与蜕变，这是一个关于家庭和梦想的动人故事。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228422631_jv0wae.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 青年大学生 | qingniandaxuesheng | [最近在研究一个新课题，感觉超有挑战性，你要一起来研究吗？](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228453152_11xqp7.wav) [从12月1日起，全区将全面应用医保刷脸支付，这一举措将进一步提升医保服务的便捷性。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228437723_owq9wd.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 软萌女声 | ruanmengnvsheng | [“时尚不仅是外在的装扮，更是内心态度的表达和个性的宣言。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228469573_c9d14l.wav) [“在这个快节奏的时代，偶尔慢下来，发现生活中被忽略的美好。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228481762_npxp0m.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 优雅女声 | youyanvsheng | [“在这个快节奏的时代，偶尔慢下来，发现生活中被忽略的美好。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228538767_2lkmyq.wav) [“爱与温暖，成长与蜕变，这是一个关于家庭和梦想的动人故事。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228548744_a6t35v.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 冷艳御姐 | lengyanyujie | [“细腻的手工，精致的工艺，每一件作品都承载着匠人的心血与智慧。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228563074_mkfaxu.wav) [“美食是文化的载体，味蕾的记忆，让我们开启这段舌尖上的旅程。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228577493_12hmg5.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 知性姐姐 | zhixingjiejie | [“从概念到现实，这款产品的诞生经历了数百个日夜的精心打磨。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228598185_j5cgak.wav) [“穿越云海，俯瞰大地，这是只属于勇者的视觉盛宴和心灵震撼。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228588844_rylx9j.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 爽快姐姐 | shuangkuaijiejie | [这个项目我来负责，保证完成得漂漂亮亮！](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228610601_8ca7fa.wav) [从12月1日起，全区将全面应用医保刷脸支付，这一举措将进一步提升医保服务的便捷性。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228620326_6f4lyx.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 文静学姐 | wenjingxuejie | [这本书的见解很独特，值得一读。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228640932_1hg09k.wav) [近期有报道显示，出租车霸占公交车泊位的现象时有发生，这给乘客上下车带来了安全隐患。](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228632403_m8zdxc.wav) |

### 7. 教育与培训场景

教培场景需要音色清晰、准确、有启发性，能够有效传递知识并激发学习兴趣。我们的 TTS 特色在于能把握教师在不同情绪下的声音特点。

| 推荐模型 | 推荐音色 | Voice-id | 合成示例 |
| :- | :- | :- | :- |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 气质温婉 | elegantgentle-female | [“英语中的现在完成时表示过去发生但与现在有关联的动作或状态。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228058073_102wb4.wav) [“让我们一起朗读这首古诗，感受诗人笔下的明月和思乡之情。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228049743_8dc93a.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 温柔男声 | wenrounansheng | [“今天我们学习勾股定理：直角三角形的两条直角边的平方和等于斜边的平方。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228096723_naf04h.wav) [“请注意这个发音要点：舌尖要轻抵上齿龈，发出清晰的辅音。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228085782_awotak.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 活力轻快 | livelybreezy-female | [“光合作用是植物将光能转化为化学能的重要过程，让我们详细了解。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228115572_zfgvsz.wav) [“绘画时要注意透视原理，近大远小，让画面更有立体感。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228129774_s17gwn.wav) |
| `stepaudio-2.5-tts` / `step-tts-2` / `step-tts-mini` | 温柔熟女 | wenroushunv | [“英语中的现在完成时表示过去发生但与现在有关联的动作或状态。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228171350_vs3v5a.wav) [“让我们一起朗读这首古诗，感受诗人笔下的明月和思乡之情。”](https://static-openapi.stepfun.com/static/platform-docs/resource/1764228180145_lct34k.wav) |

## 官方音色清单

| **中文名** | **Voice ID** | **支持模型** | **推荐场景** |
| - | - | - | - |
| Vibrant Youth | vibrant-youth | `stepaudio-2.5-tts`、`step-tts-2` | 有声书、视频配音 |
| Lively Girl | lively-girl | `stepaudio-2.5-tts`、`step-tts-2` | 有声书、视频配音 |
| Soft-spoken Gentleman | soft-spoken-gentleman | `stepaudio-2.5-tts`、`step-tts-2` | 情感陪伴、有声书 |
| Magnetic-voiced Male | magnetic-voiced-male | `stepaudio-2.5-tts`、`step-tts-2` | 有声书、视频配音 |
| 自信男声 | zixinnansheng | `stepaudio-2.5-tts`、`step-tts-2` | 有声书、情感陪伴、教育与培训、营销 |
| 气质温婉 | elegantgentle-female | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 客服与业务办理、口播（解说、新闻）、教育与培训、情感陪伴 |
| 活力轻快 | livelybreezy-female | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 情感陪伴、客服与业务办理、教育与培训、营销 |
| 温柔男声 | wenrounansheng | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 口播（解说、新闻）、情感陪伴、客服与业务办理、教育与培训 |
| 温柔公子 | wenrougongzi | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 情感陪伴、有声书 |
| 元气男声 | yuanqinansheng | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 有声书、口播（解说、新闻）、客服与业务办理 |
| 经典女声 | jingdiannvsheng | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 客服与业务办理、情感陪伴 |
| 温柔熟女 | wenroushunv | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 客服与业务办理、口播（解说、新闻）、教育与培训 |
| 甜美女声 | tianmeinvsheng | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 情感陪伴、客服与业务办理 |
| 清纯少女 | qingchunshaonv | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 客服与业务办理、语音助手 |
| 磁性男声 | cixingnansheng | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 有声书、情感陪伴 |
| 元气少女 | yuanqishaonv | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 有声书、情感陪伴、语音助手 |
| 邻家姐姐 | linjiajiejie | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 口播（解说、新闻）、情感陪伴、语音助手、视频配音 |
| 正派青年 | zhengpaiqingnian | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 营销、有声书 |
| 青年大学生 | qingniandaxuesheng | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 口播（解说、新闻） |
| 播音男声 | boyinnansheng | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 有声书、口播（解说、新闻） |
| 儒雅男士 | ruyananshi | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 有声书、情感陪伴、口播（解说、新闻）、语音助手 |
| 深沉男音 | shenchennanyin | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 情感陪伴、有声书 |
| 亲切女声 | qinqienvsheng | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 口播（解说、新闻） |
| 温柔女声 | wenrounvsheng | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 有声书、情感陪伴 |
| 机灵少女 | jilingshaonv | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 语音助手、口播（解说、新闻） |
| 软萌女声 | ruanmengnvsheng | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 情感陪伴、语音助手、视频配音 |
| 优雅女声 | youyanvsheng | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 视频配音 |
| 冷艳御姐 | lengyanyujie | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 视频配音 |
| 爽快姐姐 | shuangkuaijiejie | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 口播（解说、新闻） |
| 文静学姐 | wenjingxuejie | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 口播（解说、新闻） |
| 邻家妹妹 | linjiameimei | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 视频配音、口播（解说、新闻）、语音助手 |
| 知性姐姐 | zhixingjiejie | `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 视频配音、口播（解说、新闻）、语音助手 |
| 爽快男声 | shuangkuainansheng | `stepaudio-2.5-tts`、`step-tts-2` | 客服与业务办理、语音助手 |
| 干练女声 | ganliannvsheng | `stepaudio-2.5-tts`、`step-tts-2` | 客服与业务办理、语音助手 |
| 亲和女声 | qinhenvsheng | `stepaudio-2.5-tts`、`step-tts-2` | 客服与业务办理、语音助手 |
| 活力女声 | huolinvsheng | `stepaudio-2.5-tts`、`step-tts-2` | 客服与业务办理、语音助手 |

## 音色标签

音色标签支持语速演绎风格、情绪和语言三种选项；其中情绪类型的标签需要放置在 `voice_label.emotion` 字段中、语速演绎风格需放置在 `voice_label.style` 字段中。他们具体的支持情况如下表所示：

| **序号** | **标签名称** | **标签类型** | **step-tts-2支持情况** | **step-tts-mini 支持情况** |
| - | - | - | - | - |
| 1 | 高兴 | 情绪 | √ | √ |
| 2 | 非常高兴 | 情绪 | √ | √ |
| 3 | 悲伤 | 情绪 | √ | √ |
| 4 | 生气 | 情绪 | √ | √ |
| 5 | 非常生气 | 情绪 | √ | √ |
| 6 | 撒娇 | 情绪 | √ | √ |
| 7 | 慢速 | 语速风格 | √ | √ |
| 8 | 极慢 | 语速风格 | √ | √ |
| 9 | 快速 | 语速风格 | √ | √ |
| 10 | 极快 | 语速风格 | √ | √ |
| 11 | 恐惧 | 情绪 | √ | √ |
| 12 | 惊讶 | 情绪 | √ | √ |
| 13 | 兴奋 | 情绪 | √ | √ |
| 14 | 钦佩 | 情绪 | √ | √ |
| 15 | 困惑 | 情绪 | √ | √ |
| 16 | 冷漠 | 演绎风格 | √ | √ |
| 17 | 尴尬 | 演绎风格 | √ | √ |
| 18 | 沮丧 | 演绎风格 | √ | √ |
| 19 | 骄傲 | 演绎风格 | √ | |
| 20 | 温柔 | 演绎风格 | √ | |
| 21 | 甜美 | 演绎风格 | √ | |
| 22 | 豪爽 | 演绎风格 | √ | |
| 23 | 严肃 | 演绎风格 | √ | |
| 24 | 傲慢 | 演绎风格 | √ | |
| 25 | 老年 | 演绎风格 | √ | |
| 26 | 吼叫 | 演绎风格 | √ | |
| 27 | 阴阳怪气 | 演绎风格 | √ | |
| 28 | 磕巴 | 演绎风格 | √ | |

## 输出格式

阶跃星辰 TTS 模型 支持 wav、mp3、flac、opus 和 pcm 格式的音频输出，默认为 mp3格式，您可以根据自己的实际情况选择合适的音频格式进行使用。

## 输出语言

阶跃星辰 TTS 模型支持输出中文、英文，中英混合和日语音频。

## FAQ

**我是否拥有创造出来的音频？**

是的，您创造出来的音频归您所有。但建议在产品上向用户说明相关音频由 AI 生成，以便于用户感知相关音频为 AI 生成。

**如何调整生成的音频的音量?**

您可以在调用生成 API 时，传入 volume 参数，可选值为 0.1\~2.0 ，代表着将音量缩小至 10% \~ 增大至 200%（两倍音量）。

**如何调整生成的音频的语速**
您可以在调用生成 API 时，传入 speed 参数，可选值为 0.5-2 ，代表着将语速降速为之前的一半 \~ 提速至两倍。


# 视频理解
Source: https://platform.stepfun.com/docs/zh/guides/developer/video-chat



阶跃星辰的 `step-5-preview`、`step-3.7-flash` 和 `step-1o-turbo-vision` 模型支持视频理解能力，开发者可以在对话上下文中传入一个视频链接，模型将会自动读取视频中的内容，并基于视频中的内容进行理解，回答用户提出的问题或参与整个上下文的生成。

> 视频上传支持三种方式：可直接访问的视频 URL、Base64 内联（`data:video/mp4;base64,...`）、或通过 [Files API](/docs/zh/api-reference/files/create) 上传后的 `stepfile://` 引用；容器格式支持 MP4、QuickTime、Matroska。

## 使用 Step 5 Preview

`step-5-preview` 原生支持多模态输入，通过 [Chat API](/docs/zh/api-reference/chat/chat-completion-create) 在 `user message` 中传入 `video_url` 和您希望模型做的事情，即可让模型理解视频内容并基于其完成生成。

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl --location 'https://api.stepfun.com/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $STEP_API_KEY" \
--data '{
    "model": "step-5-preview",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://static-openapi.stepfun.com/static/platform-web/vipcase/case1.mp4"
                    }
                },
                {
                    "type": "text",
                    "text": "请概括这个视频的主要内容，并提取关键信息点。"
                }
            ]
        }
    ]
}'
```

基础调用示例见[快速开始](/docs/zh/quickstart/overview)，完整字段说明、Base64 / Files API 用法和推理强度控制见本指南及相关 API 文档。

## 使用 step-1o-turbo-vision

通过 [Chat API](/docs/zh/api-reference/chat/chat-completion-create)，在 `user message` 中传入 `video_url` 格式的视频链接，并写入您希望模型做的事情，即可让大模型理解视频内容，并基于视频内容来完成生成。

比如，如下是一个简单的基于视频写游记的例子：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl --location 'https://api.stepfun.com/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $STEP_API_KEY" \
--data '{
    "model": "step-1o-turbo-vision",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://static-openapi.stepfun.com/static/platform-web/vipcase/case1.mp4"
                    }
                },
                {
                    "type": "text",
                    "text": "你是一个文案专家，你善于通过视频分析内容里面的风景和拍摄者的风格，然后以此为基础创作文案，请根据上传的视频写一段文案，要求充满诗意和浪漫，要求文字极简。"
                }
            ]
        }
    ],
    "max_tokens": 1024
}'
```

大模型会生成如下文字返回给您：

> 在夕阳的余晖中，他们相依相偎，静享这一刻的宁静与美好。酒杯中的液体在微风中轻轻摇曳，仿佛在诉说着他们甜蜜的时光。这一刻，世界仿佛静止，只有他们的心跳声在回响。

您可以参考上述 cURL 的用法，修改 Prompt 并改成您自己想要实现的目标，来让大模型帮助您完成任务。

## 视频理解价格预估

`step-1o-turbo-vision` 的价格会受到 Prompt 长度和视频长度的影响，视频越长，价格越高。这里有一些不同长度的视频在 `step-1o-turbo-vision` 下的价格预估供您参考。

| 视频分辨率 | 视频长度 | 输入 token | 预估输入价格 |
| - | - | - | - |
| 3840x2160 | 00:14 | 5238 | 0.013095 元 |
| 4096x2160 | 01:02 | 24064 | 0.06016元 |

`step-5-preview` 和 `step-3.7-flash` 的定价详见 [API 定价](/docs/zh/guides/pricing/details)。

> **[引入 Prompt 缓存降低费用](/docs/zh/guides/developer/prompt-cache)**

## 注意事项

* 在使用时，强烈建议将视频放在指令前，这样可以让大模型获得更好的效果。
* 视频存在下载和审核的过程，耗时较长，因此在设计产品时，可设计相应的等待交互，帮助用户降低焦虑。
* `step-5-preview`、`step-3.7-flash` 与 `step-1o-turbo-vision` 当前均支持单个小于 128MB 的 MP4 视频文件 URL，如果您需要上传更大的视频或其他格式，可以使用 [ffmpeg](https://www.ffmpeg.org/) 将视频切割为多个小于 128MB 的 MP4 视频，具体操作方式可参考下方说明。
* 由于视频文件需要从您的服务器下载到阶跃星辰的服务器，所以下载速度将会直接影响最终返回的速度，您可以将视频文件放在可被高速访问的地址（如对象存储），以便于阶跃星辰服务器下载视频用于视频理解。

## 常见问题

### 使用 Files API 加速视频理解

在使用视频理解时，如果传入的是外部的 URL，阶跃星辰的服务器将会请求外部 URL，获取视频内容并进行生成。生成的速度将会受到视频下载速度的影响，因此，我们推荐将视频放置在 CDN 或具有较大下载带宽的对象存储上，以便于对视频进行更快的下载。但如果您的视频需要重复使用，比如用来做 Few-shot,则可以考虑将视频使用阶跃星辰 Files API 上传至阶跃星辰文件存储服务上，以避免重复下载，产生持续的流量消耗。

![](https://mintcdn.com/stepfun/ivZhb9pOE5X12y-g/images/guide/video_url.png?fit=max\&auto=format\&n=ivZhb9pOE5X12y-g\&q=85\&s=7847cea6458d835d7d383e1634560e5f)

您可以调用[上传文件](/docs/zh/api-reference/files/create) API，并传入文件，选择 **purpose 为 storage**，上传完成后所获取的 File ID 则可以在对话过程中使用。在拿到 File ID 后，您需要在 File ID 前拼上 `stepfile://`，用于标注这个视频从阶跃星辰文件服务中获取，后续模型在推进推理时，将会从阶跃星辰文件存储服务上获取文件，从而降低下载文件所需的时间，提升整体推理的时延。

## ffmpeg 视频切割操作指南

### 切分视频文件

当您要处理的适配文件大于 128MB 时，您可以使用 ffmpeg 将视频切割为多个视频，并**通过模型将视频内容总结后，作为上下文传递在对话中**，以便于使用完整的视频进行对话。如：将 sample.mp4 切分成若干个 120 秒的视频文件。

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
ffmpeg -i sample.mp4 -acodec copy -f segment -segment_time 120 -vcodec copy -reset_timestamps 1 -map 0 output_time_%d.mp4
```

### 将其他格式转换为 MP4 格式

当您需要将视频从其他格式转换为 MP4 格式时，可以通过 ffmpeg 命令进行转换。如：将 sample.mkv 转换为 sample.mp4 格式可用如下命令：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
ffmpeg -i sample.mkv -codec copy sample.mp4
```


# 网络搜索
Source: https://platform.stepfun.com/docs/zh/guides/developer/web-search



需要让模型回答时效性问题时，请先检索公开网页，再把结果交给对话模型。推荐使用独立的网页搜索接口。该接口与选用哪个聊天模型无关。

> [!WARNING]
>
> `step-5-preview` 不支持在 Chat Completions 的 `tools` 中传入 `type: "web_search"`。请调用 `POST https://api.stepfun.com/v1/search`，再将检索结果写入 `messages` 后调用模型。

## 推荐：网页搜索 API

请求地址：

`POST https://api.stepfun.com/v1/search`

完整参数、场景分类和响应字段见 [网页搜索 API](/docs/zh/api-reference/search/search)。

### 检索示例

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -X POST "https://api.stepfun.com/v1/search" \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "Authorization: Bearer $STEP_API_KEY" \
    -d '{
        "query": "上海最高的楼",
        "n": 5
    }'
```

### 把检索结果交给模型

下面示例先搜索，再把标题、链接和摘要交给 `step-5-preview`：

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import os
import requests
from openai import OpenAI

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

search = requests.post(
    "https://api.stepfun.com/v1/search",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={"query": "上海最高的楼", "n": 5},
)
search.raise_for_status()
results = search.json()["results"]

snippets = "\n\n".join(
    f"{item['title']}\n{item['url']}\n{item['snippet']}" for item in results
)

completion = client.chat.completions.create(
    model="step-5-preview",
    messages=[
        {
            "role": "system",
            "content": "根据检索结果回答用户问题。如果检索结果不足以判断，请明确说明。",
        },
        {
            "role": "user",
            "content": f"上海最高的楼是哪栋？\n\n检索结果：\n{snippets}",
        },
    ],
)

print(completion.choices[0].message.content)
```

也可以把 `/v1/search` 封装成自定义 `type: "function"` 工具，由模型决定何时检索。这与内置 `web_search` 不是同一能力；`step-5-preview` 支持普通 function calling，详见 [工具调用](/docs/zh/guides/developer/tool-call)。

在 Claude Code 等 Agent 客户端中，可使用 [StepSearch MCP](/docs/zh/guides/developer/search-mcp)。Realtime 语音会话的内置搜索见 [Realtime](/docs/zh/guides/developer/realtime)。

## 内置 web\_search 工具（step-5-preview 不支持）

`step-3.7-flash` 等仍支持该工具的模型，可以在 Chat Completions 的 `tools` 中传入 `type: "web_search"`。搜索完成后，结果会作为上下文交给模型继续推理，并按实际调用次数计费，见 [定价说明](/docs/zh/guides/pricing/details)。`step-5-preview` 不要使用下面的写法。

### 启用互联网搜索

如需启用互联网搜索，可以通过在调用 API 时，传入 tools 定义来使用，具体定义如下：

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
#构建web_search工具
tools = [
    {
        "type": "web_search",# 固定值
        "function": {
            "description": "这个web_search用来搜索互联网的信息"# 描述什么样的信息需要大模型进行搜索。
        }
    }
]
```

互联网搜索工具的 `type` 固定为 `web_search`，并支持通过 `function.description` 来描述需要使用搜索的场景，用于指引大模型判断是否需要调用互联网搜索搜索相关信息。在完成搜索后，会以上下文的方式，插入到对话中，并交给大模型进行推理。互联网搜索工具按实际调用的次数计费，具体计费可见[定价说明](/docs/zh/guides/pricing/details)。

### 实现步骤 & 参考代码

以下示例仅适用于仍支持内置 `web_search` 的模型。如开发者有自己的搜索渠道，也可以通过普通 function calling 自行接入。

**非流式响应**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI
# 初始化 阶跃星辰 Client
STEPFUN_KEY = "YOUR_STEP_API_KEY"

client = OpenAI(
base_url="https://api.stepfun.com/v1",
api_key=STEPFUN_KEY
) #定义sys扮演的角色和任务
sys_prompt = "每个提问先通过web search，然后通过web search的结果，回答用户问题"
user_prompt = "上海最高的楼上海什么楼？请只回答楼的名称，不要包含其他内容。例如：上海金茂大厦。" #构建信息
message = [
{"role": "system", "content": sys_prompt},
{"role": "user", "content": user_prompt}
] #构建web_search工具
tools = [
{
"type": "web_search",# 固定值
"function": {
"description": "这个web_search用来搜索互联网的信息"# 描述什么样的信息需要大模型进行搜索。
}
}
]

# 调用补全接口进行补全

completion = client.chat.completions.create(
model="step-3.7-flash",
messages=message,
tool_choice="auto",
tools=tools,
stream=False#非流式可以不进行设置使用默认值
) #非流式
print(completion)

```

**返回结果**

* 返回结果中的 tool\_calls.function.results 当中包含的是搜索引擎返回的信息，您可以基于此渲染 UI。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "id": "354dff9f4e8b0d273cf9d4639ba5f183.2618f2a05bbfdd02896c32051994da8c",
    "object": "chat.completion",
    "created": 1722413870,
    "model": "step-3.7-flash",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "上海中心大厦",
                "tool_calls": [
                    {
                        "id": "call__Tg9p9DHRK2JamqimG-IVA",
                        "type": "web_search",
                        "function": {
                            "name": "step_websearch",
                            "arguments": "{\"keyword\": \"上海 最高的楼\"}",
                            "results": [
                                {
                                    "index": 0,
                                    "url": "https://www.tianqi.com/video/3352.html",
                                    "title": "上海最高的楼 上海最高的楼是哪",
                                    "summary": "\n上海中心大厦是上海市的一座超高层地标式摩天大楼，其地上有119层，还有5层裙楼和5层地下室。上海中心大厦分为9个区，每一个都有自己的空中大厅和中庭。其中空中大厅每一层都建有自己的零售店和餐馆，形成了一个垂直商业区。\n相关推荐 更多 >>\n-\n### 何超莲看中国女排比赛快窒息 并且引发了网友的共鸣\n##### 热点07-30\n-\n### 覃海洋张雨霏一天7次尿检 游泳运动员受大干扰和压力\n##### 热点07-29\n-\n"
                                },
                                {
                                    "index": 1,
                                    "url": "https://www.maigoo.com/news/481863.html?fromapp=wx",
                                    "title": "上海十大高楼排行榜 上海10大最高的摩天大楼 上海最高建筑盘点→买购网",
                                    "summary": "\n15 | 上海信息港枢纽大楼 | 288.00米 | 已建成 |\n16 | 上海恒基中心 | 285.00米 | 已建成 |\n17 | 上海明天广场 | 284.60米 | 已建成 |\n18 | 上海前滩中心 | 280.00米 | 已建成 |"
                                },
                                {
                                    "index": 2,
                                    "url": "http://m.wenda.bendibao.com/sgh/128141.shtm",
                                    "title": "上海最高的楼有多少层- 本地宝",
                                    "summary": "【导语】: 118层.上海最高建筑物是上海中心大厦.上海中心大厦项目面积433954平方米,总高为632米,结构高度为580米,机动车停车位布置在地下,可停放2000辆. 118层.上海最高建筑物是上海中心大厦.上海中心大厦项目面积433954平方米,总高为632米,结构高度为580米,机动车停车位布置在地下,可停放2000辆. 上海三个高楼通常指上海环球金融中心、上海金茂大厦、上海中心大厦.其中,上海环球金融中心是位于中国上海陆家嘴的一栋摩天大楼,楼高492米,地上101层,是世界最高的平顶式大楼. 上海中心大厦是中国第一高楼(截止2018年1月).上海中心大厦项目面积433954平方米,建筑主体为118层,总高为632米,结构高度为580米,机动车停车位布置在地下,可停放2000辆. 金茂大厦又称金茂大楼,曾经是中国大陆最高的大楼,位于上海市浦东新区黄浦江畔的陆家嘴金融贸易区,楼高420.5米. 温馨提示: 微信关注上海本地宝 公众号(shbendibao)输入框回复 社保 ,查看更多上海最新社保卡更换流程、社保卡余额查询,社保卡办理网点等信息. "
                                },
                                {
                                    "index": 3,
                                    "url": "https://hf.house365.com/info6666/398606.html",
                                    "title": "上海最高楼叫什么大厦有多少米高-365淘房网-上海最高楼",
                                    "summary": "上海最高楼叫上海中心大厦,总高为632米,共有132层,地上127层,地下5层.它不仅是上海最高的楼,也曾是中国最高的楼,现被739米的H700深圳塔取代.上海中心大厦于2008年11月29日开工,直到2016年3月12日全部完工,2016年4月27日开始运营.上海中心的设计来自美国的Gensler建筑设计事务所设计,其设计的'龙型方案中标后,与同济大学建筑设计研究院完成施工图出图,深化大厦细部设计. 上海中心大厦采用了一种'龙型设计能够延缓风流,随着高度的升高,每层扭曲近1度,将风环绕建筑时的侧力减少24%,提升了大厦的安全.此外,上海中心大厦不单单是一座办公楼,每个区都有自己的空中大厅和中庭,形成了一个垂直区.1号区将是零售区,2号区到6号区将为办公区,酒店和观景台座落于7号区到9号区.空中大厅的每一层都将建有自己的零售店和餐馆,成为一个垂直区. 除了上海中心大厦外,上海环球金融中心也是上海的地标建筑之一,它位于中国上海陆家嘴的一栋摩天大楼,2008年8月29日竣工,楼高492米,地上101层.环球金融中心曾一度成为国内外游客来上海的首选之地,位于100层的观光厅更是成为了上海的一个标志. 总的来说,上海中心大厦和上海环球金融中心都是上海的标志建筑,代表着上海的发展和成就.它们不仅仅是一座建筑,更是上海人民勇于进取、开拓创新的精神象征."
                                },
                                {
                                    "index": 4,
                                    "url": "http://m.nongpin88.com/know/1957952.html",
                                    "title": "上海最高的楼是哪个楼_知道问答_醉学网",
                                    "summary": "上海最高的的楼是上海中心大厦 . 上海中心大厦,位于陆家嘴,建筑主体为118层,总高为632米,其设计高度超过附近的上海环球金融中心,被称为中国第一高楼,世界第三高楼. 上海中心大厦项目面积433954平方米,结构高度为580米,机动车停车位布置在地下,可停放2000辆. 美国SOM建筑设计事务所、美国KPF建筑师事务所及上海现代建筑设计集团等多家国内外设计单位提交了设计方案,美国Gensler建筑设计事务所的“龙型”方案及英国福斯特建筑事务所“尖顶型”方案入围.经过评选,“龙型”方案中标,大厦细部深化设计以“龙型”方案作为蓝本,由同济大学建筑设计研究院完成施工图出图."
                                }
                            ]
                        }
                    }
                ]
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "cached_tokens": 64,
        "prompt_tokens": 1516,
        "completion_tokens": 4,
        "total_tokens": 1520
    }
}
```

**流式响应**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI
# 初始化 阶跃星辰 Client
STEPFUN_KEY = "YOUR_STEP_API_KEY"

client = OpenAI(
base_url="https://api.stepfun.com/v1",
api_key=STEPFUN_KEY
) #定义sys扮演的角色，以及user提出的任务
sys_prompt = "每个提问先通过web search，然后通过web search的结果，回答用户问题" #在调用 Web Search 时，阶跃星辰会将搜索结果作为上下文传入传给大模型，因此如果您需要获取引用内容，可以通过 Prompt Engineering 的方式，#来要求大模型将信息来源反馈给您。具体效果可以参考下方的高亮加粗部分。
#user_prompt = "上海最高的楼上海什么楼？请只回答楼的名称，不要包含其他内容。例如：上海金茂大厦。回答时，你会将所使用的具体信息的 index 一并返回给用户。"
user_prompt = "上海最高的楼上海什么楼？请只回答楼的名称，不要包含其他内容。例如：上海金茂大厦。" #构建信息
message = [
{"role": "system", "content": sys_prompt},
{"role": "user", "content": user_prompt}
] #构建web_search工具
tools = [
{
"type": "web_search",# 固定值
"function": {
"description": "这个web_search用来搜索互联网的信息"# 描述什么样的信息需要大模型进行搜索。
}
}
]

# 调用补全接口进行补全

completion = client.chat.completions.create(
model="step-3.7-flash",
messages=message,
tool_choice="auto",
tools=tools,
stream=True#流式需要设置此参数，非流式可以不进行设置使用默认值
) #非流式
#print(completion) #对流式返回的内容进行打印 / 渲染输出
for chunk in completion:
print(chunk)
#print(chunk.choices[0].delta.content.strip(),end="")

```

**响应**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "id": "1681409a3e4f09244a0951a67612cdf2.c78632c4a6ec4e2ef404a3222c81a82c",
    "object": "chat.completion.chunk",
    "created": 1722413589,
    "model": "step-3.7-flash",
    "choices": [
        {
            "index": 0,
            "delta": {
                "role": "assistant",
                "tool_calls": [
                    {
                        "id": "call_GygttvWbRZu1ympMbC_eEw",
                        "type": "web_search",
                        "function": {
                            "name": "step_websearch",
                            "arguments": "{\"keyword\": \"上海 最高 楼 名称\"}",
                            "results": [
                                {
                                    "index": 0,
                                    "url": "https://www.tianqi.com/toutiao/read/190032.html",
                                    "title": "上海最高的大楼 上海最高的大楼是什么名字 - 天气加",
                                    "summary": "\n当前所在位置 : 天气网\n天气生活\n生活 正文\n# 上海最高的大楼 上海最高的大楼是什么名字\n2022-05-31 来源：天气网 【字体： 大 中 小 】\n上海最高的大楼是上海中心大厦Shanghai Tower，建筑高度632米，位于上海市陆家嘴金融贸易区银城中路501号，是上海市的一座巨型高层地标式摩天大楼，始建于2008年11月29日，于2016年3月12日完成建筑总体的施工工作。上海中心大厦主要用途为办公、酒店、商业、观光等公共设施。\n主楼为地上127层，建筑高度632米，地下室有5层。\n\n上海中心大厦为多功能摩天大楼，主楼沿竖向共分为8个区段和1个观光层，在每个区段的顶部均布置有设备层和避难层。其中1区共5层，主要用于商业和会议。2区共12层、3区共13层、4区共13层、5区共14层、6区共14层均用于办公，办公标准层面积分别为：2区约5000平方米、3区约3900平方米、4区约3200平方米、5区约2700平方米、6区约2000平方米，7区共15层，为酒店。8区共15层，其中10层为酒店，5层用于办公。9区共3层，为观光层。观光层以上为设备层。地下5层用于地下商业和停车。\n"
                                },
                                {
                                    "index": 1,
                                    "url": "https://m.renrenshipu.com/diet/article/24119.html",
                                    "title": "上海最高的楼叫什么 - 阅品美食",
                                    "summary": "\n在上海之巅360度全视角观光厅，近看东方明珠、金茂大厦、环球金融中心身居足下，远眺外滩、世博园区、八万人体育场尽收眼底，一览苏州河与黄浦江蜿蜒同奔长江共入东海。"
                                },
                                {
                                    "index": 2,
                                    "url": "https://hf.house365.com/info6666/398606.html",
                                    "title": "上海最高楼叫什么大厦有多少米高-365淘房网-上海最高楼",
                                    "summary": "上海最高楼叫上海中心大厦,总高为632米,共有132层,地上127层,地下5层.它不仅是上海最高的楼,也曾是中国最高的楼,现被739米的H700深圳塔取代.上海中心大厦于2008年11月29日开工,直到2016年3月12日全部完工,2016年4月27日开始运营.上海中心的设计来自美国的Gensler建筑设计事务所设计,其设计的'龙型方案中标后,与同济大学建筑设计研究院完成施工图出图,深化大厦细部设计. 上海中心大厦采用了一种'龙型设计能够延缓风流,随着高度的升高,每层扭曲近1度,将风环绕建筑时的侧力减少24%,提升了大厦的安全.此外,上海中心大厦不单单是一座办公楼,每个区都有自己的空中大厅和中庭,形成了一个垂直区.1号区将是零售区,2号区到6号区将为办公区,酒店和观景台座落于7号区到9号区.空中大厅的每一层都将建有自己的零售店和餐馆,成为一个垂直区. 除了上海中心大厦外,上海环球金融中心也是上海的地标建筑之一,它位于中国上海陆家嘴的一栋摩天大楼,2008年8月29日竣工,楼高492米,地上101层.环球金融中心曾一度成为国内外游客来上海的首选之地,位于100层的观光厅更是成为了上海的一个标志. 总的来说,上海中心大厦和上海环球金融中心都是上海的标志建筑,代表着上海的发展和成就.它们不仅仅是一座建筑,更是上海人民勇于进取、开拓创新的精神象征."
                                },
                                {
                                    "index": 3,
                                    "url": "http://www.zsuan.com/dq/dqzs/1467226.html",
                                    "title": "上海最高楼,上海市最高的楼宇多少米叫什么名字 - 装算",
                                    "summary": "1,上海市最高的楼宇多少米叫什么名字 上海的最高建筑是上海中心大厦,2014年建成,总高度632米,共125层. 2,上海最高楼叫什么名字 东方明珠不是楼是建筑最高楼不确定 上海中心大厦 东方明珠 3,上海最高的楼多高 上海最高的楼——上海中心大厦(总高为632米)地理位置:中国上海市陆家嘴金融贸易区建筑高度:632米层 数:地上118层、5层裙楼和5层地下室 4,上海最高的建筑是那幢 上海最高的建筑是上海中心大厦,地处上海最繁华的金融中心区陆家嘴.上海中心大厦总高度是632米,总高度125层,是国内第一高楼,在已经投入使用的写字楼里排名世界第三. 5,上海最高的楼是哪一座 九月十四日,上海的第一高度再次刷新,492米高、101层的上海环球金融中心结构封顶,整幢大楼预计明年春天竣工.据悉,在距地面472米的100层处,设计了“观光天阁”,这一高度或将成为当今世界摩天大楼中人可到达的最高高度,上海也因此将出现世界最高的大楼观光厅. 图为建造中的“上海第一高楼”已“鹤”立楼群,屹立在黄浦江畔 环球金融中心额 6,上海最高的楼 环球金融中心 上海中心比它还要高 但是现在还在打地基呢 N0.1 上海中心大厦(在建):632米,地下5层,地上124层,总高度632米,建筑造价:148亿元.位于浦东的陆家嘴功能区,百占地3万多平方米,其建筑设计方案由美国Gensler建筑设计事务所完成,总承包单位为上海建工(集团)总公司,是目前中国国内在建中的第一高楼. 在2010年上海世博会时地下部分封顶,2012年结构封顶且部分投入运营,2014年竣工交付使用.NO.2 上海环球金融中心是位于中国上海陆家嘴的一栋摩天大楼,2008年8月29日竣工.是中国目前第二高楼、世界第三高楼、世界最高的平顶式大楼,楼高492米,地上101层NO.3 东方明珠广播电视塔:468米,又名东方明珠塔,是一座位于中国上海的电视塔.坐落在中国上海浦东新区陆家嘴,毗邻黄浦江,与外滩隔江相望.东方明珠塔是由上海现代建筑设计(集团)有限公司的江欢成设计.建筑动工于1991年,于1994年竣工,投资总额达8.3亿元人民币.高467.9米,亚洲第二,世界第四高塔,仅次于广州新电度视塔(600米)、加拿大的加拿大CN电视塔(553.3米)及俄罗斯的奥斯坦金诺电视塔(540.1米),是上海的地标之一. 目前的东方明珠高468"
                                },
                                {
                                    "index": 4,
                                    "url": "https://sgh.51dongshi.com/eggaedfresgbcs.html",
                                    "title": "上海市最高的楼叫什么_懂视",
                                    "summary": "上海市最高的楼叫什么 上海最高的楼叫做上海中心大厦,位于陆家嘴,总高632米,建筑主体为118层,是一座超高层地标式摩天大楼,上海中心大厦项目的面积达到了433954平方米,在2008年开工,直到2016年才竣工,费时八年,是目前中国的第一高楼,世界的第二高楼. 推荐度: 导读 上海最高的楼叫做上海中心大厦,位于陆家嘴,总高632米,建筑主体为118层,是一座超高层地标式摩天大楼,上海中心大厦项目的面积达到了433954平方米,在2008年开工,直到2016年才竣工,费时八年,是目前中国的第一高楼,世界的第二高楼. 上海是我们国家经济最为繁荣的城市之一,上海最高的楼也是上海的地标建筑,那么上海最高的楼叫什么呢?一起来看看吧. 上海最高的楼叫做上海中心大厦,位于陆家嘴,总高632米,建筑主体为118层,是一座超高层地标式摩天大楼. 上海中心大厦项目的面积达到了433954平方米,在2008年开工,知道2016年才竣工,费时八年,是目前中国的第一高楼,世界的第二高楼."
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ],
    "usage": {
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "total_tokens": 0
    }
}
{
    "id": "1681409a3e4f09244a0951a67612cdf2.c78632c4a6ec4e2ef404a3222c81a82c",
    "object": "chat.completion.chunk",
    "created": 0,
    "model": "step-3.7-flash",
    "choices": [
        {
            "index": 0,
            "delta": {
                "role": "assistant"
            }
        }
    ],
    "usage": {
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "total_tokens": 0
    }
}
{
    "id": "1681409a3e4f09244a0951a67612cdf2.c78632c4a6ec4e2ef404a3222c81a82c",
    "object": "chat.completion.chunk",
    "created": 1722413589,
    "model": "step-3.7-flash",
    "choices": [
        {
            "index": 0,
            "delta": {
                "content": "上海"
            }
        }
    ],
    "usage": {
        "cached_tokens": 96,
        "prompt_tokens": 2167,
        "completion_tokens": 1,
        "total_tokens": 2168
    }
}
{
    "id": "1681409a3e4f09244a0951a67612cdf2.c78632c4a6ec4e2ef404a3222c81a82c",
    "object": "chat.completion.chunk",
    "created": 1722413589,
    "model": "step-3.7-flash",
    "choices": [
        {
            "index": 0,
            "delta": {
                "content": "中心"
            }
        }
    ],
    "usage": {
        "cached_tokens": 96,
        "prompt_tokens": 2167,
        "completion_tokens": 2,
        "total_tokens": 2169
    }
}
{
    "id": "1681409a3e4f09244a0951a67612cdf2.c78632c4a6ec4e2ef404a3222c81a82c",
    "object": "chat.completion.chunk",
    "created": 1722413589,
    "model": "step-3.7-flash",
    "choices": [
        {
            "index": 0,
            "delta": {
                "content": "大厦"
            }
        }
    ],
    "usage": {
        "cached_tokens": 96,
        "prompt_tokens": 2167,
        "completion_tokens": 3,
        "total_tokens": 2170
    }
}
{
    "id": "1681409a3e4f09244a0951a67612cdf2.c78632c4a6ec4e2ef404a3222c81a82c",
    "object": "chat.completion.chunk",
    "created": 1722413589,
    "model": "step-3.7-flash",
    "choices": [
        {
            "index": 0,
            "delta": {}
        }
    ],
    "usage": {
        "cached_tokens": 96,
        "prompt_tokens": 2167,
        "completion_tokens": 4,
        "total_tokens": 2171
    }
}
{
    "id": "1681409a3e4f09244a0951a67612cdf2.c78632c4a6ec4e2ef404a3222c81a82c",
    "object": "chat.completion.chunk",
    "created": 1722413589,
    "model": "step-3.7-flash",
    "choices": [
        {
            "index": 0,
            "delta": {},
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "cached_tokens": 96,
        "prompt_tokens": 2167,
        "completion_tokens": 4,
        "total_tokens": 2171
    }
}
```

**流式响应并获取引用**

由于 OpenAI 的 SDK 在流式下无法获取到 results 的结果，所以在流式场景下，您需要自行实现调用阶跃星辰模型能力，并解析结果以获得响应。如下是一个基于 `httpx` 的参考代码。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# 需要先执行 pip install httpx httpx-sse 以安装依赖。
import httpx
from httpx_sse import connect_sse
import json

STEP_API_KEY = "YOUR_STEP_API_KEY"

def main():
headers = {
"Authorization": f"Bearer {STEP_API_KEY}"
}
body = {
"model": "step-3.7-flash",
"stream": True,
"messages": [
{
"role": "system",
"content": "你是由阶跃星辰提供的AI聊天助手，你擅长中文，英文，以及多种其他语言的对话。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容。"
},
{
"role": "user",
"content": "你好，请介绍一下 OPPO 公司！"
}
],  
 "tools": [
{
"type": "web_search",
"function": {
"description": "这个函数可以用于搜索不同公司的介绍，比如 特斯拉公司、苹果公司"

                }
            }
        ]
    }

    text = ""
    search_result = []
    finish_reason = ""

    with httpx.Client() as client:
        with connect_sse(client, "POST", "https://api.stepfun.com/v1/chat/completions", headers=headers, json=body) as event_source:
            for sse in event_source.iter_sse():
                # 当返回 "[DONE]"，表示流式结束，可以继续处理后续逻辑
                if (sse.data == "[DONE]"):
                    continue

                response_message = json.loads(sse.data)

                # 提取内容
                text = text + response_message["choices"][0]["delta"]["content"]

                if "finish_reason" in response_message["choices"][0]:
                    finish_reason = response_message["choices"][0]["finish_reason"]

                # 处理流式返回中的 Tool Call 逻辑
                if "tool_calls" in response_message["choices"][0]["delta"]:
                    # 可能会命中多个tool
                    for tool_response in response_message["choices"][0]["delta"]["tool_calls"]:
                        # 处理 web_search 的 tool
                        if (tool_response["type"] == "web_search"):
                            search_result = tool_response["function"]["results"]

    print("______result_________")
    print(f"完整补全内容：{text}")
    print(f"搜索结果: {search_result}")
    print(f"结束原因: {finish_reason}")
    pass

if __name__ == "__main__":
main()

```

### 常见用法

#### 输出使用到的链接

在展示生成结果时，如果希望展示所使用的 Web 链接，则可以要求大模型在返回时，返回所使用的链接，并通过返回的 tool\_calls 的 results 来获取到对应链接的基础信息，并渲染给用户。

### 注意事项

* 在使用流式输出时，将会在返回的第一个 chunk 中带上搜索引擎的结果。您可以使用第一个 chunk 来渲染 UI。
* 在使用大模型推理时，您需要写清楚 System Prompt 和 Tool 的 description，以便大模型能够正确理解您的需求，调用互联网搜索。
* 目前在实际调用互联网搜索时，会先进行意图判断，评估是否需要调用互联网搜索，并不会对每一次调用都使用互联网搜索。


# 语音模型列表
Source: https://platform.stepfun.com/docs/zh/guides/models/audio



## 模型概述

阶跃语音系列模型覆盖实时语音互动、综合音频生成、文本转语音和自动语音识别，提供从文字到音频、从语音到文字以及端到端语音对话的完整能力，适用于配音、语音助手、智能硬件、Voice Agent、音乐创作、实时字幕和会议记录等场景。

## 模型列表

### StepAudio 3 Realtime

* **真人自然交互**：接话自然、节奏松弛、表达有温度，实时互动更接近真人交流。
* **听懂话，也听懂话外之音**：理解语气、情绪、副语言线索和环境声音。
* **真正的全双工对话**：支持自然打断、附和识别和话权协调，不抢话也不装聋。
* **自适应推理**：简单问题快速回应，复杂问题边想边说，在响应速度和回答质量之间动态平衡。
* **从会聊天到能办事**：Voice Agent 可调用工具或执行后端任务，任务完成后自然回到对话。

> **[StepAudio 3 Realtime](/docs/zh/guides/models/stepaudio-3-realtime)**
>
> 查看模型 ID、API 端点、能力说明和计费状态。

### StepAudio 3 TTS

* **真人级说话表现**：在音色、语调、节奏和气口停顿上贴近自然口语，可呈现笑声、迟疑、结巴、重复和改口等真实表达。
* **超低时延流式生成**：支持边生成边输出，适合实时对话和语音助手。
* **高表现力控制**：支持从整体语境到局部表达的细致控制，适合有声内容、配音和情绪化播报。

> **[StepAudio 3 TTS](/docs/zh/guides/models/stepaudio-3-tts)**
>
> 查看 TTS 能力和 API 端点。

### StepAudio 3 Gen

* **综合音频内容创作**：用自然语言描述角色设定、音色风格和情绪表达，即可生成富有表现力、可精细控制的人声，并统一编排音效、环境音、背景音乐与歌声。
* **精细化声音设计与控制**：支持通过自然语言控制多角色台词、音色风格、说话方式、语气情绪、方言口音，以及笑声、喘息、停顿等副语言特征，可在一条指令中描述多个角色及其互动关系。
* **全要素生成与时序编排**：可指定人声、音效、环境音和背景音乐的出现位置与先后顺序，完成协同生成与片段衔接。
* **专业内容生产**：适用于影视、游戏、动画、广播剧和有声书等场景，快速完成角色配音、多角色对白及配套的环境音、音效和背景音乐。
* **短视频与自媒体**：无需专业音频制作经验，一段规范化的自然语言描述即可生成风格可控的配音，并按需补充背景音乐和音效。

> **[StepAudio 3 Gen](/docs/zh/guides/models/stepaudio-3-gen)**
>
> 查看 Gen 能力和 API 端点。

### StepAudio 3 Music

* **歌词成歌**：根据歌词和自然语言风格描述，生成包含人声、旋律、编曲和混音的完整歌曲。
* **纯音乐生成**：根据场景、情绪、节奏和乐器描述生成无演唱人声的音乐。
* **歌曲翻唱与风格切换**：参考歌曲旋律，重新控制风格、人声、编曲和情绪。
* **干声智能配乐**：分析清唱人声的旋律、速度、节拍和情绪，生成匹配的和声、节奏与器乐编配。
* **自然语言音乐控制**：可组合描述曲风、人声、乐器、情绪、调式和制作质感，降低音乐创作门槛。

> **[StepAudio 3 Music](/docs/zh/guides/models/stepaudio-3-music)**
>
> 查看音乐生成能力、任务类型和 API 端点。

### StepAudio 3 ASR

* **语境理解**：以大语言模型为语义底座，结合音频、上下文和领域知识，提升专业术语、人名和同音词识别。
* **跨语言、跨场景提升**：覆盖中文、英文、方言、中英混说、长音频和垂类领域。
* **复杂声音处理**：支持悄悄话、极快语速、含糊连读、环境噪声、歌唱和背景音乐。
* **低误识别**：无语音测试准确率达到 99%，减少环境声、背景音乐和静音片段的误转写。
* **评测亮点**：内部上下文推理错误率 0.57%，较 StepAudio 2.5 ASR 降低 64.2%；AISHELL-6 悄悄话 CER 为 3.97%。

> **[StepAudio 3 ASR](/docs/zh/guides/models/stepaudio-3-asr)**
>
> 查看 ASR 系列能力、当前模型和识别 API。

关于 StepAudio 2.5 系列的对话模型，我们提供了两种不同的方式调用最新的语音对话模型，分别对应 StepAudio 2.5 Realtime 和 StepAudio 2.5 Chat：

* StepAudio 2.5 Realtime，支持实时语音对话的 Realtime 交互形式，使用 websocket 协议，支持语音请求、语音回复，便于直接使用我们封装好的一整套实时对话能力使用。
* StepAudio 2.5 Chat，支持按轮次对话的 Chat Comletion 交互形式，支持单次提交语音请求、流式文本输出回复内容，便于基于接口和模型能力进行接入和开发。

### StepAudio 2.5 Realtime

真正具备“活人感”的实时语音大模型。**全维度打造专属人设，连每一次呼吸和轻笑都不掉戏。**

1. **情绪价值**：不再是冰冷的 AI，而是有脾气、有态度、懂接梗的鲜活搭子，为您带来最自然、好玩的陪伴体验。
2. **对话双商领跑**：实现对话智商与情商的双重跃升。不仅能深度理解复杂语意、机智抛梗，更具备行业顶级副语言感知力——瞬间读懂您语气中的迟疑与轻笑，极速输出契合度拉满的高情商反馈。
3. **副语言感知**：不仅能深度理解复杂语意、机智抛梗，更具备行业顶级副语言感知力——瞬间读懂您语气中的迟疑与轻笑，极速输出契合度拉满的高情商反馈。
4. **千万人设完全自定义**：真正实现“全维灵魂捏脸”，彻底打破预设模板束缚。支持细颗粒度定义性格特征、专属口癖与情绪边界，随心打造千万种独一无二的专属搭子。
5. **贴合语境神级表现力**：在声音表现层面，StepAudio 2.5 Realtime 全面继承了业内顶尖的 StepAudio 2.5 TTS 能力，理解与生成的深度融合，结合强化学习训练，实现了“Global 全局场景定调”与“句内细节雕琢”的双重能力。能够精准洞察对话氛围，极细颗粒度地拿捏语速、重音与潜台词；发声时自然融入轻笑、叹息等真实细节，让每一次开口都与当下的交流场景完美契合。

情感陪伴、日常交流、百科问答、任务助手等日常实时沟通交互对话全场景。

### StepAudio 2.5 Chat

真正具备“活人感”的对话大模型。**全维度打造专属人设，连每一次呼吸和轻笑都不掉戏。**

1. **情绪价值**：不再是冰冷的 AI，而是有脾气、有态度、懂接梗的鲜活搭子，为您带来最自然、好玩的陪伴体验。
2. **对话双商领跑**：实现对话智商与情商的双重跃升。不仅能深度理解复杂语意、机智抛梗，更具备行业顶级副语言感知力——瞬间读懂您语气中的迟疑与轻笑，极速输出契合度拉满的高情商反馈。
3. **副语言感知**：不仅能深度理解复杂语意、机智抛梗，更具备行业顶级副语言感知力——瞬间读懂您语气中的迟疑与轻笑，极速输出契合度拉满的高情商反馈。
4. **千万人设完全自定义**：真正实现“全维灵魂捏脸”，彻底打破预设模板束缚。支持细颗粒度定义性格特征、专属口癖与情绪边界，随心打造千万种独一无二的专属搭子。

### StepAudio 2.5 TTS

Contextual TTS，真正具有声音表演能力的语音合成模型。首次将**语境理解能力**引入语音生成全流程，让 AI 不是念文本，而是演文本。支持**通过自然语言描述实现全局语境定调与句中细腻控制**，生成具有呼吸感、轻重主次、情绪弧线的真人级表达。

1. **双档语境控制，人人都是配音导演**：
   * 通过 Global Context（全局语境）+ Inline Context（文中语境）双档控制，既能为整段内容定调氛围和人物关系，也能逐句精控每个字词如何演绎。
   * 告别传统标签匹配，用自然语言描述您想要的声音表达。情绪、风格、场景、说话状态，模型都能理解并精准执行。
   * 支持「克制的悲伤，不哭腔，轻轻发颤」「试探着撒娇，不是很黏，带一点嘴硬」这类复杂、混合、有层次的表达意图，实现更开放、更连续、也更贴近真实语境的情绪控制。
2. **Zero-shot Clone 全音色可控，百变音色随心复刻**：
   * 只需 3s 参考音频即可进行音色复刻，且完整继承全局 / 文中语境控制能力，不受固定音库和预设角色的限制。
3. **字字有戏，句句真实，开口没有 AI 味**：
   * 在停顿、重音、节奏、语气转折等韵律维度上全面提升，合成语音有呼吸感、有轻重主次、有情绪起伏。
   * 底层人声品质升级，输出的声音更通透、更具拟人感，没有传统语音合成常见的“塑料感”和“AI 味”。

有声书、短剧配音、广告旁白、情感叙事、内容二创等多种对语音表现力有高要求的场景。

### StepAudio 2.5 ASR

阶跃新一代语音识别模型，4B 参数 + Multi-Token Prediction（MTP）架构。在保持 SOTA 转写精度的同时单步并行预测多个 Token，大幅削减串行等待——5 分钟音频可在 1 秒内完成转写。提供一次性提交（SSE，模型字符串 `stepaudio-2.5-asr`）与实时双向流式（WebSocket，模型字符串 `stepaudio-2.5-asr-stream`）两种接入方式。

1. **极速推理，吞吐与时延双线突破**：
   * 引入 MTP 技术单步并行预测多个 Token，吞吐量较传统 ASR 提升 400%，时延降低 60%。
   * 引擎侧 RTF ≈ 0.0053，转写 1 小时音频约需 19 秒，5 分钟音频 1 秒内出完整结果。
2. **SOTA 转写精度，多场景全面刷新基线**：
   * 基于 4B 参数深度优化，在新闻、会议、强噪声等多场景下，中英文错误率全面刷新行业基线。
   * 支持 ITN 文本规范化，转写结果可直接用于业务系统。
3. **进阶识别能力**：
   * 双向流式（`stepaudio-2.5-asr-stream`）支持累计全量文本、可纠错尾词与字级时间戳，适合实时对话、语音助手、会议字幕。
   * 音频文件识别支持分句与字 / 词级时间戳、双声道分轨，以及说话人识别（区分同一段音频中的不同说话人）。
4. **极致性价比，Step Plan 直接可用**：
   * 一次性提交（SSE）API 定价 0.15 元 / 小时，仅为上代 `step-asr` 系列的 1/10；双向流式 1.2 元 / 小时。
   * Step Plan 订阅用户可直接调用，无需额外开通。

Voice Agent、大规模批量转写、实时字幕 / 直播、会议记录、语音输入等对识别速度与准确率均有要求的场景。

### Step Audio 2

* 定位：全方位感官理解与端到端自然交互
* 能力标签：音色复刻、Tool Call、网络搜索
* 体验入口：[体验中心](https://www.stepfun.com/studio/audio?tab=voice-chat)
* 在语言方面能够理解中文普通话、中文方言、英语、日语。支持语音复刻（通过上传音色片段实现自定义音色）。在能力方面能够理解环境声音事件、人类副语言和语音中的情绪、根据声音推测用户年龄、理解音乐，能够控制不同的语速、语调和情感进行表达，具备原生的 Tool Call 和 网络搜索 能力。

### Step Audio 2 Mini

* 定位：轻盈、极速而又不失深度
* 能力标签：Tool Call、网络搜索
* 接入方式：仅支持 API 接入
* 与 `step-audio-2` 模型相似，原生的 Tool Call 和网络搜索能力，效果得分在指令遵循、数理和推理任务上略低于 `step-audio-2`。模型推理速度更快，需要的资源更少。

### StepAudio 2 ASR Pro

32B 参数的 ASR Pro 模型。

### Step Audio R1.5

* 定位：深度声音理解与推理（Step Audio R1.1 升级版）
* 能力标签：边说边想、深度推理、自然交互
* 体验入口：[体验中心](https://www.stepfun.com/studio/audio?tab=conversation)
* 在 Step Audio R1.1 的基础上升级，进一步强化声音细节分析与逻辑推理能力，能听懂语气背后的深意，大幅提高对声音和情绪的理解。
* 引入基于人类反馈的强化学习（RLHF），在保持推理能力的同时，提升长程语音对话的自然度与情感连贯性。
* 推理和说话并发进行，在保证高质量回复的同时实现更快响应。

> [!NOTE]
>
> 原 Step Audio R1.1 已升级为 Step Audio R1.5，并结束限时免费，按文本 token 计费。计费标准请见[API 定价](/docs/zh/guides/pricing/details)。

### Step-1o Audio

* 定位：稳定型，久经考验
* 能力标签：Tool Call
* 接入方式：仅支持 API 接入
* 第一代 端到端语音模型。技术成熟稳定，在汽车场景下大规模部署，久经考验，支持多种预置音色风格，支持工具调用。适用于构建基础的语音交互、内容生成等常规业务场景。

**应用案例**

* **情感陪伴场景**：在用户分享人生重要时刻时，如相亲成功经历，模型能够表达恰当的祝贺，提出深入问题，并展现真实的情感共鸣。

  **试听：恭喜相亲成功**
  由 step-1o-audio 生成

  <audio />

* **安全驾驶辅助**：识别驾驶者疲劳状态下的语音特征，给予针对性的安全建议，同时通过情感支持缓解疲劳感。

  **试听：疲劳提醒**
  由 step-1o-audio 生成

  <audio />

* **方言交互能力**：精准模拟地方方言特性，如四川话的音调起伏和特色词汇运用，提供本地化的语音交互体验。

  **试听：四川话**
  由 step-1o-audio 生成

  <audio />

* **如何与男朋友撒娇**：以自然可爱且略带俏皮的语气，示范与亲密关系间的撒娇互动，增强关系亲密度。

  **试听：撒娇互动**
  由 step-1o-audio 生成

  <audio />

* **亲子关系支持**：针对家长首次送孩子入学等敏感场景，理解并安抚焦虑情绪，同时提供实用的适应性建议。

  **试听：入学的安抚**
  由 step-1o-audio 生成

  <audio />

### Step TTS 2

`step-tts-mini` 的升级版：极简高效设计摒弃传统 speaker/emotion 嵌入模块，通过纯 NTP 实现端到端语音生成，大幅降低系统复杂度。支持 `step-tts-mini` 全部音色、情绪、风格、语种，并在其基础上，进一步强化**情绪与风格的可控度**、**情绪表现力** 和**音色复刻效果**。

1. **11 种情绪 17种风格 3种语言精准可控，情绪饱满，韵律自然，表现力强**：
   * 内置 11 种情绪 与 17 种风格 控制，覆盖从温柔甜美到严肃豪爽的多样化表达。语气、韵律与停连更贴近真人情绪起伏。
   * 完美适配需要情绪张力的配音与对话。
   * 支持粤语、四川话、日语。
2. **10s 音频，精准复刻，0成本支持全部情绪风格控制**：
   * 仅需约 10 秒参考音频，即可精准复刻音色，并零成本激活全部情绪与风格控制；
   * 适合需要用复刻后的音色 + 多情绪播报的场景，如短视频配音、情感陪聊、营销播报等。
3. **音色复刻支持口音精准还原**：
   * 领先的 LLM-based 架构，相较同类产品，可提供对说话人口音细节更精准的复刻效果。
   * 为 **直播带货** 场景提供更加真实、自然的语音交互体验，有效提升观众沉浸感和信任度。让虚拟主播或智能话术如同真人般亲切生动，显著降低用户听觉疲劳，助力转化率提升。

### Step TTS Mini

强大的文本转语音模型，以高情绪表现力和风格可控性为亮点。

1. **11 种情绪、7种风格、3种语言可控**：内置 9 种情绪 与 13 种风格 控制；支持粤语、四川话、日语。
2. **10s 音频，精准复刻，0成本支持全部情绪风格控制**：仅需约 10 秒参考音频，即可精准复刻音色，并零成本激活全部情绪与风格控制。复刻相似度业界领先。

### Step ASR

阶跃自动语音识别模型，支持实时与离线识别，具备高准确率与低延迟。

特点：

* 支持中英文及多种方言；
* 可应用于语音转写、会议记录、客服质检、语音搜索等场景。

### Step ASR 1.1

阶跃自动语音识别模型，适用于音频文件识别场景。

特点：

* 可应用于语音转写、会议记录、客服质检、语音搜索等场景。

### Step ASR 1.1 Stream

阶跃自动语音识别模型，适用于流式语音识别场景。

特点：

* 适用于实时语音输入与流式文本返回场景。

## 使用限制

1. **单次请求支持的最大字符数**：tts 模型单次最多支持输入 1000 个字符。
2. **输出格式**：支持 wav、mp3、flac、opus，默认为 mp3 格式。
3. **StepAudio 3 Gen 输入限制**：`instruction` 和 `roles` 字段最多 500 字符，`scripts` 字段最多 1000 字符；超出限制时接口返回 HTTP 400。
4. **StepAudio 3 Gen 返回方式**：当前支持 HTTP `audio` / `sse` 返回，不支持 WebSocket 双向流式。

## 模型快速入门

> **[音频合成开发指南](/docs/zh/guides/developer/tts)**
>
> 了解语音生成、音色复刻和语音识别等能力的接入方式。


# 模型下线与迁移
Source: https://platform.stepfun.com/docs/zh/guides/models/deprecations



模型下线后停止提供调用服务。当前模型的能力与规格见[模型列表](/docs/zh/guides/models/list)。

## 下线模型

### 2026 年 10 月 10 日

`step-2x-large`、`step-image-edit-2`、`step-1x-edit` 均已停止提供调用服务。其中，`step-2x-large` 和 `step-image-edit-2` 于 2026 年 10 月 10 日下线，`step-1x-edit` 在此之前已停止服务。详见[图像模型下线公告](/docs/zh/announcements/image-model-retirement)。

### 2026 年 7 月 8 日

| 下线模型 ID | 推荐替代模型 ID 或迁移说明 |
| - | - |
| `step-1-8k` | [`step-1o-turbo-vision`](/docs/zh/guides/models/vision) |
| `step-1-32k` | [`step-1o-turbo-vision`](/docs/zh/guides/models/vision) |
| `step-1v-8k` | [`step-1o-turbo-vision`](/docs/zh/guides/models/vision) |
| `step-1v-32k` | [`step-1o-turbo-vision`](/docs/zh/guides/models/vision) |
| `step-2-mini` | [`step-1o-turbo-vision`](/docs/zh/guides/models/vision) |
| `step-1o-vision-32k` | [`step-1o-turbo-vision`](/docs/zh/guides/models/vision) |
| `step-2-16k` | [`step-1o-turbo-vision`](/docs/zh/guides/models/vision) |
| `step-3` | [`step-3.7-flash`](/docs/zh/guides/models/step-3.7-flash) |
| `step-1x-medium` | 原推荐替代模型 `step-2x-large` 也已下线，参见[图像模型下线公告](/docs/zh/announcements/image-model-retirement) |

## 迁移到替代模型

对于上表中提供推荐替代模型的调用：

1. 查阅对应模型文档，核对输入格式、参数与能力是否满足业务需求。
2. 将请求中的 `model` 字段替换为推荐替代模型的 ID。例如，将 `step-3` 替换为 `step-3.7-flash`。
3. 核对 [API 定价](/docs/zh/guides/pricing/details)，并验证业务调用后再切换生产环境。

如需协助，请[联系我们](/docs/zh/guides/contact-us)。


# 模型列表
Source: https://platform.stepfun.com/docs/zh/guides/models/list



[API 定价](/docs/zh/guides/pricing/details) · [API 速率限制](/docs/zh/guides/pricing/rate-limits) · [模型下线与迁移](/docs/zh/guides/models/deprecations) · [API 快速开始](/docs/zh/quickstart/overview)

**全部模型**

全部模型

## 全部公开模型

推理 / 多模态

Step 5 Preview新一代旗舰基模

最大上下文1M

面向真实任务的新一代旗舰基模，重点覆盖编程与专业知识工作，原生支持文本、图片与视频输入，可结合工具与文档持续推进多步骤任务。API 模型 ID：`step-5-preview`。

知识工作
编程
Agent
图片与视频理解

开始使用

[快速上手发送第一次请求](/docs/zh/quickstart/overview)

[模型总览能力、规格与配置](/docs/zh/guides/models/step-5-preview)

推理 / 多模态

Step 3.7 Flash多模态推理旗舰

最大上下文256K

阶跃星辰旗舰多模态推理模型。在 `step-3.5-flash` 的高速推理与工具调用能力基础上，新增**原生多模态输入能力**，可直接理解图片和视频内容，无需借助视觉 MCP 或额外模型。支持三档推理强度（low/medium/high），是智能体、代码与多模态场景的快且可依赖的模型。

推理
多模态
Agent
图片理解
视频理解

相关入口

[模型页Step 3.7 Flash](/docs/zh/guides/models/step-3.7-flash)

[快速上手多模态快速上手](/docs/zh/quickstart/overview)

[开发指南推理模型开发指南](/docs/zh/guides/developer/reasoning)

推理 / 文本

Step 3.5 Flash旗舰推理

最大上下文256K

旗舰级推理模型，专为智能体构建而生。推理深度比肩顶尖闭源模型，同时具备极速响应与稳定可靠的工具调用能力。在通用推理能力基础之上，更擅长复杂项目规划与长程任务执行。

推理
工具调用

相关入口

[模型页
Step 3.5 Flash](/docs/zh/guides/models/step-3.5-flash)

[开发指南
推理模型开发指南](/docs/zh/guides/developer/reasoning)

[API 文档
Chat Completion API](/docs/zh/api-reference/chat/chat-completion-create)

推理 / 文本

Step 3.5 Flash 2603Agent 优化

最大上下文256K

基于 `step-3.5-flash` 针对高频 Agent 场景优化，在保留旗舰推理与工具调用能力的同时，进一步提升 Token 效率与推理速度，并支持切换低推理模式以降低消耗。对 Coding 与 Agent 框架兼容性也做了专项优化。

推理
Agent
低推理模式

相关入口

[模型页Step 3.5 Flash](/docs/zh/guides/models/step-3.5-flash)

[开发指南推理模型开发指南](/docs/zh/guides/developer/reasoning)

[API 文档Chat Completion API](/docs/zh/api-reference/chat/chat-completion-create)

视觉

Step-1o Turbo Vision图像 / 视频理解

最大上下文32K

典型应用场景有社媒发帖文案创作、AI 问答助手、图片与视频理解等。单次请求限制输入最多60张图片，总大小控制在20M 以内，输入视频为小于128MB 的 MP4文件。

图片理解
视频理解
文本生成

相关入口

[模型页
视觉理解大模型](/docs/zh/guides/models/vision)

[开发指南
视频理解开发指南](/docs/zh/guides/developer/video-chat)

[API 文档
Chat Completion API](/docs/zh/api-reference/chat/chat-completion-create)

实时语音

StepAudio 3 Realtime像真人一样聊，也能边想边做

交互模态语音 ↔ 语音

面向实时互动的全双工语音旗舰。融合实时音频理解、自然打断、话权协调、自适应推理、边想边说与 Voice Agent 工具调用，简单问题快速回应，复杂任务边思考边表达，适合智能座舱、智能终端、客服和情感陪伴等场景。

全双工
自适应推理
Voice Agent

相关入口

[模型页
StepAudio 3 Realtime](/docs/zh/guides/models/stepaudio-3-realtime)

[开发指南
实时双向语音开发](/docs/zh/guides/developer/realtime)

[API 文档
Realtime Chat API](/docs/zh/api-reference/realtime/chat)

语音对话

StepAudio 2.5 Chat活人感对话大模型

输出模态仅文本

真正具备"活人感"的对话大模型，仅文本返回。能深度理解复杂语意、机智抛梗，具备行业顶级副语言感知力——读懂语气中的迟疑与轻笑，输出高情商反馈。支持千万人设完全自定义，细颗粒度定义性格特征、专属口癖与情绪边界。

对话
副语言感知
人设自定义

相关入口

[模型页
StepAudio 2.5 Chat](/docs/zh/guides/models/stepaudio-2.5-chat)

[API 文档
Chat Completion API](/docs/zh/api-reference/chat/chat-completion-create)

语音合成

StepAudio 3 TTS真人级的说话表现

模型在音色基底、语调层次、节奏律动与气口停顿上高度贴合人类原生口语范式，能够呈现笑声、咂嘴、迟疑、结巴、重复和改口等真人级口语表现，并根据语义脉络自然表达情绪与语气变化。

真人级表现
低时延流式
综合音频生成

相关入口

[模型页
StepAudio 3 TTS](/docs/zh/guides/models/audio)

[开发指南
语音合成开发指南](/docs/zh/guides/developer/tts)

[API 文档
音频合成 API](/docs/zh/api-reference/audio/create-audio)

语音合成

Step TTS Mini高表现力 TTS

单次输入上限1000 字符

支持中、英、日语、粤语、四川话，提供19种官方音色，兼具出色的音色复刻能力，支持中、英、日语复刻。适合客服外呼、情感陪伴、智能助手语音交互等对发音真人感要求高的场景。

语音生成
音色复刻
情绪风格

相关入口

[模型页
语音大模型](/docs/zh/guides/models/audio)

[开发指南
语音合成开发指南](/docs/zh/guides/developer/tts)

[API 文档
音频合成 API](/docs/zh/api-reference/audio/create-audio)

语音识别

StepAudio 2.5 ASR新一代流式 ASR 旗舰

模型规模4B MTP

阶跃新一代流式语音识别模型，基于 4B MTP 架构，在识别准确率与响应延迟之间取得良好平衡。支持中英文识别与 ITN 文本规范化，适合实时字幕、语音输入、会议记录等对识别速度与准确率均有要求的场景。

高准确率
低延迟
中英双语

相关入口

[模型页
StepAudio 2.5 ASR](/docs/zh/guides/models/stepaudio-2.5-asr)

[API 文档
语音识别（流式返回文本）](/docs/zh/api-reference/audio/asr-sse)

语音识别

StepAudio 2 ASR Pro32B ASR Pro

模型规模32B

32B 参数的 ASR Pro 模型。

大参数

相关入口

[模型页
StepAudio 2.5 ASR](/docs/zh/guides/models/stepaudio-2.5-asr)

[API 文档
语音识别（流式返回文本）](/docs/zh/api-reference/audio/asr-sse)

语音识别

Step ASR实时 / 离线识别

单文件上限100 MB

具有强大的中英文语音识别能力的 ASR 模型，能够自动区分语音和噪音，支持中英文混合语音识别和多种重口音普通话识别。可广泛应用于语音输入、语音控制、会议记录等场景。

语音识别
实时
离线

相关入口

[模型页
语音大模型](/docs/zh/guides/models/audio)

[API 文档
语音识别 API](/docs/zh/api-reference/audio/asr)

实时语音

Step-1o Audio稳定型

单次互动时长30 分钟

提供超低延迟的双向交互语音对话体验，支持中文、英语、重口音普通话输入，支持中、英、日语、粤语和四川话输出。单次互动时长最长30分钟，可处理音频时长最长70分钟。已在智能座舱、智能终端、社交娱乐、情感陪伴、智能客服、金融调解等行业领域落地。

实时交互
工具调用

相关入口

[模型页
实时语音互动模型](/docs/zh/guides/models/stepaudio-3-realtime)

[开发指南
实时双向语音开发](/docs/zh/guides/developer/realtime)

[API 文档
Realtime Chat API](/docs/zh/api-reference/realtime/chat)

**推理**

推理

## 推理模型

推理 / 多模态

Step 5 Preview新一代旗舰基模

最大上下文1M

面向真实任务的新一代旗舰基模，重点覆盖编程与专业知识工作，原生支持文本、图片与视频输入，可结合工具与文档持续推进多步骤任务。API 模型 ID：`step-5-preview`。

知识工作
编程
Agent
图片与视频理解

开始使用

[快速上手发送第一次请求](/docs/zh/quickstart/overview)

[模型总览能力、规格与配置](/docs/zh/guides/models/step-5-preview)

推理 / 多模态

Step 3.7 Flash多模态推理旗舰

最大上下文256K

阶跃星辰旗舰多模态推理模型。在 `step-3.5-flash` 的高速推理与工具调用能力基础上，新增**原生多模态输入能力**，可直接理解图片和视频内容，无需借助视觉 MCP 或额外模型。支持三档推理强度（low/medium/high），是智能体、代码与多模态场景的快且可依赖的模型。

推理
多模态
Agent
图片理解
视频理解

相关入口

[模型页Step 3.7 Flash](/docs/zh/guides/models/step-3.7-flash)

[快速上手多模态快速上手](/docs/zh/quickstart/overview)

[开发指南推理模型开发指南](/docs/zh/guides/developer/reasoning)

推理 / 文本

Step 3.5 Flash旗舰推理

最大上下文256K

旗舰级推理模型，专为智能体构建而生。推理深度比肩顶尖闭源模型，同时具备极速响应与稳定可靠的工具调用能力。在通用推理能力基础之上，更擅长复杂项目规划与长程任务执行。

推理
工具调用

相关入口

[模型页
Step 3.5 Flash](/docs/zh/guides/models/step-3.5-flash)

[开发指南
推理模型开发指南](/docs/zh/guides/developer/reasoning)

[API 文档
Chat Completion API](/docs/zh/api-reference/chat/chat-completion-create)

推理 / 文本

Step 3.5 Flash 2603Agent 优化

最大上下文256K

基于 `step-3.5-flash` 针对高频 Agent 场景优化，在保留旗舰推理与工具调用能力的同时，进一步提升 Token 效率与推理速度，并支持切换低推理模式以降低消耗。对 Coding 与 Agent 框架兼容性也做了专项优化。

推理
Agent
低推理模式

相关入口

[模型页Step 3.5 Flash](/docs/zh/guides/models/step-3.5-flash)

[开发指南推理模型开发指南](/docs/zh/guides/developer/reasoning)

[API 文档Chat Completion API](/docs/zh/api-reference/chat/chat-completion-create)

**视觉**

视觉

## 视觉理解模型

推理 / 多模态

Step 5 Preview新一代旗舰基模

最大上下文1M

面向真实任务的新一代旗舰基模，重点覆盖编程与专业知识工作，原生支持文本、图片与视频输入，可结合工具与文档持续推进多步骤任务。API 模型 ID：`step-5-preview`。

知识工作
编程
Agent
图片与视频理解

开始使用

[快速上手发送第一次请求](/docs/zh/quickstart/overview)

[模型总览能力、规格与配置](/docs/zh/guides/models/step-5-preview)

推理 / 多模态

Step 3.7 Flash多模态推理旗舰

最大上下文256K

阶跃星辰旗舰多模态推理模型。在 `step-3.5-flash` 的高速推理与工具调用能力基础上，新增**原生多模态输入能力**，可直接理解图片和视频内容，无需借助视觉 MCP 或额外模型。支持三档推理强度（low/medium/high），是智能体、代码与多模态场景的快且可依赖的模型。

推理
多模态
Agent
图片理解
视频理解

相关入口

[模型页Step 3.7 Flash](/docs/zh/guides/models/step-3.7-flash)

[快速上手多模态快速上手](/docs/zh/quickstart/overview)

[开发指南推理模型开发指南](/docs/zh/guides/developer/reasoning)

视觉

Step-1o Turbo Vision图像 / 视频理解

最大上下文32K

典型应用场景有社媒发帖文案创作、AI 问答助手、图片与视频理解等。单次请求限制输入最多60张图片，总大小控制在20M 以内，输入视频为小于128MB 的 MP4文件。

图片理解
视频理解
文本生成

相关入口

[模型页
视觉理解大模型](/docs/zh/guides/models/vision)

[开发指南
视频理解开发指南](/docs/zh/guides/developer/video-chat)

[API 文档
Chat Completion API](/docs/zh/api-reference/chat/chat-completion-create)

**语音**

语音

## 语音与实时语音模型

实时语音

StepAudio 3 Realtime像真人一样聊，也能边想边做

交互模态语音 ↔ 语音

面向实时互动的全双工语音旗舰。融合实时音频理解、自然打断、话权协调、自适应推理、边想边说与 Voice Agent 工具调用，简单问题快速回应，复杂任务边思考边表达，适合智能座舱、智能终端、客服和情感陪伴等场景。

全双工
自适应推理
Voice Agent

相关入口

[模型页
StepAudio 3 Realtime](/docs/zh/guides/models/stepaudio-3-realtime)

[开发指南
实时双向语音开发](/docs/zh/guides/developer/realtime)

[API 文档
Realtime Chat API](/docs/zh/api-reference/realtime/chat)

语音对话

StepAudio 2.5 Chat活人感对话大模型

输出模态仅文本

真正具备"活人感"的对话大模型，仅文本返回。能深度理解复杂语意、机智抛梗，具备行业顶级副语言感知力——读懂语气中的迟疑与轻笑，输出高情商反馈。支持千万人设完全自定义，细颗粒度定义性格特征、专属口癖与情绪边界。

对话
副语言感知
人设自定义

相关入口

[模型页
StepAudio 2.5 Chat](/docs/zh/guides/models/stepaudio-2.5-chat)

[API 文档
Chat Completion API](/docs/zh/api-reference/chat/chat-completion-create)

语音合成

StepAudio 3 TTS真人级的说话表现

模型在音色基底、语调层次、节奏律动与气口停顿上高度贴合人类原生口语范式，能够呈现笑声、咂嘴、迟疑、结巴、重复和改口等真人级口语表现，并根据语义脉络自然表达情绪与语气变化。

真人级表现
低时延流式
综合音频生成

相关入口

[模型页
StepAudio 3 TTS](/docs/zh/guides/models/audio)

[开发指南
语音合成开发指南](/docs/zh/guides/developer/tts)

[API 文档
音频合成 API](/docs/zh/api-reference/audio/create-audio)

语音合成

Step TTS Mini高表现力 TTS

单次输入上限1000 字符

支持中、英、日语、粤语、四川话，提供19种官方音色，兼具出色的音色复刻能力，支持中、英、日语复刻。适合客服外呼、情感陪伴、智能助手语音交互等对发音真人感要求高的场景。

语音生成
音色复刻
情绪风格

相关入口

[模型页
语音大模型](/docs/zh/guides/models/audio)

[开发指南
语音合成开发指南](/docs/zh/guides/developer/tts)

[API 文档
音频合成 API](/docs/zh/api-reference/audio/create-audio)

语音识别

StepAudio 2.5 ASR新一代流式 ASR 旗舰

模型规模4B MTP

阶跃新一代流式语音识别模型，基于 4B MTP 架构，在识别准确率与响应延迟之间取得良好平衡。支持中英文识别与 ITN 文本规范化，适合实时字幕、语音输入、会议记录等对识别速度与准确率均有要求的场景。

高准确率
低延迟
中英双语

相关入口

[模型页
StepAudio 2.5 ASR](/docs/zh/guides/models/stepaudio-2.5-asr)

[API 文档
语音识别（流式返回文本）](/docs/zh/api-reference/audio/asr-sse)

语音识别

StepAudio 2 ASR Pro32B ASR Pro

模型规模32B

32B 参数的 ASR Pro 模型。

大参数

相关入口

[模型页
StepAudio 2.5 ASR](/docs/zh/guides/models/stepaudio-2.5-asr)

[API 文档
语音识别（流式返回文本）](/docs/zh/api-reference/audio/asr-sse)

语音识别

Step ASR实时 / 离线识别

单文件上限100 MB

具有强大的中英文语音识别能力的 ASR 模型，能够自动区分语音和噪音，支持中英文混合语音识别和多种重口音普通话识别。可广泛应用于语音输入、语音控制、会议记录等场景。

语音识别
实时
离线

相关入口

[模型页
语音大模型](/docs/zh/guides/models/audio)

[API 文档
语音识别 API](/docs/zh/api-reference/audio/asr)

实时语音

Step-1o Audio稳定型

单次互动时长30 分钟

提供超低延迟的双向交互语音对话体验，支持中文、英语、重口音普通话输入，支持中、英、日语、粤语和四川话输出。单次互动时长最长30分钟，可处理音频时长最长70分钟。已在智能座舱、智能终端、社交娱乐、情感陪伴、智能客服、金融调解等行业领域落地。

实时交互
工具调用

相关入口

[模型页
实时语音互动模型](/docs/zh/guides/models/stepaudio-3-realtime)

[开发指南
实时双向语音开发](/docs/zh/guides/developer/realtime)

[API 文档
Realtime Chat API](/docs/zh/api-reference/realtime/chat)


# Model Lab
Source: https://platform.stepfun.com/docs/zh/guides/models/model-lab



Model Lab 是阶跃星辰的实验性模型开放实验室。开发者可以在这里体验到阶跃星辰所提供的最新模型；Model Lab 的模型将免费开放给开发者使用。**需要注意，Model Lab 中的模型在快速迭代中，建议用于测试环境及本地开发使用，不建议用于生产环境。**

## 模型上新：Step GUI

`step-gui` 是针对图形界面交互（GUI）相关任务设计的多模态视觉大模型。通过视觉理解、步骤推理和动作执行等闭环能力，能够像人类一样在各类 GUI 界面上完成连续多步骤任务。

### 端到端的复杂任务处理能力

模型具备强大的视觉感知、理解能力，包括：

* 精准视觉解析：识别并理解通用 UI 控件、布局结构、交互逻辑以及内容语义等；
* 类人动作推理：支持点击、输入、滑动、长按、拖拽等基本原子操作；
* 跨界面、跨 app 连续任务规划：无需预先定义执行工作流即可自动完成完整端到端任务；
  可支持的代表性任务包括：
* 生活场景：刷 feed 流、订机票、点外卖、回复社媒消息、比价等；
* 办公场景：执行自动化流程、跨软件信息整理、数据操作等；
  `step-gui` 的能力可作为无 API 可用的智能体任务场景中的“通用双手”，为更广泛的其他智能体提供可靠的支持，打破有脑无手的困局，助力各种智能体成为用户日常生活工作中的“全能助手”；

### 高准确率的单步理解

除了端到端的多步骤复杂任务，`step-gui` 在单步级别的感知与推理能力上同样表现突出，能实现稳定、可靠的单步决策：

* 当前 GUI 屏幕的即时理解：能够基于当前 GUI 屏幕内容进行快速、准确的语义理解，包括 UI 控件识别、可交互区域判断、页面状态识别等；
* 精准下一步推理：在任意可见页面上直接给出高准确率的下一步动作推理；

### 人机协同交互能力

在探索更自然、更灵活的新一代“可对话、可协同、可纠错”人机交互范式时，`step-gui` 的模型能力可与其他智能体实现深度协同：

* 丰富的交互行为：模型支持等待加载、向用户发起追问、主动向用户报告执行结果等可控操作；在高敏感环节（如涉及金钱操作的支付转账等，模型会主动终止任务，并报告给用户）
* 实时人机协同：在与其他智能体或系统深度集成的情况下，`step-gui` 支持用户随时打断、变更意图等；

### 异常处理与纠错能力

`step-gui` 可以识别并处理真实环境中的常见异常，包括但不限：

* 即时通知消息
* 网络/加载失败
* 页面跳转异常
* 文本或控件动态变化
* 意外弹窗（系统弹窗、隐私协议、升级提示）
* ....等等
  在实际任务执行过程中动态观察界面变化，并在进入任务非预期页面时，自动恢复、重新定位并继续任务；

## API 操作指南

为了方便用户更好地体验 GUI 模型能力，我们准备了模型的开发使用指南供大家参考 [`step-gui` API 小白使用指南](https://ai.feishu.cn/wiki/BfVHwghPdiyp2ckS3HfcJZAmnsc?from=from_copylink)。同时为了方便用户快速实现模型能力调用和功能开发，我们推出了 **`step-gui` MCP**，将 GUI 操作功能封装为标准化的 MCP 工具，使开发者能够更快速地使用 `step-gui` 作为执行 tool（sub agent/agent as a tool）被大脑作为工具委派。通过统一接口协议，可随时调用，详情见 [`step-gui` MCP 小白使用指南](https://ai.feishu.cn/wiki/OBIdw67cLiFKbTkGQuwcdbjbnUe?from=from_copylink)。

### 场景案例

比价采购

视频效果

<video />

任务描述 / Prompt看到这个图了吗？帮我去京东淘宝和拼多多搜同款比个价。每次报告搜索结果第一项即可。

![](https://static-openapi.stepfun.com/static/platform-docs/resource/1765861595877_gbk4mt.png)

比价选票

视频效果

<video />

任务描述 / Prompt我计划16号到20号 要去上海出差，你在需要：\
1\. 分别帮我去携程 查一下16号早上从北京去上海，20晚上返程的飞机和高铁票，报告最便宜的给我。嘱咐 agent 报告，飞机航班号或车次，预期出发到达时间和价格。给 agent 的指令应该明确筛选条件。\
2\. 查询一下，上海桔子酒店徐汇区体育场店，16-20号的住宿价格。\
3\. 编辑一条请假消息去飞书发给王卓宇，内容需包含差旅预算范围。

旅行规划

视频效果

<video />

任务描述 / Prompt我计划21号去上海玩，帮我去美团找一下，上海外滩附近的餐厅。要求3公里以内，销量最多的一家，记下来。我计划请朋友去那里聚聚。之后帮我在高德地图将其分别收藏。看下明天疯狂动物城2 最早的场次，记录电影院和放映时间信息。将查到的内容汇总后，以得体的口吻，通过飞书发给王卓宇。

使用过程中，欢迎您通过[表单](https://wvixbzgc0u7.feishu.cn/share/base/form/shrcn6ayHJgQothPXTCIfB4UxRg)提交您的 Good Case，被选中的 Good Case 我们将会给予现金激励。

## 模型列表

| 模型 | 模型介绍 | 可用 API |
| - | - | - |
| `step-gui` | 该模型专可处理长步骤复杂任务、模糊任务、个性化推荐任务以及跨 app 任务（比如比价任务），具备强泛化性（能在陌生界面中保持稳定表现）、高可靠性和强可控性。 | [新手指南](https://ai.feishu.cn/wiki/BfVHwghPdiyp2ckS3HfcJZAmnsc?from=from_copylink) [创建 Chat](/docs/zh/api-reference/chat/chat-completion-create) |

> [!NOTE]
>
> `step-2x-large` 已于 2026 年 10 月 10 日下线，文生图、图生图接口已同步停止服务。详见[图像模型下线公告](/docs/zh/announcements/image-model-retirement)。

## 模型限制

* Model Lab 内的模型将限制支持并发为 1 ；
* Model Lab 内的模型将不保证始终在线，并会在运营期结束后下线。
* 如需更多资源或希望在生产环境中使用，可联系 [platform@stepfun.com](mailto:platform@stepfun.com)


# Step 3.5 Flash
Source: https://platform.stepfun.com/docs/zh/guides/models/step-3.5-flash



`step-3.5-flash` 是阶跃星辰的旗舰语言推理模型。具备顶尖推理能力与快速可靠的执行能力，能够完成复杂任务的分解与计划，可快速可靠地调用工具执行任务，胜任逻辑推理、数学、软件工程、深度研究等各种复杂任务。基于 196B 总参数 / 11B 激活参数的稀疏 MoE 架构。

## 关键信息

> **模型类型**
>
> 稀疏 MoE 架构\
> 196B 总参数 / 11B 激活参数

> **上下文长度**
>
> 256K tokens

> **场景定位**
>
> 高速推理 + 工具调用\
> 智能体与代码任务优化

## 核心能力

> **🚀 高速推理**
>
> 稀疏 MoE 架构带来高吞吐与低延迟，适合实时智能体工作流与高频调用场景。

> **🛠️ 工具调用**
>
> 可靠的 `tools` / `tool_choice` 调用能力，支持多步任务分解与计划执行。

> **🧠 复杂推理**
>
> 胜任逻辑推理、数学、软件工程、深度研究等复杂任务，是 Agent 长链路推理的稳定底座。

## 模型变体

> **step-3.5-flash**
>
> **基础版本**：通用推理与工具调用，适合多数 Agent 与复杂任务场景。

> **step-3.5-flash-2603**
>
> **Agent 优化版**：基于 step-3.5-flash 针对高频 Agent 场景优化，Token 效率提升、推理速度更快，可切换至低推理模式大幅降低 Token 消耗，对 Coding 与 Agent 框架兼容性也做了专项优化。支持 `reasoning_effort` 字段（`low` / `high`）。

## API 端点

> **[Chat Completion](/docs/zh/api-reference/chat/chat-completion-create)**
>
> `POST /v1/chat/completions`\
> OpenAI 协议兼容，支持流式与工具调用。

> **[Messages](/docs/zh/api-reference/chat/messages-create)**
>
> `POST /v1/messages`\
> Anthropic 协议兼容，可直接复用 Anthropic SDK。

## 定价

| 计费项 | 单价（每百万 tokens） |
| :- | :- |
| 输入（缓存命中） | ¥0.14 |
| 输入（缓存未命中） | ¥0.7 |
| 输出 | ¥2.1 |

[查看完整定价详情 →](/docs/zh/guides/pricing/details)

## 快速上手

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/chat/completions \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "step-3.5-flash",
    "messages": [
      {"role": "user", "content": "你好，请介绍一下你自己"}
    ]
  }'
```

**Python (OpenAI SDK)**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

response = client.chat.completions.create(
    model="step-3.5-flash",
    messages=[
        {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
)

print(response.choices[0].message.content)
```

## 相关阅读

> **[推理模型开发指南](/docs/zh/guides/developer/reasoning)**
>
> 了解推理模型在复杂任务、工具调用和长上下文中的推荐用法。

> **[Step 3.7 Flash](/docs/zh/guides/models/step-3.7-flash)**
>
> 在 `step-3.5-flash` 高速推理能力基础上新增原生图片与视频理解的旗舰多模态推理模型。


# Step 3.7 Flash
Source: https://platform.stepfun.com/docs/zh/guides/models/step-3.7-flash



阶跃星辰的旗舰多模态推理模型。基于 198B 总参数 / 11B 激活参数的稀疏 MoE 架构，原生支持图片和视频理解。

## 关键信息

> **模型类型**
>
> 稀疏 MoE 架构\
> 198B 总参数 / 11B 激活参数

> **上下文长度**
>
> 256K tokens

> **场景定位**
>
> 高速推理 + 原生多模态\
> 智能体与代码任务优化

## 核心能力

> **👁️ 原生多模态**
>
> 原生支持图片和视频理解，在 Agent 框架中无需额外视觉模型，直接拖入对话框即可使用。

> **🚀 高速推理**
>
> 稀疏 MoE 架构带来高吞吐与低延迟，适合实时智能体工作流与高频调用场景。

> **🛠️ 工具调用**
>
> 可靠的工具调用能力，支持多步任务分解与计划执行。

> **🎯 高完成度复杂任务**
>
> 面向代码生成、方案规划、视觉转工作流等复杂任务，单次调用即可产出更完整的计划、代码与文档，减少中途反复调试。

## 推理强度

`step-3.7-flash` 支持三档推理强度，可根据任务复杂度灵活选择：

| 推理强度 | 适用场景 |
| :- | :- |
| `low` | 简单问答、摘要、改写、信息抽取 |
| `medium` | 默认推荐，适合一般推理和多步骤任务 |
| `high` | 复杂推理、数学、规划、代码分析 |

> [!NOTE]
>
> Chat Completions API 使用 `reasoning_effort` 控制推理强度；Messages API 使用 `output_config.effort`。基础调用示例见[快速开始](/docs/zh/quickstart/overview)。

## 开始使用

> **[快速开始](/docs/zh/quickstart/overview)**
>
> 从图片、视频、本地文件和推理强度控制开始接入。

> **[场景示例](/docs/zh/guides/models/step-3.7-flash-cookbook)**
>
> 查看白板转计划、图表转数据、票据转表格等任务模板。

> **[手机操作 Agent](/docs/zh/guides/models/step-3.7-flash-mobile-agent)**
>
> 通过 GELab-Zero 连接 Android 真机，让模型基于屏幕截图规划操作。

> **[Chat Completion](/docs/zh/api-reference/chat/chat-completion-create)**
>
> `POST /v1/chat/completions`\
> OpenAI 协议兼容，支持流式与工具调用。

> **[Messages](/docs/zh/api-reference/chat/messages-create)**
>
> `POST /v1/messages`\
> Anthropic 协议兼容，可直接复用 Anthropic SDK。

## 定价

| 计费项 | 单价（每百万 tokens） |
| :- | :- |
| 输入（缓存命中） | 0.27 元 |
| 输入（缓存未命中） | 1.35 元 |
| 输出 | 8.1 元 |

## 框架适配

`step-3.7-flash` 可稳定接入主流 Coding 与 Agent 工具，适合在终端、IDE 和 Agent 工作流中完成代码生成、文件编辑与复杂任务协作。

[查看 Step Plan 接入指南 →](/docs/zh/step-plan/quick-start)

## 相关阅读

> **[推理模型开发指南](/docs/zh/guides/developer/reasoning)**
>
> 了解推理模型在复杂任务、工具调用和长上下文中的推荐用法。

> **[图片理解](/docs/zh/guides/developer/image-chat)**
>
> 深入了解图片理解的 API 参数、detail 设置和最佳实践。

> **[视频理解](/docs/zh/guides/developer/video-chat)**
>
> 深入了解视频理解的 API 参数、文件限制和常见问题。

> **[Step 3.5 Flash](/docs/zh/guides/models/step-3.5-flash)**
>
> 了解不含多模态能力的纯文本推理模型。


# Step 3.7 Flash 场景示例
Source: https://platform.stepfun.com/docs/zh/guides/models/step-3.7-flash-cookbook



`step-3.7-flash` 可以把图片、视频和文本放在同一次对话中理解，适合把现实世界里的视觉信息转成计划、表格、代码草稿或问题诊断。本文收集一些常见场景的 prompt 模板，帮助您快速判断任务该怎么组织输入和输出。

> [!NOTE]
>
> 这些示例侧重任务设计和输出格式。代码调用方式请先参考[快速开始](/docs/zh/quickstart/overview)；图片、视频的细节参数请参考 [图片理解](/docs/zh/guides/developer/image-chat) 和 [视频理解](/docs/zh/guides/developer/video-chat)。

## 使用建议

* 先明确输出格式：让模型输出 Markdown 表格、JSON、CSV 行或任务清单。
* 对关键字段要求保留证据：例如金额、日期、图表数值、任务 owner，需要让模型说明来源或不确定项。
* 不要让模型猜缺失信息：看不清、无法判断的字段应输出 `null`、空字符串或“无法确认”。
* 涉及财务、报销、合同、医疗等高风险数据时，需要人工复核。

## 白板转计划

适合处理会议白板、便利贴墙、手写流程图、项目讨论照片。目标是把松散信息转成可执行计划，而不是逐字转录。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
这是一张项目讨论白板照片。请完成：
1. 提取白板中的主要议题和结论
2. 整理成一份项目计划，包含目标、关键里程碑、风险和待确认事项
3. 生成任务清单，字段包括：任务、负责人（如无法判断则为 null）、优先级、依赖项、建议截止时间
4. 单独列出识别不清或需要人工确认的内容
```

推荐输出：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
## 项目计划
## 任务清单
## 风险与依赖
## 待确认事项
```

## 图表转数据

适合处理报告截图、仪表盘截图、柱状图、折线图、饼图等。目标是把图表内容转成结构化数据，并保留不确定性。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请从这张图表中提取数据，并按 JSON 返回：
{
  "chart_type": "",
  "title": "",
  "x_axis": "",
  "y_axis": "",
  "series": [
    {
      "name": "",
      "points": [
        {"label": "", "value": null, "confidence": "high|medium|low"}
      ]
    }
  ],
  "insights": [],
  "uncertain_fields": []
}

要求：
- 如果数值只能估算，请把 confidence 标为 low 或 medium
- 不要编造图中没有的信息
- 如果坐标轴、单位或图例看不清，请写入 uncertain_fields
```

> [!NOTE]
>
> 图表截图中的数值可能受分辨率、压缩和坐标轴比例影响。需要精确计算时，应优先使用原始数据源；模型提取结果适合作为初稿或人工录入辅助。

## 票据转表格

适合处理收据、发票、报销单、购物小票等。目标是转成可直接写入表格的行数据，便于复制进表格或继续写入系统。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请从这张票据图片中提取结构化信息，按 JSON 返回：
{
  "merchant": "",
  "date": "",
  "currency": "",
  "total_amount": null,
  "tax_amount": null,
  "items": [
    {
      "name": "",
      "quantity": null,
      "unit_price": null,
      "amount": null
    }
  ],
  "payment_method": "",
  "uncertain_fields": []
}

要求：
- 金额必须来自票据画面，不要自行推断
- 看不清的字段填 null，并写入 uncertain_fields
- 保留原始币种和日期格式
```

如果您希望直接粘贴到电子表格，可以让模型改成 CSV：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请把票据中的明细输出为 CSV，列为：
merchant,date,item_name,quantity,unit_price,amount,currency,confidence
```

## 截图生成代码

适合处理网页、移动端界面、组件截图和设计稿截图。目标是得到可继续修改的 HTML / React / Tailwind 初稿。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
这是一张网页界面截图。请用 React + Tailwind CSS 复刻这个页面。

要求：
1. 先描述页面结构、布局和主要视觉元素
2. 再给出可运行的 React 组件代码
3. 使用语义化命名，不要依赖截图中的真实品牌资产
4. 对无法确认的图片或图标，用占位元素表示
5. 保持移动端和桌面端都有合理布局
```

> [!TIP]
>
> 如果截图里包含大量文字，建议先让模型做一次“页面结构分析”，再让它生成代码。这样更容易减少布局遗漏。

## 录屏问题诊断

适合处理软件操作录屏、Bug 复现视频、App 使用路径、客服排障录屏等。目标是让模型还原用户动作、定位异常点并给出排查建议。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
这是一个软件操作录屏。请分析：
1. 用户按时间顺序做了哪些操作
2. 哪一步开始出现异常
3. 异常表现是什么
4. 可能原因有哪些，请按可能性排序
5. 给出排查步骤和建议修复方向

请按 Markdown 输出，并把无法确认的内容单独列为“需要补充的信息”。
```

推荐输出：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
## 操作时间线
## 异常点
## 可能原因
## 排查步骤
## 需要补充的信息
```

## 多图对比

适合比较设计改版前后、商品图片差异、截图中的 UI 状态差异、文档扫描页差异等。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请比较这几张图片，输出：
1. 相同点
2. 差异点，按视觉布局、文字内容、数据数值、状态变化分类
3. 可能影响
4. 需要人工复核的差异

如果某个差异无法确认，请明确说明原因，不要猜测。
```

## 结构化输出建议

当您需要把结果接入程序或表格时，建议显式要求 JSON 或 CSV，并说明空值策略：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请只返回合法 JSON，不要返回 Markdown。
如果字段无法从图片中确认，请填 null。
如果存在识别不确定的字段，请把字段名和原因写入 uncertain_fields。
```

如果下游程序需要稳定解析 JSON，可以配合 `response_format` 开启 JSON Mode。具体用法见 [JSON Mode 使用建议](/docs/zh/guides/developer/json-mode) 和 [Chat Completions API](/docs/zh/api-reference/chat/chat-completion-create#请求参数)。

对于需要人工复核的任务，可以让模型同时给出 `confidence`：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "field": "total_amount",
  "value": 128.5,
  "confidence": "medium",
  "evidence": "票据底部 Total 一行"
}
```

## 下一步

> **[快速开始](/docs/zh/quickstart/overview)**
>
> 学习图片、视频、Base64 和 Files API 的基础调用方式。

> **[Chat Completions API](/docs/zh/api-reference/chat/chat-completion-create)**
>
> 查看 `messages`、`image_url`、`video_url`、`reasoning_effort` 等参数。

> **[手机操作 Agent](/docs/zh/guides/models/step-3.7-flash-mobile-agent)**
>
> 通过 GELab-Zero 连接 Android 真机，让模型规划手机操作。


# 手机操作 Agent
Source: https://platform.stepfun.com/docs/zh/guides/models/step-3.7-flash-mobile-agent



`step-3.7-flash` 的多模态理解能力可以用于手机 GUI Agent 场景：模型读取手机截图、任务描述和历史轨迹，判断下一步动作，再由运行框架把动作执行到 Android 真机上。

当前推荐使用 [GELab-Zero](https://github.com/stepfun-ai/gelab-zero) 跑通这类任务。GELab-Zero 是一个面向 Android 手机上的 GUI Agent 运行框架，负责连接手机、采集截图、调用多模态模型、执行动作并记录过程。

> [!NOTE]
>
> 手机操作 Agent 涉及真机、ADB、模型调用和本地运行环境，适合作为进阶场景使用。第一次接入建议先完成[快速开始](/docs/zh/quickstart/overview)，确认 API Key 与模型调用正常。

## 工作流程

GELab-Zero 将模型决策和手机执行串成一条完整链路：

1. 您给 Agent 一个自然语言任务。
2. 电脑通过 ADB 连接 Android 手机并获取截图。
3. 框架把当前截图、历史轨迹和任务描述发给多模态模型。
4. 模型输出下一步动作，例如 `AWAKE`、`CLICK`、`TYPE`、`SLIDE`。
5. 框架把动作真正执行到手机上。
6. 每一步截图、动作和模型输出都会被记录。
7. 任务结束后，可以通过可视化页面按 `Session ID` 回看整个过程。

## 前置准备

运行前需要准备：

* 一台 Android 手机，并开启开发者模式和 USB 调试
* ADB / platform-tools
* Python 3.12+
* GELab-Zero 仓库代码与依赖
* 可用的 Step API Key

手机需要先通过 USB 连接电脑，并确认 ADB 可以识别：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adb devices
```

如果设备状态显示为 `unauthorized`，需要在手机上允许 USB 调试授权。

## 安装 GELab-Zero

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
git clone https://github.com/stepfun-ai/gelab-zero
cd gelab-zero
pip install -r requirements.txt
```

建议从 GELab-Zero 项目根目录执行后续命令。

## 配置模型服务

GELab-Zero 的模型调用会读取 `model_config.yaml`，并通过 OpenAI 兼容接口发起请求。先在 `model_config.yaml` 中配置 Step API：

```yaml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
stepfun:
  api_base: "https://api.stepfun.com/v1"
  api_key: "YOUR_STEP_API_KEY"
```

然后在 `examples/run_single_task_state_compress.py` 中把模型 provider 指向 `stepfun`，并使用 `step-3.7-flash`：

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
local_model_config = {
    "task_type": "parser_0920_summary_adv_state_compress",
    "model_config": {
        "model_name": "step-3.7-flash",
        "model_provider": "stepfun",
        "args": {
            "temperature": 1,
            "top_p": 0.95,
            "frequency_penalty": 0.05,
            "max_tokens": 32768,
        },
    },
    "config": {
        "enable_state_compression": True,
        "state_compression_interval": 10,
        "state_compression_recent_window": 10,
        "state_compression_max_field_items": 10,
    },
    "max_steps": 400,
    "delay_after_capture": 3,
    "debug": False,
}
```

> [!NOTE]
>
> GELab-Zero 的极简运行指南建议 `temperature` 保持为 `1`，不要改成 `0.1` 或 `0.5`。长轨迹任务建议开启 state compression，避免历史上下文持续膨胀。

## 运行手机任务

先确认手机仍然在线：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adb devices
```

然后运行单个任务：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
python examples/run_single_task_state_compress.py \
  --task "帮我看看微博文娱热搜上有哪些内容，总结一下给我"
```

如果电脑连接了多台设备，建议显式指定设备：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
python examples/run_single_task_state_compress.py \
  --device-id AN2CVB4C28000731 \
  --task "帮我看看微博文娱热搜上有哪些内容，总结一下给我"
```

运行后终端会打印 `Session ID`、每一步耗时、当前动作和最终总耗时。任务日志默认写入：

* `running_log/server_log/os-copilot-local-eval-logs/traces`
* `running_log/server_log/os-copilot-local-eval-logs/images`

## 查看执行过程

GELab-Zero 提供本地可视化页面，用于查看每一步截图、模型思考和动作结果：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
streamlit run visualization/pages/main_page.py \
  --server.address 127.0.0.1 \
  --server.port 33503
```

启动后打开：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
http://localhost:33503
```

从任务终端复制 `Session ID`，粘贴到页面输入框后即可回看完整执行轨迹。

## 参考

> **[GELab-Zero 极简运行指南](https://github.com/stepfun-ai/gelab-zero/blob/main/%E6%9E%81%E7%AE%80%E8%BF%90%E8%A1%8C%E6%8C%87%E5%8D%97_CN.md)**
>
> 查看 Android 真机配置、State Compress 入口、推荐参数和可视化页面说明。


# Step 5 Preview
Source: https://platform.stepfun.com/docs/zh/guides/models/step-5-preview



**Step 5 Preview 是 StepFun 面向真实任务的新一代旗舰基模**，重点覆盖编程与专业知识工作。模型原生支持文本、图片和视频输入，提供 **1M tokens 上下文窗口**，适合需要处理大量信息、调用工具，并持续推进到交付结果的任务。

## 规格速览

| 规格 | Step 5 Preview |
| :- | :- |
| **模型 ID** | `step-5-preview` |
| **上下文窗口** | **1M tokens** |
| 输入类型 | 文本、图片、视频 |
| 输出类型 | 文本 |
| 最大输入 | **1M tokens** |
| 最大输出 | **64k tokens** |

## 核心能力

> **长上下文理解与推理**
>
> 在 1M tokens 上下文中，结合长文档、多份材料和对话历史进行分析。
>
> **典型任务**：跨文档问答、研究资料整理。

> **编程与软件工程**
>
> 覆盖多种编程语言和工程任务，配合工具推进开发、修改与验证。
>
> **典型任务**：问题排查、代码修改、测试编写。

> **多步骤 Agent 任务**
>
> 通过应用提供的工具检索信息、处理文档，持续推进多步骤工作。
>
> **典型任务**：深度研究、分析报告。

> **多模态理解**
>
> 结合图片、视频与文字，提取和分析多模态信息。
>
> **典型任务**：图表分析、截图问答、视频总结。

## 适用场景

* **软件开发**：结合代码、依赖信息和错误日志，完成问题定位、代码修改与测试建议。
* **长文档处理**：在较长上下文中整理多份材料，执行信息抽取、归纳和交叉核对。
* **研究与分析**：配合搜索、代码执行或文档工具，拆解任务并形成结构化结果。
* **多模态理解**：分析截图、图表和视频内容，并按照指定格式输出结论。

工具、搜索和代码执行能力由接入模型的应用提供，不代表模型会直接访问本地环境或外部服务。

## 输入与输出

### 图片与视频输入

| 项目 | 支持范围 |
| :- | :- |
| 图片传入方式 | URL 或 Base64 |
| 图片格式 | JPG/JPEG、PNG、WebP、静态 GIF |
| 单次数量 | 最多 60 张图片 |
| 图片细节级别 | `low`、`high` |
| 视频传入方式 | URL、Base64 或 Files API 的 `stepfile://` 引用 |
| 视频格式 | MP4、QuickTime、Matroska |
| URL 视频限制 | 单个 MP4 文件小于 128MB，时长建议小于 5 分钟 |

图片和视频请求示例见[快速开始](/docs/zh/quickstart/overview)，完整限制见[图片理解](/docs/zh/guides/developer/image-chat)和[视频理解](/docs/zh/guides/developer/video-chat)。

## 功能与配置

| 功能／配置项 | 支持范围／参数 | 使用指南 |
| :- | :- | :- |
| 流式输出 | 支持 | [流式输出](/docs/zh/guides/developer/stream) |
| 工具调用 | 支持 | [工具调用](/docs/zh/api-reference/tool-call) |
| 结构化输出 | 支持 JSON Mode 与 JSON Schema | [JSON Mode](/docs/zh/guides/developer/json-mode) |
| 推理强度 | 支持 `low`、`medium`、`high`；Chat Completions API 使用 `reasoning_effort`，Messages API 使用 `output_config.effort` | [推理模型](/docs/zh/guides/developer/reasoning) |
| 提示缓存 | 支持 | [提示缓存](/docs/zh/guides/developer/prompt-cache) |
| 输出长度 | `max_tokens` 默认为 `INF`，不作限制，由模型自动决定 | [Chat Completions API](/docs/zh/api-reference/chat/chat-completion-create) |

## 接入方式

1. 在 StepFun 开放平台创建 API Key。
2. 打开[快速开始](/docs/zh/quickstart/overview)，选择 Step 5 Preview，再切换文本对话、图片理解或视频理解示例。
3. 使用 cURL 或 Python 发送请求，并从 `choices[0].message.content` 读取结果。
4. 上线前根据 [API 参考](/docs/zh/api-reference/chat/chat-completion-create)补齐超时、重试、错误处理和密钥管理。

> **[快速开始](/docs/zh/quickstart/overview)**
>
> 查看文本、图片与视频请求示例。

> **[Chat Completions API](/docs/zh/api-reference/chat/chat-completion-create)**
>
> 查看完整请求参数、响应字段和用量信息。

> **[Claude Code 接入](/docs/zh/guides/developer/integrations/claude-code)**
>
> 配置 Step Plan，并开启 1M 上下文。

## 定价与限速

Step 5 Preview 按实际输入和输出 token 用量计费。输入与输出单价见 [API 定价](/docs/zh/guides/pricing/details#文本与多模态模型)，账号限速见 [API 速率限制](/docs/zh/guides/pricing/rate-limits)。

## 更多信息

[快速开始](/docs/zh/quickstart/overview) · [API 参考](/docs/zh/api-reference/chat/chat-completion-create) · [Claude Code 接入](/docs/zh/guides/developer/integrations/claude-code) · [API 定价](/docs/zh/guides/pricing/details)


# Step Router V1 智能路由
Source: https://platform.stepfun.com/docs/zh/guides/models/step-router



`step-router-v1` 是阶跃星辰为 [Step Plan](/docs/zh/step-plan/overview) 通道提供的智能路由模型。只需在 `model` 字段填入 `step-router-v1`，系统会根据每次请求的特征在 `deepseek-v4-pro` 与 `step-3.7-flash` 之间自动调度：复杂推理与长链路决策交由 `deepseek-v4-pro` 处理，高频与结构化执行交由 `step-3.7-flash` 承载，从而在控制整体成本的同时维持复杂任务的输出质量，开发者无需自行实现分流逻辑。

> [!NOTE]
>
> 本模型仅在 [Step Plan](/docs/zh/step-plan/overview) 通道（`https://api.stepfun.com/step_plan/v1`）可用。

## 关键信息

> **模型类型**
>
> 双引擎智能路由：deepseek-v4-pro + step-3.7-flash

> **调度依据**
>
> 按请求特征自动路由，参考消息轮数、输入量、工具数量

> **可用通道**
>
> 仅 Step Plan 通道；支持 OpenAI 与 Anthropic 协议

## 底层引擎

`step-router-v1` 由以下两个引擎组成，系统按请求特征自动路由到其中之一：

> **deepseek-v4-pro**
>
> **决策引擎**：1M 上下文、250K 最大输出，面向复杂推理与长链路 Agent 决策，支持 `thinking`、`tools` / `tool_choice` 等字段透传。请求被判定为复杂或高不确定性时路由到此引擎。

> **step-3.7-flash**
>
> **执行引擎**：阶跃星辰旗舰多模态推理模型，198B 总参数 / 11B 激活参数的稀疏 MoE 架构，256K 上下文，原生支持图片与视频理解，支持三档推理强度。承载多数高频与结构化任务，是 `step-router-v1` 的默认执行模型。

## 路由说明

系统根据请求特征（消息轮数、输入 token 量、工具数量等）自动判定复杂度并选择引擎，无需在请求中额外指定。调用方式、字段约束与直接调用底层模型一致，仅 `model` 字段填 `step-router-v1`。

> [!NOTE]
>
> `step-router-v1` 在 Step Plan 通道下的字段差异（`max_tokens` 上限、不支持的内容类型等）详见 [Messages API](/docs/zh/api-reference/chat/messages-create) 中 **step-router-v1 字段限制（仅适用于该模型）**，以及 [Chat Completion API](/docs/zh/api-reference/chat/chat-completion-create) 中 **Step Plan 通道：DeepSeek 引擎字段差异**。

## 定价

按实际命中的底层引擎计费：命中 `deepseek-v4-pro` 按 `deepseek-v4-pro` 计费，命中 `step-3.7-flash` 按 `step-3.7-flash` 计费。计费金额最终折算为 [Step Plan](/docs/zh/step-plan/overview) 总额度消耗。

## 开始使用

> **[开发指南](/docs/zh/guides/developer/step-router)**
>
> 适用场景、流式与非流式调用示例、最佳实践。

> **[Step Plan 推理模型接入](/docs/zh/step-plan/integrations/reasoning-api)**
>
> base\_url、SDK 示例与 Step Router 切换方式。

> **[Chat Completion API](/docs/zh/api-reference/chat/chat-completion-create)**
>
> OpenAI 协议端点参数与响应说明。


# StepAudio 3 ASR
Source: https://platform.stepfun.com/docs/zh/guides/models/stepaudio-3-asr



StepAudio 3 ASR 系列提供高准确率、低延迟的语音转写能力。

StepAudio 3 ASR Max 是阶跃星辰迄今规模最大的 ASR 模型，以大语言模型为语义底座，将高精度声学建模与大语言模型的上下文理解、知识储备和推理能力深度融合，让语音识别从“辨认声音”进一步走向“理解语境”。[语音体验中心](https://www.stepfun.com/studio/audio?tab=speech-recognition)

## 模型信息

| 项目 | 内容 |
| :- | :- |
| 输入 | 音频 |
| 输出 | 增量与最终文本 |
| 协议 | HTTP + SSE |
| 计费 | 2.8 元 / 小时 |

## 核心能力

* **语境理解**：结合音频信号、上下文关系和领域知识，提升人名、地名、药品名、技术术语和同音词等复杂内容的识别准确率。
* **跨语言、跨场景识别**：覆盖中文、英文、方言、中英混说、长音频和垂类领域等场景，相较上一代模型均有提升。
* **专业领域识别**：在体育、医药、化工、汽车、法律、金融、编程开发等 20+ 垂类场景中，能够结合领域知识理解专业表达。
* **复杂声音处理**：支持悄悄话、极快语速、含糊连读、拖沓发音、环境噪声、歌唱和背景音乐等真实世界音频。
* **歌曲与歌声转写**：支持处理清唱、伴奏演唱等复杂歌声场景，直接转写歌曲内容。
* **低误识别**：无语音测试准确率达到 99%，可减少环境声、背景音乐和静音片段引发的错误转写。

## 评测亮点

* **上下文推理**：错误率为 0.57%，相比 StepAudio 2.5 ASR 的 1.59% 降低 64.2%；相比豆包 ASR 2.0 的 1.00% 降低 43.0%。
* **垂类专名**：覆盖体育、医药、化工、汽车、法律、金融和编程开发等 20+ 领域，平均错误率为 3.81%。
* **相较上一代的全面跃升**：中文、英文通用平均错误率分别降低 9.3% 和 25.0%，方言降低 22.3%，垂类领域降低 42.1%，中英混说降低 27.9%。
* **长上下文能力**：上下文推理错误率相比上一代降低 64.2%。
* **对比主要商业模型**：相比豆包 ASR 2.0，中文通用、英文、重口音、长音频和上下文推理平均错误率分别降低 18.6%、60.4%、23.3%、40.3% 和 43.0%。
* **真实复杂声音**：AISHELL-6 悄悄话测试 CER 为 3.97%，优于上一代的 5.36%；在极快语速、含糊、连读和拖沓等测试中保持稳定识别能力。

## 应用场景

StepAudio 3 ASR Max 将通过 API 提供服务，可用于会议纪要、视频字幕、直播内容理解、智能客服、车载交互、医疗记录、金融服务和专业内容生产等场景，让语音内容更准确地被理解、检索和使用。

## API 端点

> **[语音识别（流式返回文本）](/docs/zh/api-reference/audio/asr-sse)**
>
> `POST /v1/audio/asr/sse`\
> 一次性提交音频，SSE 流式返回识别文本。

## 相关资源

> **[语音大模型概述](/docs/zh/guides/models/audio)**
>
> 返回 Audio 3 系列模型概述。

> **[完整定价详情](/docs/zh/guides/pricing/details)**
>
> 查看语音、文本、图像等全部模型的计费规则。

> **[语音识别 API](/docs/zh/api-reference/audio/asr-sse)**
>
> 查看语音识别请求参数、响应事件和接口说明。

> **[Demo 与体验中心](https://www.stepfun.com/studio/audio?tab=speech-recognition)**
>
> 在线体验 StepAudio 3 ASR 的识别能力。


# StepAudio 3 Gen
Source: https://platform.stepfun.com/docs/zh/guides/models/stepaudio-3-gen



StepAudio 3 Gen 是面向综合音频内容创作的生成模型。用户仅需用自然语言描述角色设定、音色风格与情绪表达，即可生成富有表现力、可精细控制的人声；在此基础上，模型同样支持音效、环境音、背景音乐与歌声的生成，并可将各类声音统一编排到同一段音频中，输出具有完整听觉效果的作品。[技术报告](https://arxiv.org/abs/2609.12945)｜[更多 demo](https://static.stepfun.com/blog/stepaudio3/gen/)｜[语音体验中心](https://www.stepfun.com/studio/audio?tab=audio-gen)

## 模型信息

| 项目 | 内容 |
| :- | :- |
| 模型 ID | `stepaudio-3-gen-preview` |
| 输入 | 角色、脚本描述和自然语言指令 |
| 输出 | 综合音频 |
| 计费 | 限时免费 |

> [!NOTE]
>
> `stepaudio-3-gen-preview` 为限免期间使用的模型名称，限免到期后该预览版本将下线，并新增正式付费版本。

## 核心能力

* **精细化声音设计与控制**：支持通过自然语言控制多角色台词、音色风格、说话方式、语气情绪、方言口音，以及笑声、喘息、停顿等拟人化副语言特征。可在一条指令中描述多个角色及其互动关系，由模型完成对白组织和声音衔接，使生成结果更具连贯性和表现力。
* **全要素生成与时序编排**：除人声外，同样支持音效、环境音、背景音乐与歌声的生成，并可通过规范化的自然语言指定各声音元素的出现位置与先后顺序，完成协同生成与片段衔接，满足完整音频作品的制作需要。

## 应用场景

* **专业内容生产**：面向影视、游戏、动画、广播剧和有声书等专业场景，可灵活设计不同角色的音色与表达风格，快速完成角色配音与多角色对白；并可一并生成所需的环境音、音效与背景音乐，减少传统制作流程中的多工种协作与后期处理成本，提升内容生产效率。
* **短视频与自媒体**：面向个人创作者的短视频配音场景，无需专业软件或音频制作经验，仅需一段规范化的自然语言描述，即可生成与视频内容匹配、风格可控的配音；并可按需补充背景音乐与音效，简化配音、选曲与混音等环节。

## API 端点

> **[音频生成 API](/docs/zh/api-reference/audio/generate)**
>
> `POST /v1/audio/generate`

## 相关资源

> **[语音大模型概述](/docs/zh/guides/models/audio)**
>
> 返回 Audio 3 系列模型概述。

> **[完整定价详情](/docs/zh/guides/pricing/details)**
>
> 查看语音、文本、图像等全部模型的计费规则。

> **[音频生成 API](/docs/zh/api-reference/audio/generate)**
>
> 查看音频生成请求参数与接口说明。

> **[Demo 与体验中心](https://www.stepfun.com/studio/audio?tab=audio-gen)**
>
> 在线快速体验 StepAudio 3 Gen 的音频生成能力。


# StepAudio 3 Music
Source: https://platform.stepfun.com/docs/zh/guides/models/stepaudio-3-music



模型以自然语言、歌词、人声及参考音频为核心输入，覆盖从灵感描述、完整歌曲生成到智能配乐的多种创作任务，帮助用户更高效地将创意转化为可听、可用的音乐作品。[技术报告](https://arxiv.org/abs/2609.16034)｜[查看更多 demo](https://static.stepfun.com/blog/stepaudio3/music/)｜[语音体验中心](https://www.stepfun.com/studio/audio?tab=music)

## 模型信息

| 项目 | 内容 |
| :- | :- |
| 模型 ID | `stepaudio-3-music-preview` |
| 输入 | 自然语言、歌词、人声或参考音频 |
| 输出 | 音乐 |
| 协议 | HTTP 异步任务 |
| 计费 | 限时免费 |

> [!NOTE]
>
> `stepaudio-3-music-preview` 为限免期间使用的模型名称，限免到期后该预览版本将下线，并新增正式付费版本。

## 模型架构

StepMusic 采用面向音乐理解与高保真生成的统一架构，基于大规模歌曲与音乐理解数据进行训练，通过自研无监督音乐表征编码器学习旋律、和声、节奏、结构、音色和演唱等信息，并由生成与渲染模块完成最终音频合成。

* **音乐语义理解**：将文字描述、歌词与参考音频映射到统一的音乐语义空间，理解内容、风格和演唱要求之间的关系。
* **多条件控制**：根据任务组合歌词、音乐描述、人声、旋律或参考歌曲等条件，支持多种生成模式。
* **音乐结构建模**：学习前奏、主歌、副歌、桥段、间奏和尾奏等结构，以及跨段落的旋律与能量发展。
* **高保真音频渲染**：通过 DiT 等生成架构完成音频细节重建，兼顾人声、器乐、空间感和整体制作质量。

## 核心能力

* **歌曲生成**：根据音乐描述和歌词，生成包含人声、旋律、编曲与混音的完整歌曲。
* **纯音乐生成**：根据风格、情绪、场景或乐器描述，生成无演唱人声的纯音乐。
* **干声智能配乐**：分析清唱或干声人声的旋律、节奏与情绪，自动生成匹配的伴奏和编曲。
* **自然语言音乐控制**：支持描述风格与流派、人声与唱腔、旋律与节奏、乐器与编曲、情绪与场景，以及制作质感。
* **参考音频驱动**：支持通过音色、哼唱、原曲或干声等参考输入，进行更精确、更个性化的音乐生成。
* **ABC 记谱输入**：支持参考 ABC 旋律记谱输入的音乐生成（即将支持）。

## 使用场景

* **音乐创作与 Demo**：快速验证歌词、旋律、曲风和编曲方向，为词曲作者、制作人和歌手提供创作草稿。
* **短视频与内容平台**：根据视频主题、情绪和时长生成原创歌曲或背景音乐，提升内容生产效率。
* **影视、游戏与广告**：围绕角色、剧情、世界观或品牌调性生成主题音乐、场景音乐和广告音乐。
* **虚拟角色与数字人**：结合角色音色生成歌曲，强化角色声音身份与持续内容供给能力。
* **个性化娱乐**：使用用户自己的声音、歌词或哼唱生成专属歌曲，用于纪念、祝福和社交分享。
* **音乐教育与灵感辅助**：将旋律想法快速转化为不同风格版本，辅助理解编曲、曲风和情绪表达。

## 输入建议

* **描述尽量具体**：相比“生成一首好听的歌”，同时说明流派、速度、人声、乐器、情绪和制作质感，更容易获得符合预期的结果。
* **歌词使用清晰结构**：建议使用 `[Intro]`、`[Verse]`、`[Pre-Chorus]`、`[Chorus]`、`[Bridge]`、`[Outro]` 等段落标签，帮助模型理解歌曲结构。
* **分轮调整关键变量**：首次生成先确定整体曲风和演唱方向，后续再逐步调整乐器、编曲密度和制作细节，便于比较不同版本。

## 合规说明

涉及声音克隆、歌曲翻唱和参考音频生成时，应确保已获得声音主体、词曲、录音及其他相关权利人的合法授权。生成内容在公开传播或商业使用前，应依据实际业务地区、平台规则和使用场景完成必要的版权、人格权及内容安全审核。

## API 端点

> **[Music API](/docs/zh/api-reference/audio/music)**
>
> `POST /v1/audio/music`

## 相关资源

> **[语音大模型概述](/docs/zh/guides/models/audio)**
>
> 返回 Audio 3 系列模型概述。

> **[完整定价详情](/docs/zh/guides/pricing/details)**
>
> 查看语音、文本、图像等全部模型的计费规则。

> **[Music API](/docs/zh/api-reference/audio/music)**
>
> 查看 Music API 请求参数。

> **[Demo 与体验中心](https://www.stepfun.com/studio/audio?tab=music)**
>
> 在线快速体验 StepAudio 3 Music 的音乐生成能力。


# StepAudio 3 Realtime
Source: https://platform.stepfun.com/docs/zh/guides/models/stepaudio-3-realtime



## 模型概述

阶跃星辰提供两种语音对话方案，适用于不同的场景需求。StepAudio 3 Realtime 是当前面向实时互动场景的旗舰模型，重点提升全双工对话、边想边说和 Voice Agent 能力。[技术报告](https://arxiv.org/abs/2609.14005)｜[查看更多 demo](https://static.stepfun.com/blog/stepaudio3/realtime/)｜[语音体验中心](https://www.stepfun.com/studio/audio?tab=voice-chat)

| 特性 | Chat Completions API | Realtime API |
| - | - | - |
| 连接方式 | HTTP 请求 | WebSocket 长连接 |
| 语音识别 (ASR) | 需自行实现或使用第三方服务 | 内置，自动识别用户语音 |
| 上下文管理 | 需自行维护 messages 列表 | 内置，自动管理对话历史 |
| 语音活动检测 (VAD) | 需自行实现 | 内置，自动检测用户说话 |
| 联网搜索 | 需自行实现搜索接口 | 内置 web\_search 工具 |
| 知识库检索 | 需自行实现 | 内置 retrieval 工具 |
| 延迟 | 较低（流式输出） | 极低（双向流式交互） |
| 适用场景 | 离线处理、批量任务、简单集成 | 实时对话、语音助手、客服机器人 |

以下模型可分别通过 [Chat API](/docs/zh/api-reference/chat/chat-completion-create) 和 [Realtime API](/docs/zh/api-reference/realtime/chat) 接入。

## 模型列表

### StepAudio 3 Realtime

* 定位：面向实时互动的全双工语音模型
* 能力标签：真人自然交互、全双工对话、自适应推理、边想边说、Voice Agent
* 体验入口：[体验中心](https://www.stepfun.com/studio/audio?tab=voice-chat)
* StepAudio 3 Realtime 将实时音频理解、话轮管理、推理和工具调用整合到同一段对话中。模型不仅识别用户说了什么，还能理解语气、情绪、副语言线索与环境声音。
* 支持自然打断、附和识别和话权协调：用户与模型可以同时说话，模型会在真正被打断时及时停下，在自然停顿或随口附和时保持对话连贯。
* 面对简单问题可以快速回应；面对复杂任务，可以自适应进入更深入的思考，并通过边想边说降低等待感。
* Voice Agent 可以在意图明确后调用工具或执行后端任务，任务运行期间对话仍可继续，结果返回后自然接入交流。

> [!NOTE]
>
> `stepaudio-3-realtime-preview` 为限免期间使用的模型名称，限免到期后该预览版本将下线，并新增正式付费版本。价格见 [API 定价](/docs/zh/guides/pricing/details)，调用限制见 [API 速率限制](/docs/zh/guides/pricing/rate-limits)。

### StepAudio 3 Chat

* 定位：面向 Chat Completions API 的语音理解与对话模型
* 能力标签：语音输入、文本对话、上下文理解、工具调用
* 通过 [Chat API](/docs/zh/api-reference/chat/chat-completion-create) 接入，适合按轮次提交语音或文本并获取文本回复的场景。
* 与 StepAudio 3 Realtime 共享 Audio 3 系列的声音理解与推理能力；如需语音流式输出和全双工交互，请使用 Realtime API。

> [!NOTE]
>
> `stepaudio-3-chat-preview` 为限免期间使用的模型名称，限免到期后该预览版本将下线，并新增正式付费版本。价格见 [API 定价](/docs/zh/guides/pricing/details)，调用限制见 [API 速率限制](/docs/zh/guides/pricing/rate-limits)。

## 业务场景应用

Realtime API 凭借实时交互与情感理解能力，已在多个行业领域实现成功落地：

* **智能座舱**：为车载系统提供自然语音交互界面，支持驾驶过程中的信息查询、闲聊对话和安全提醒
* **智能终端**：为各类 IOT 智能硬件设备提供实时语音交互能力，提升用户与设备间的交互体验
* **社交娱乐**：帮助社交平台和娱乐应用构建情感陪伴 Agent
* **智能客服**：实现高度拟人化的客户服务体验，提升服务效率和客户满意度
* **金融调解**：在金融纠纷处理过程中提供中立、专业的沟通辅助

通过集成 Realtime API，开发者可以快速构建具备人类般自然交流能力的应用，为用户带来真正沉浸式的语音交互体验。

## 模型快速入门

> **[实时双向语音开发](/docs/zh/guides/developer/realtime)**
>
> 了解 Realtime API 的事件模型、会话管理和语音交互流程。

> **[语音对话开发](/docs/zh/guides/developer/audio-chat)**
>
> 通过 Chat Completion 接口接入语音输入输出与音频流式能力。

> **[Realtime API 事件文档](/docs/zh/api-reference/realtime/chat)**
>
> 查看 Realtime API 的请求格式、事件字段和接口说明。

> **[Realtime API Demo](https://github.com/stepfun-ai/Step-Realtime-Console)**
>
> 参考官方前端演示项目，快速搭建实时语音对话控制台。


# StepAudio 3 TTS
Source: https://platform.stepfun.com/docs/zh/guides/models/stepaudio-3-tts



StepAudio 3 TTS 生成贴近真人的自然语音，在音色、语调、节奏和气口停顿上高度还原真实口语表现。[技术报告](https://arxiv.org/abs/2609.12945)｜[语音体验中心](https://www.stepfun.com/studio/audio?tab=tts)

## 模型信息

| 项目 | 内容 |
| :- | :- |
| 模型 ID | `stepaudio-3-tts` |
| 输入 | 文本、音频 |
| 输出 | 语音 |
| 计费 | 2.5 元 / 万字符 |
| 音色克隆 | 9.9 元 / 音色 |

## 核心能力

* **真人级的说话表现**：模型在音色基底、语调层次、节奏律动与气口停顿上高度贴合人类原生口语范式，彻底挣脱机器朗读的生硬桎梏与固化韵律模板。模型还原的不只是字面内容，更是人在说话时的最真实状态——笑声、咂嘴、迟疑、结巴、重复与改口等真人级口语表现，还能根据语义脉络自主推演情绪与语气的微妙变化。听到的始终是“一个人在说话”，而不是“一段被合成的语音”。
* **超低时延流式生成**：依托流式生成架构，一边生成一边输出，无需等待整句合成完成即可开始播放，可无缝对接实时对话业务链路，极大压缩交互等待窗口。

适合实时对话、语音助手和高表现力内容生成。

## API 端点

> **[非流式合成](/docs/zh/api-reference/audio/create-audio)**
>
> `POST /v1/audio/speech`

> **[流式合成](/docs/zh/api-reference/audio/ws-audio)**
>
> `WebSocket /v1/realtime/audio`

## 相关资源

> **[语音大模型概述](/docs/zh/guides/models/audio)**
>
> 返回 Audio 3 系列模型概述。

> **[完整定价详情](/docs/zh/guides/pricing/details)**
>
> 查看语音、文本、图像等全部模型的计费规则。

> **[音色列表](/docs/zh/guides/developer/tts#支持音色)**
>
> 查看官方提供的音色及参数说明。

> **[Demo 与体验中心](https://www.stepfun.com/studio/audio?tab=tts)**
>
> 在线快速体验 StepAudio 3 TTS 的完整能力。


# 视觉理解大模型
Source: https://platform.stepfun.com/docs/zh/guides/models/vision



## 模型概述

视觉理解大模型在文本大模型的基础上，增加了图像和视频输入能力，以实现更全面、更准确的理解和推理。

当前阶跃星辰已推出 Step 系列视觉理解大模型：

## 模型列表

### Step 5 Preview

推荐优先使用。面向真实任务的新一代旗舰基模，原生支持文本、图片和视频输入，提供 1M tokens 上下文，支持三档推理强度（low/medium/high）。适合图表分析、截图问答、视频总结和跨文档多模态任务。详见 [Step 5 Preview](/docs/zh/guides/models/step-5-preview)。

### Step 3.7 Flash

阶跃星辰的高速多模态推理模型，**原生支持图片和视频理解**，无需借助视觉 MCP 或额外模型，可直接完成图像 / 视频问答、跨模态分析等任务。支持三档推理强度（low/medium/high），上下文长度为 256K。详见 [Step 3.7 Flash](/docs/zh/guides/models/step-3.7-flash)。

### Step-1o Turbo Vision

该模型拥有强大的图像理解和视频理解能力，暂时只开放文本、图像和视频输入，且仅支持文本生成。输出速度快，上下文长度为 32K。

## 关键术语

1. **图像分辨率**：通常指长宽像素数量，分辨率越高，图像能表达的信息越丰富，模型推理成本越高，如更高的网络传输时间、首字延迟和费用消耗。建议长或宽不要超过4096像素。
2. **图像的 Token 数量**：与图像的分辨率有关，目前自适应缩放到最佳大小。
3. **支持的图像格式**：JPG/JPEG、PNG、静态 GIF、WebP
4. **URL 格式**：
   * **http/https 协议的网络资源**：要求中国大陆互联网可访问，且资源加载时间会影响推理首字延迟。
   * **base64编码**：遵循 RFC2394规范，基本格式为 `data:[<mediatype>][;base64],<data>`。示例 `data:image/jpeg;base64,<base64_data_string>`
   * **参考资源**： [RFC2397](https://www.rfc-editor.org/rfc/rfc2397#section-2)、[Data URL Format](https://developer.mozilla.org/en-US/Web/HTTP/Basics_of_HTTP/Data_URLs)

## 使用限制

1. **单次请求图像数量上限**：Step 5 Preview 单次请求最多 60 张图片，同时受上下文长度约束；其他模型请参考对应模型文档。轮次较多的对话，建议先通过多模态模型对图像进行描述或总结，再放入轮次历史作为文本理解的上下文。
2. **单次请求图像体积大小限制**：多张图片总大小控制在20M 以内。
3. **图像元数据**：模型无法获得图像元数据信息，如文件路径、文件名、文件大小、原始分辨率、作者、相机型号、地理位置信息等。在输入模型前，预处理阶段会将元数据清除，以免泄露隐私。此外，图像也会被缩放到最佳尺寸。
4. **字体过小的文本**：文字过小可能会影响识别效果。
5. **旋转和裁切**：不完整或非正位可能会影响识别效果。
6. **计数**：模型输出的数值可能不是完全精确，而是估算的值。
7. **准确性**：在某些情况下，模型可能会生成不正确的描述或标题。请勿在有严重后果的场景依赖模型推理结果。

## 模型快速入门

> **[从 OpenAI 迁移至阶跃星辰](/docs/zh/guides/developer/openai)**
>
> 使用兼容 OpenAI 的调用方式，快速切换到视觉理解模型。

> **[实现图片理解](/docs/zh/guides/developer/image-chat)**
>
> 让模型结合图片内容进行问答、描述和多模态理解。

> **[实现视频理解](/docs/zh/guides/developer/video-chat)**
>
> 传入视频链接，让模型读取并理解视频中的关键信息。

> **[实现多轮对话](/docs/zh/guides/developer/multiple-round)**
>
> 结合上下文历史，构建连续稳定的视觉对话体验。

> **[实现文档问答](/docs/zh/guides/developer/doc-parser)**
>
> 解析文档内容并结合视觉模型完成问答、抽取和理解任务。

> **[输出 JSON](/docs/zh/guides/developer/json-mode)**
>
> 让视觉理解结果按 JSON 结构返回，方便程序处理。

> **[流式输出](/docs/zh/guides/developer/stream)**
>
> 在模型生成过程中实时返回内容，提升交互体验。

> **[实现 Tool Call](/docs/zh/guides/developer/tool-call)**
>
> 让多模态模型结合外部工具完成更复杂的任务。

> **[实现 联网搜索](/docs/zh/guides/developer/web-search)**
>
> 接入互联网搜索，为模型补充最新信息与外部知识。

> **[Prompt 缓存](/docs/zh/guides/developer/prompt-cache)**
>
> 缓存重复上下文，优化长对话和复杂多模态输入场景。


# 创建并使用项目 API Key
Source: https://platform.stepfun.com/docs/zh/guides/organization/api-keys



加入组织后，您可以在所参与的项目下创建 API Key。用它发起的调用由组织的 Credit 账户承担费用，不消耗您个人账号的额度。

## 接受邀请

主账号发起邀请后，您会收到一条含邀请链接的短信。点击链接进入邀请页面：

* 手机号已注册平台账号：点击「确认加入组织」，即成为该组织的成员。
* 手机号尚未注册：点击「去注册」完成注册，注册成功后自动加入该组织。

邀请链接自发起时刻起 7 天内有效，过期后请联系邀请人重新发送。

## 切换到组织空间

通过控制台右上角的「用户中心 > 空间切换」进入组织空间。项目下 API Key 的创建与用量查询都在该空间下进行。如需退出组织，请联系主账号。

## 创建 API Key

1. 在组织空间进入「账户管理 > 接口密钥」。该页面按项目列出您参与的每个项目，每个项目下最多创建一个 API Key。
2. 在目标项目行点击「创建密钥」，填写名称（不超过 20 字）后确认。
3. 复制并妥善保存完整的 API Key。

> [!WARNING]
>
> 请妥善保管您的 API Key，不要写入代码仓库或分享给他人。任何获得该 Key 的人都能以您的身份调用模型，并消耗组织的 Credit。

已创建的 API Key 可以修改名称或删除。删除后该 API Key 立即失效且无法撤回，如需继续使用可在该项目下重新创建。

状态显示为「已被管理员禁用」时，该 API Key 已由主账号禁用，请联系主账号处理。

## 发起调用

项目下 API Key 的使用方式与个人 API Key 一致，不需要额外传递组织或项目标识。

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEPFUN_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "messages": [
      {
        "role": "user",
        "content": "你好"
      }
    ]
  }'
```

调用产生的费用从组织的 Credit 账户扣减，并计入对应的项目与成员。完整的接口说明见 [Chat Completions](/docs/zh/api-reference/chat/chat-completion-create)。

## 查看自己的用量

「账户管理 > 使用详情」展示您的调用明细，每一行对应一个计费项，可按密钥名称、模型与日期区间筛选，并导出当前筛选结果。

「账户管理 > 接口密钥」中的「Credit 已用 / 上限」一列展示您在该项目下的当期用量。上限显示为「不限」时，表示主账号未对您单独设置上限，此时仍受项目整体上限与组织 Credit 余额的约束。上限于每月 1 号 00:00 重置。

## 调用被拒绝时的排查

| 现象 | 原因 | 处理方式 |
| - | - | - |
| 402 `insufficient_credit` | 组织的 Credit 账户余额不足 | 联系主账号补充 Credit |
| 429 `project_credit_limit_exceeded` | 所在项目达到当期 Credit 上限 | 联系主账号调高项目上限，或等待下月 1 号重置 |
| 429 `member_project_credit_limit_exceeded` | 您在该项目内达到当期 Credit 上限 | 联系主账号调高您的上限，或等待下月 1 号重置 |
| API Key 不可用 | API Key 已被禁用或删除，或您已被移出该项目、该组织 | 在「账户管理 > 接口密钥」确认状态，必要时联系主账号 |
| 401 `invalid_api_key`：`Error code: 401 - {'error': {'message': 'Incorrect API key provided', 'type': 'invalid_api_key'}}` | 您使用的是组织空间的 API Key，不能用于 Step Plan 的 Base URL `https://api.stepfun.com/step_plan/v1/chat/completions` | 将 Base URL 改为 `https://api.stepfun.com/v1/chat/completions`，调用成功后从当前组织的 Credit 账户扣费 |

额度上限与速率限制返回的状态码同为 429，收到 429 时请以错误标识区分两种情况，错误标识的对照见[错误码](/docs/zh/api-reference/error-codes)。额度规则的完整说明见 [组织 Credit 额度规则](/docs/zh/guides/organization/credits)。


# 组织 Credit 额度规则
Source: https://platform.stepfun.com/docs/zh/guides/organization/credits



组织的 API 调用额度以 Credit 计量。全部 Credit 存放在组织级的 Credit 账户中，由组织成员共用。成员调用模型时，平台先按模型定价算出费用，再折算为 Credit 从该账户扣减。

## 计量口径

调用产生的消耗按 1 元 = 1,000,000 Credit 折算。各模型的单价见[API 定价](/docs/zh/guides/pricing/details)，按实际用量算出费用后，再折算为 Credit。

到账的 Credit 数量由合同约定的价格与折扣确定，开通与发放流程见[开通企业套餐](/docs/zh/guides/organization/subscribe)。

## Credit 的有效期

Credit 的有效期为合同到期日之后 180 天。到期未使用的 Credit 自动失效且不可恢复。账户中存在多笔 Credit 时，平台按到期时间由近及远依次扣除。

## 项目与成员的额度上限

Credit 账户由全体成员共用。在此基础上，主账号可以为项目、以及项目中的个别成员设置月度 Credit 上限，用于约束用量分布。上限只约束 Credit 用量，不影响速率限制。

* **项目月度上限**：默认不设置，即该项目不单独受限。设置后，项目当期用量达到上限时，该项目下的所有 API Key 停止调用。
* **成员在项目内的月度上限**：默认不设置，即该成员仅受所在项目的上限约束。设置后，该成员在该项目下的 API Key 达到上限时停止调用，项目内其他成员不受影响。

上限的统计周期为自然月，每月 1 号 00:00 重置。月中启用上限时，当月按完整上限计算，不按剩余天数折算；月中修改上限值时，已用量不清零、周期不重置，新的上限值直接减去已用量。

项目上限之和可以超过 Credit 账户余额，成员上限之和也可以超过所在项目的上限，实际可用额度取其中最紧的一项。

## 单次调用的扣减上限

一次调用实际可扣减的 Credit 不超过以下三者中的最小值：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
min(Credit 账户余额, 项目当期剩余上限, 成员当期剩余上限)
```

本次调用的用量超过该值时，调用被拒绝，且不产生扣费。

## 额度不足时的返回

| 情况 | 状态码 | 错误标识 | 恢复方式 |
| - | - | - | - |
| Credit 账户余额不足 | 402 | `insufficient_credit` | 联系销售补充 Credit |
| 项目达到月度上限 | 429 | `project_credit_limit_exceeded` | 由主账号调高项目上限，或等待下月 1 号重置 |
| 成员在项目内达到月度上限 | 429 | `member_project_credit_limit_exceeded` | 由主账号调高该成员的上限，或等待下月 1 号重置 |

额度上限与速率限制返回的状态码同为 429，收到 429 时请以错误标识区分两种情况，错误标识的对照见[错误码](/docs/zh/api-reference/error-codes)。速率限制见 [API 速率限制](/docs/zh/guides/pricing/rate-limits)。

## 查看用量

主账号在「组织管理 > 组织用量」查看整个组织的 Credit 消耗与调用明细，可按项目、成员与模型筛选并导出，详见[管理成员与项目](/docs/zh/guides/organization/manage)。

成员在「账户管理 > 使用详情」查看自己的调用明细，详见[创建并使用项目 API Key](/docs/zh/guides/organization/api-keys)。


# 管理成员与项目
Source: https://platform.stepfun.com/docs/zh/guides/organization/manage



组织的成员、项目与额度上限由主账号在组织空间中管理，相关页面仅主账号可见。项目用于划分 API Key 与 Credit 额度，组织名称与组织 ID 在「组织管理 > 组织信息」查看。

## 邀请成员

1. 进入「组织管理 > 成员管理」，点击右上角「邀请成员」。
2. 在文本框中输入被邀请人的手机号，一行一个，可一次提交多个。
3. 提交后，平台向这些手机号下发含邀请链接的短信。已注册的手机号确认后即成为组织成员，未注册的手机号完成注册后自动加入本组织。

邀请链接自发起时刻起 7 天内有效。未被接受的邀请显示在待接受邀请列表中，超过有效期后移入已过期邀请列表，需要重新发起邀请。

新加入的成员即可使用组织的 Credit 额度。如需约束用量，为项目或成员设置月度上限。

## 移除成员

> [!WARNING]
>
> 移除成员后，该成员名下的全部 API Key 失效，不可再用于调用。

在「组织管理 > 成员管理」的成员行点击「移除成员」并确认。成员不能自行退出组织，如成员需要退出，请将其移除。

## 创建项目

1. 进入「组织管理 > 项目管理」，点击右上角「创建项目」。
2. 填写项目名称（不超过 20 字），项目描述选填。
3. 确认后，新项目出现在项目列表中。

## 删除项目

> [!WARNING]
>
> 删除项目后，该项目下的所有 API Key 一并删除且不可恢复。

在项目行的操作列点击「删除项目」并确认。默认项目不提供删除操作。

## 添加项目成员

成员加入项目后，才能在该项目下创建 API Key。

1. 在项目列表点击「查看详情」进入项目详情页。
2. 在「项目成员列表」点击右上角「添加项目成员」。
3. 在下拉列表中搜索并选择组织成员，可一次添加多人。

## 将成员移出项目

在项目详情页成员行的操作列点击「移除成员」并确认。移出后该成员在本项目下的 API Key 失效，组织成员身份保留。

## 设置项目额度上限

1. 在项目详情页的「项目额度管理」卡片中点击「设置上限」或「编辑上限」。
2. 填写月度 Credit 上限后确认。将上限留空并确认，即取消该项目的上限。

设置后，卡片显示上限值、当期用量与下次重置时间。上限的生效规则见 [组织 Credit 额度规则](/docs/zh/guides/organization/credits)。

## 设置成员额度上限

成员的上限按项目分别设置，只约束该成员在本项目内的用量。

1. 在项目详情页的「API Key 列表」找到该成员的 API Key。
2. 在该行操作列点击「设置上限」，在「成员额度管理」弹窗中填写月度 Credit 上限后确认。留空表示不单独限制，该成员仅受项目上限约束。

## 禁用或启用成员的 API Key

在项目详情页「API Key 列表」中该 API Key 行的操作列点击「禁用」并确认。禁用后该 API Key 立即无法调用，成员侧显示为「已被管理员禁用」，成员不能自行恢复。点击「启用」即恢复调用。

## 管理自己的 API Key

主账号在任意项目下均可创建属于自己的 API Key，不必先加入该项目。

1. 在项目详情页点击右上角「创建新的密钥」。
2. 填写名称（不超过 20 字）后确认。

自己的 API Key 在列表中带有「我的」标签，可以修改名称与删除。删除后该 API Key 立即失效且无法撤回，如需继续使用可在该项目下重新创建。

## 查看组织用量

「组织管理 > 组织用量」的「Credit 账户」卡片展示本合同周期内的 Credit 已用量、总额度与有效期。合同周期指合同的生效日至到期日。

「使用详情」按调用记录展示明细，可按时间范围（默认本月）、项目、成员 ID 与模型 / 能力筛选，并导出当前筛选结果。汇总卡片「组织 Credit 总扣减」随筛选条件变化。

明细的每一行对应一个计费项。同一次调用产生多个计费项时，例如输入 Token 与输出 Token，拆成多行展示。


# 组织与项目
Source: https://platform.stepfun.com/docs/zh/guides/organization/overview



组织让一个团队共用同一份额度调用模型。企业完成[企业认证](/docs/zh/guides/organization/verification)后获得一个组织，开通企业套餐后，Credit 发放至组织的 Credit 账户。团队成员受邀加入组织，在项目下创建 API Key 调用模型，产生的费用统一从组织的 Credit 账户扣减，无需为每位成员单独充值。开通流程见[开通企业套餐](/docs/zh/guides/organization/subscribe)。

## 账号与空间

一个账号对应一位使用者。账号可以在个人空间与组织空间之间切换，两个空间的 API Key、额度与用量相互独立。

| 空间 | 使用的 API Key | 费用承担方 |
| - | - | - |
| 个人空间 | 账号自己的 API Key | 账号自身 |
| 组织空间 | 各项目下的 API Key | 组织的 Credit 账户 |

空间切换入口位于[开放平台控制台](https://platform.stepfun.com/account-info)右上角的 **用户中心 > 空间切换**。账号完成企业认证，或被邀请加入某个组织后，该入口才会出现。

一个账号可以同时属于多个空间，例如在本企业的组织中是主账号，同时又是合作方组织的成员。

## 组织的构成

| 概念 | 说明 |
| - | - |
| 组织 | 团队的容器，持有一个 Credit 账户，账户中的额度由全体成员共用 |
| 主账号 | 完成企业认证并开通企业套餐的账号，负责管理组织的成员、项目与额度 |
| 成员 | 由主账号邀请加入组织的账号，在所参与的项目下调用模型 |
| 项目 | 组织内的分组单位，用于隔离 API Key 并分配 Credit 额度 |
| API Key | 调用凭证，归属于某位成员在某个项目下，每位成员在每个项目中最多创建一个 |

组织下的默认项目不支持删除。主账号可以按业务线、团队或运行环境另行创建项目，并控制每个项目的成员与额度上限，详见[管理成员与项目](/docs/zh/guides/organization/manage)。

成员需先被添加到项目，才能在该项目下创建 API Key。

## 组织之间相互独立

组织之间的 Credit、成员、项目与额度上限均不互通。一个账号可以同时加入多个组织，在每个组织中使用该组织自己的额度。

## 调用方式

项目下 API Key 的调用方式与个人 API Key 一致，不需要额外传递组织或项目标识。平台按 API Key 的归属结算费用，并把每次调用计入对应的项目与成员。创建 API Key 与发起调用的步骤见[创建并使用项目 API Key](/docs/zh/guides/organization/api-keys)，额度的折算与上限规则见 [组织 Credit 额度规则](/docs/zh/guides/organization/credits)。


# 企业转账
Source: https://platform.stepfun.com/docs/zh/guides/organization/recharge



企业转账充值仅对完成[企业认证](/docs/zh/guides/organization/verification)的账号开放。平台按专属收款账号和认证时绑定的对公账户自动匹配款项，充入账户余额，无需提交凭证。

## 通过对公转账充值

1. 使用完成企业认证的账号登录 [StepFun 开放平台](https://platform.stepfun.com/)。

2. 在页面右上角的 **用户中心** 菜单中，选择 **账户管理**，进入[开放平台控制台](https://platform.stepfun.com/account-info)。

3. 在控制台左侧导航栏中，选择 **支付管理 > 充值**。

4. 切换到 **对公打款** 标签页。

5. 复制页面显示的收款账号。

   平台为每家企业分配专属收款账号，复制时请保留账号末尾的企业专属编号。

6. 记录页面显示的账户名和开户行。

   > [!WARNING]
   >
   > 平台限制非正当理由的退款，转账前请仔细核对充值金额。

7. 通过网银或银行柜台，使用企业认证时绑定的对公账户，向专属收款账号转账，无需填写备注。

   平台会在银行到账后自动识别款项并充入账户余额，到账时间以银行处理为准，通常为工作日当天。

8. 在控制台左侧导航栏中，选择 **支付管理 > 充值记录**，查看到账情况。

   余额到账后即可用于 API 调用。

## 充值规则

| 规则 | 说明 |
| - | - |
| 充值金额 | 没有固定面额要求，实际到账金额即为充值金额 |
| 累计充值金额 | 充值至开放平台账户的金额计入累计充值金额，限速档位见[API 速率限制](/docs/zh/guides/pricing/rate-limits#阶梯限速) |

## 申请发票

1. 在控制台左侧导航栏中，选择 **支付管理 > 发票管理**。
2. 选择已充值的订单。
3. 发起开票申请。

已完成企业认证的账号只能开具企业抬头发票，抬头与税号按认证信息自动带出。

## 问题排查

| 现象 | 原因 | 处理方式 |
| - | - | - |
| 款项超过 1 个工作日未到账 | 银行尚未完成处理，或付款账户、收款账号与认证信息不匹配 | 保留银行转账回单，联系平台客服核实 |
| 从个人账户、其他银行账户或第三方支付渠道打款后未入账 | 系统只识别企业认证时绑定的对公账户 | 联系平台客服处理 |
| 更换对公账户后无法充值 | 系统只识别企业认证时绑定的对公账户 | 联系平台客服变更绑定信息，再发起转账 |
| 转账金额有误需要退回 | 转账金额与计划充值金额不一致 | 联系平台客服处理 |


# 开通企业套餐
Source: https://platform.stepfun.com/docs/zh/guides/organization/subscribe



企业套餐通过签订合同开通。合同签订后，Credit 由平台发放至组织的 Credit 账户，组织成员即可使用。

## 开通流程

**1. 完成企业认证**

进入[开放平台控制台](https://platform.stepfun.com/account-info)，按[企业认证](/docs/zh/guides/organization/verification)流程完成认证。认证通过后，账号获得一个组织，控制台右上角出现空间切换入口。已完成认证的账号可跳过此步。

**2. 联系销售**

切换到组织空间，在**企业套餐 > 订阅情况**中点击**联系销售**，填写表单并提交。我们将在 1 至 2 个工作日内与您联系，沟通用量规模与商务方案。

**3. 签订合同**

双方确认方案后签订合同。合同签订后，Credit 按合同约定发放至组织的 Credit 账户。

若认证已通过但空间切换入口未出现，请提交工单联系我们。

> [!NOTE]
>
> 购买的 Credit 有效期为合同到期日之后 180 天，到期未使用的部分自动失效。扣减顺序与额度上限规则见 [组织 Credit 额度规则](/docs/zh/guides/organization/credits)。

## 查看订阅与支付记录

**企业套餐 > 订阅情况**展示当前的订阅状态。组织的 Credit 额度、已用量与有效期在**组织管理 > 组织用量**查看。

**企业套餐 > 支付记录**按订单展示历次 Credit 发放，包括订单编号、购买时间、消费金额、到账的 Credit 数量与支付状态。

## 申请发票

需要开具发票时，在支付记录中对应订单处发起申请，或前往**支付管理 > 发票管理**。发票可按购买金额或消耗金额开具，历史申请在**开票记录**中查看。


# 企业认证
Source: https://platform.stepfun.com/docs/zh/guides/organization/verification



企业认证采用企业信息核验与对公账户小额打款核验。认证全程在线完成，无需上传营业执照或法人证件，也不需要人工审核。

## 认证所需信息

准备以下信息，并确认可以查询对公账户的到账明细：

* 公司全称
* 统一社会信用代码
* 对公账户的开户银行
* 企业对公账户

## 企业认证限制

| 规则 | 说明 | 处理方式 |
| - | - | - |
| 鉴权金额有效期 | 自打款起 24 小时内有效，获取次数有限制 | 过期后重新获取鉴权金额 |
| 错误次数 | 鉴权金额连续填错超过 2 次，或因银行信息有误导致打款失败 2 次，认证锁定 24 小时 | 核实企业信息与银行账户，等待 24 小时后再试 |
| 企业与账号的绑定 | 一家企业只能由一个账号认证，一个对公账户只能绑定一个账号 | 认证过程中提示企业或对公账户已被其他账号绑定时，请联系平台客服处理 |

## 完成企业认证

1. 登录 [StepFun 开放平台](https://platform.stepfun.com/)。
2. 在页面右上角的 **用户中心** 菜单中，选择 **账户管理**，进入[开放平台控制台](https://platform.stepfun.com/account-info)。
3. 在控制台左侧导航栏中，选择 **账户管理 > 账户信息**。
4. 点击提示条右侧的**立即认证**。
5. 填写公司名称、统一社会信用代码、所属银行和银行账户。
6. 点击**下一步**。
   系统会核验公司名称与统一社会信用代码是否匹配。信息不匹配时，请修正后重新提交。
7. 点击**获取鉴权金额**。招商银行会向该对公账户打入一笔 `0.01` 元至 `0.09` 元的随机款项，通常在几分钟内到账。
8. 向财务确认实际到账金额。
9. 在**鉴权金额**中填写金额，单位为元。例如到账 5 分钱时填写 `0.05`。
10. 勾选《企业用户服务购买协议》。
11. 点击**提交**。

金额校验通过即认证成功，**账户信息**页显示**企业已认证**。

## 认证后的账户与组织

认证通过后，账号获得一个组织，可通过控制台右上角的入口切换空间。组织的构成与使用见[组织与项目](/docs/zh/guides/organization/overview)；如需使用组织的 Credit 额度，请参阅[开通企业套餐](/docs/zh/guides/organization/subscribe)。

账户默认为预付费模式，可通过[企业转账](/docs/zh/guides/organization/recharge)向账户余额充值。如需月结，可联系平台销售申请改为后付费模式。

## 问题排查

| 现象 | 原因 | 处理方式 |
| - | - | - |
| 鉴权金额未到账 | 开户银行或银行账户填写有误，或银行尚未完成处理 | 向财务确认对公账户明细；确认未到账时，核对开户银行和银行账户后重新获取鉴权金额。连续失败时，请联系平台客服处理 |


# 静态托管
Source: https://platform.stepfun.com/docs/zh/guides/page-hosting



静态托管可以将已经构建好的静态网站发布到阶跃星辰开放平台，并生成可预览、可分享的链接。无需准备服务器或配置 CDN，上传网站文件后即可完成预览、上线和版本管理。

本文面向使用阶跃星辰开放平台「我的站点」功能的产品用户，介绍从首次发布到日常运维的完整流程。

> [!NOTE]
>
> 如需通过命令行、CI/CD 或 MCP 部署和管理站点，请参阅[静态托管 CLI 与 MCP](/docs/zh/guides/developer/page-hosting-cli-mcp)。

## 适用场景

* 产品官网、活动页、帮助中心、作品集等静态网站。
* 使用 React、Vue、Vite、Next.js 静态导出等工具构建后的产物。
* 需要在正式上线前分享预览链接，或需要保留多个可回滚版本的场景。

静态托管只负责静态文件分发，不提供服务端运行时。PHP、Python、Node.js 等服务端代码不会在托管环境中执行。

## 核心概念

| 概念 | 说明 |
| - | - |
| 站点 | 一个独立的网站项目，包含名称、访问地址、服务模式和多个版本。 |
| 版本 | 一次发布产生的文件快照，按 `v1`、`v2`……递增。版本可以预览、上线或回滚。 |
| 预览链接 | 指向指定版本的临时分享地址。预览不改变线上版本，可设置有效期或撤销。 |
| 线上版本 | 当前对外正式提供服务的版本。一个站点同一时间只有一个线上版本。 |
| 根页面 | 访问站点根路径 `/` 时返回的文件，通常是 `index.html`。 |

## 快速开始

### 1. 打开「我的站点」

登录[阶跃星辰开放平台](https://platform.stepfun.com)后，在控制台侧边栏进入「我的站点」，点击「新建站点」。

站点列表支持按名称搜索，并按「全部」「已上线」「草稿」「异常」筛选。

### 2. 准备并上传网站产物

在「发布站点」窗口中填写站点标题，然后将以下任一种内容拖入上传区域，或点击对应按钮选择：

* 单个 `.zip` 压缩包；
* 一个网站文件夹；
* 多个网站文件。

上传文件夹时，系统会自动去除最外层的公共目录。例如选择 `dist/` 文件夹后，`dist/index.html` 会按 `index.html` 发布。

### 3. 确认根页面

如果上传内容中包含根目录下的 `index.html`，系统会自动将它作为根页面。

如果没有 `index.html`，系统会列出可选文件：

* 选择一个 HTML 文件，访问 `/` 时返回该文件；
* 选择「无根页面」，访问 `/` 时返回 404。

ZIP 压缩包不能在上传窗口中逐文件选择根页面；请在压缩包根目录放置 `index.html`。压缩包内没有该文件时，发布会失败。

### 4. 生成预览并上线

点击「发布」后，系统会依次上传文件、处理版本并生成预览链接。发布成功后会显示「预览就绪」：

1. 点击「打开预览」检查页面和资源是否正常；
2. 在版本历史中找到需要发布的版本，点击「上线」；
3. 确认后，该版本会替换当前线上版本。

首次发布默认只生成预览，不会自动替换线上版本。线上地址会在首次上线后显示在站点详情页和站点卡片中。

## 上传要求与限制

### 文件大小和数量

* 单次发布整包大小不超过 **50 MB**；
* 单次发布文件数不超过 **5,000 个**；
* 站点名称最多 **64 个字符**；
* 每个站点最多保存的版本数受账户配额限制，达到上限后请先删除旧版本（如果产品界面提示该限制）。

`.zip` 的限制按压缩包文件大小检查；压缩包解开后，文件类型和路径仍由服务端再次校验。

### 支持的文件类型

常见支持类型包括：

`html`、`htm`、`css`、`js`、`mjs`、`json`、`map`、`txt`、`xml`、`svg`、`ico`、`png`、`jpg`、`jpeg`、`gif`、`webp`、`avif`、`woff`、`woff2`、`ttf`、`otf`、`eot`、`wasm`、`pdf`、`mp4`、`webm`、`mp3`、`wav`、`md`、`markdown`、`jsonl`、`tsx`、`jsx`。

以下类型明确禁止：

`php`、`py`、`exe`、`sh`、`bat`、`cmd`、`dll`、`so`、`jsp`、`asp`、`aspx`、`cgi`、`pl`。

扩展名不在支持列表中的文件也会被拒绝。建议上传构建工具生成的 `dist` 或 `build` 目录，不要上传源代码、依赖目录（如 `node_modules`）或服务端文件。

## 预览、上线与版本管理

### 预览链接

每次发布都会为新版本生成预览链接。预览链接支持以下操作：

* 打开链接检查页面；
* 复制链接并分享给协作者；
* 设置有效期：永不过期、24 小时、7 天或 30 天；
* 撤销链接；
* 撤销后重新生成新链接。

预览链接只代表对应版本的预览，不等于线上地址。链接撤销后会立即失效，访问返回 404；设置了有效期的链接到期后同样不可访问。

### 上线

在站点详情页的「历史版本」中，打开版本操作菜单并点击「上线」。上线前会弹出确认提示，因为上线会替换当前线上版本。

只有未上线且未被审核标记为拒绝的版本可以尝试上线；最终结果以服务端校验为准。审核未通过或配置解析失败的版本不能上线。

### 回滚

如果新版本出现问题，在「历史版本」中找到之前的版本，打开操作菜单并点击「回滚」。确认后，选中的版本会成为新的线上版本，原线上版本仍保留在历史记录中。

### 重新发布

站点详情页右上角的「重新发布」有两种用法：

* **不上传新文件**：重新激活当前线上版本，适合线上地址异常或需要再次触发上线的场景；
* **上传新文件**：创建一个新版本。新版本先生成预览，检查无误后再上线。

如果修改了环境变量，必须上传新的构建产物并发布新版本，直接重新上线旧版本不会使用最新环境变量。

## 服务模式

在站点详情页进入「站点设置」，可以选择服务模式：

* **SPA**：未知路由返回根页面（通常是 `index.html`），适合 React Router、Vue Router 等客户端路由应用。刷新 `/about` 等前端路由时，仍由前端应用接管路由。
* **Static**：请求缺失文件时直接返回 404，适合路径与文件一一对应的普通静态网站。

切换服务模式会立即保存。若应用使用前端路由，建议选择 SPA；若希望错误路径明确返回 404，建议选择 Static。

## 自定义响应头

在上传包的**根目录**放置 `page.config.json`，可以为不同路径配置响应头。示例：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "headers": [
    {
      "path": "/*",
      "name": "X-Frame-Options",
      "value": "DENY"
    },
    {
      "path": "/assets/*",
      "name": "Cache-Control",
      "value": "public, max-age=31536000, immutable"
    }
  ]
}
```

| 字段 | 说明 |
| - | - |
| `path` | 规则匹配的路径，例如 `/*`、`/assets/*`。 |
| `name` | 响应头名称，例如 `Cache-Control`。 |
| `value` | 响应头值。 |

发布后在「响应头规则」页签可以查看当前线上版本解析出的规则。该页签展示的是只读结果，修改规则需要更新 `page.config.json` 后重新发布。配置无法解析时，该版本会被标记为配置拒绝，不能上线。

## 构建时环境变量

### 配置变量

在「站点设置」的「环境变量」区域添加变量。变量名必须：

* 以大写英文字母开头；
* 只包含大写英文字母、数字和下划线，例如 `API_BASE_URL`；
* 同一站点内不能重复；
* 最多配置 50 个变量；
* 单个变量值为单行文本，最多 2,048 个字符。

### 在文件中引用

在静态文件中使用 `{{PAGE_ENV:变量名}}` 占位符。例如：

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const apiBase = '{{PAGE_ENV:API_BASE_URL}}'
```

发布构建时，系统会在文本文件中将占位符替换为对应值。当前处理的文本类型包括：`.html`、`.htm`、`.js`、`.css`、`.json`、`.txt`、`.svg`、`.xml`。图片、字体、音视频、PDF 等二进制文件不会被修改；未定义的占位符会保持原样。

环境变量在**发布构建时注入**，保存变量后不会改写已经发布的版本。变更变量后，请重新上传并发布产物；仅对旧版本执行「重新发布」不会生效。

不要把密码、私钥、长期有效的访问令牌等高敏感信息放入前端环境变量。静态文件会发送给访问者，构建后的变量值也可能被用户在浏览器中看到。

## 数据分析与部署日志

进入站点详情页的「数据分析」页签，可以查看：

* 请求数；
* 传输流量；
* 每日请求趋势；
* 部署日志（版本、操作、操作者、时间和结果）。

数据分析支持 `24h`、`7d`、`30d` 三个时间范围。新站点或尚未产生访问请求的站点会显示空状态；分享线上地址或预览地址产生访问后，再返回查看统计数据。

## 站点设置与删除

「站点设置」支持：

* 修改站点名称；
* 切换 SPA / Static 服务模式；
* 管理环境变量；
* 删除站点。

删除站点需要在确认框中完整输入站点名称。删除是永久操作，会同时删除站点及其所有版本，且线上地址和预览链接都会失效。删除前请先通过版本下载功能备份仍可用的版本文件。

## 常见问题

### 访问 `/` 返回 404

请确认：

1. 上传包根目录存在 `index.html`；
2. 如果使用文件/文件夹上传，已在「根页面」中选择正确文件；
3. 没有选择「无根页面」；
4. 站点已经上线，而不是仅生成了预览版本。

### 刷新前端路由返回 404

将站点服务模式改为 SPA，并重新访问线上地址。Static 模式只会返回实际存在的文件。

### 发布提示文件类型不支持

检查报错列出的文件名或扩展名，移除禁止类型和不在支持列表中的文件后重新打包。ZIP 内的文件也会被检查；请特别注意不要把服务端源码或脚本放入压缩包。

### 环境变量没有更新

环境变量是构建时替换。确认变量已保存，然后上传新的静态产物并发布新版本；直接对旧版本执行「重新发布」不会重新注入变量。

### 预览链接打不开

检查链接是否已过期或被撤销，并在版本操作中重新生成链接。若版本已经删除或站点被删除，原链接也无法恢复。

### 新版本无法上线

查看版本上的状态标签：审核未通过、审核提交失败或 `page.config.json` 配置拒绝都会阻止上线。修复网站内容或配置后，重新发布一个新版本。

## 发布前检查清单

* [ ] 入口文件和资源路径使用相对路径，大小写与实际文件名一致。
* [ ] 根目录包含 `index.html`，或已明确选择其他根页面。
* [ ] 根据应用类型选择 SPA 或 Static 服务模式。
* [ ] 已移除 `node_modules`、源代码和服务端脚本等不需要发布的文件。
* [ ] 整包不超过 50 MB，文件数不超过 5,000 个。
* [ ] 环境变量已保存，并确认不会把敏感信息暴露到浏览器端。


# API 定价
Source: https://platform.stepfun.com/docs/zh/guides/pricing/details



API 调用按实际用量计费，单价以人民币计价。

## 文本与多模态模型

> [!NOTE]
>
> Step 5 Preview 的缓存命中输入价格自北京时间 2026 年 10 月 14 日 00:30 起由 0.35 元／百万 tokens 调整为 0.70 元／百万 tokens。在该时间之前已通过按量付费 API 调用过 Step 5 Preview 的用户，继续适用 0.35 元／百万 tokens。详见[价格调整公告](/docs/zh/announcements/step-5-preview-price-adjustment)。

单位：元／百万 tokens。

| Model ID | 输入价格（缓存未命中） | 输入价格（缓存命中） | 输出价格 |
| - | - | - | - |
| `step-5-preview` | 7 | 0.70 | 20 |
| `step-3.7-flash` | 1.35 | 0.27 | 8.1 |
| `step-3.5-flash` | 0.7 | 0.14 | 2.1 |
| `step-3.5-flash-2603` | 0.7 | 0.14 | 2.1 |
| `step-1o-turbo-vision` | 2.5 | 0.5 | 8 |

## 语音模型

### 按 Token 计费

单位：元／百万 tokens。

| Model ID | 输入价格（缓存未命中） | 输入价格（缓存命中） | 输出价格 | 状态 |
| - | - | - | - | - |
| `stepaudio-3-realtime-preview` | — | — | — | 限时免费 |
| `stepaudio-3-chat-preview` | — | — | — | 限时免费 |
| `stepaudio-2.5-realtime` | 10 | 2 | 70 | 按量计费 |
| `stepaudio-2.5-chat` | 10 | 2 | 25 | 按量计费 |
| `step-1o-audio` | 25 | 5 | 60 | 按量计费 |
| `step-audio-2` | 10 | 2 | 70 | 按量计费 |
| `step-audio-r1.5` | 10 | 2 | 105 | 按量计费 |

### 语音合成

| Model ID | 单价 |
| - | - |
| `stepaudio-3-tts` | 2.5 元／万字符 |
| `stepaudio-2.5-tts` | 5.8 元／万字符 |
| `step-tts-2` | 2.8 元／万字符 |
| `step-tts-mini` | 0.9 元／万字符 |

> [!NOTE]
>
> 此处 1 个汉字算 1 个字符，2 个英文字母算 1 个字符，2 个标点符号算 1 个字符。

### 语音复刻

| Model ID | 单价 |
| - | - |
| `stepaudio-3-tts`、`stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini` | 9.9 元／音色，试听接口仅收合成费用；正式复刻成功立即收费 |

### 音频与音乐生成

| Model ID | 状态 |
| - | - |
| `stepaudio-3-gen-preview` | 限时免费 |
| `stepaudio-3-music-preview` | 限时免费 |

### 语音识别

| Model ID | 单价 |
| - | - |
| `stepaudio-3-asr-max` | 2.8 元／小时 |
| `stepaudio-2.5-asr` | 0.15 元／小时 |
| `stepaudio-2.5-asr-stream` | 1.2 元／小时 |
| `stepaudio-2-asr-pro` | 2 元／小时 |
| `step-asr` | 0.9 元／小时 |
| `step-asr-1.1` | 2.2 元／小时 |
| `step-asr-1.1-stream` | 2.6 元／小时 |

## 增值能力

| 能力 | 单价 |
| - | - |
| 互联网搜索 | 0.04 元／次 |
| 文搜图 | 0.12 元／次 |
| 文件存储 | 0.5 元／GB／天 |


# 计费概述
Source: https://platform.stepfun.com/docs/zh/guides/pricing/intro



开放平台提供 API 按量付费和 Step Plan 订阅两种计费方式。按量付费根据调用用量计算费用，Step Plan 订阅按套餐发放月度 Credit 额度。

## 计费方式

| 计费方式 | 费用计算 | 详细规则 |
| - | - | - |
| API 按量付费 | 根据模型或能力的实际用量与对应单价计算费用 | [API 定价](/docs/zh/guides/pricing/details) |
| Step Plan 订阅 | 按套餐支付订阅费，每月获得对应的 Credit 额度；额度用尽后可购买加油包 | [Step Plan 套餐](/docs/zh/step-plan/pricing#套餐档位) |

## API 计费单位

| 计费项 | 计量方式 |
| - | - |
| 模型输入与输出 | 按 Token 计量，输入与输出分别计费；支持缓存的模型区分缓存命中与未命中的输入价格 |
| 部分语音能力 | 按字符数或音频时长计量 |
| 搜索与存储等增值能力 | 按调用次数或存储量与存储时长计量 |

每个计费项的费用为用量乘以对应单价，各项费用相加得到调用费用。各模型和能力的计费单位与单价见 [API 定价](/docs/zh/guides/pricing/details)。调用量还受并发、每分钟请求数（RPM）和每分钟 Token 数（TPM）的限制，具体配额见 [API 速率限制](/docs/zh/guides/pricing/rate-limits)。

## API 费用归属

按量付费调用的费用由 API Key 所属的账户承担。

| API Key 类型 | 费用归属 | 相关操作 |
| - | - | - |
| 个人 API Key | 从个人账户额度中扣减 | [创建 API Key](/docs/zh/quickstart/create-api-key) |
| 组织项目 API Key | 从组织 Credit 账户中扣减，由组织成员共用；有效期与额度上限见[组织 Credit 额度规则](/docs/zh/guides/organization/credits) | [开通企业套餐](/docs/zh/guides/organization/subscribe)、[管理成员与项目](/docs/zh/guides/organization/manage) |


# API 速率限制
Source: https://platform.stepfun.com/docs/zh/guides/pricing/rate-limits



API 的速率限制包括并发、每分钟请求数（RPM）和每分钟 Token 数（TPM）。

## 限制指标

| 指标 | 含义 |
| - | - |
| 并发 | 同时处理的请求数量 |
| RPM | 每分钟请求数量 |
| TPM | 每分钟 Token 数量 |

## 阶梯限速

按量付费 API 按账户累计充值金额分档限速，累计充值金额只统计现金充值，代金券不计入。[Step Plan](/docs/zh/step-plan/overview) 用量由所订阅套餐的月度 Credit 额度管理，不按累计充值金额分档。资源达到容量上限时，我们可能临时调整各档限速。

## 个人账户

个人账户需先完成[实名认证](/docs/zh/quickstart/real-name-verification)，档位按累计充值金额划分：

| 用户等级 | 累计充值金额 | 并发 | RPM | TPM |
| :-: | :- | :- | :- | :- |
| V0 | 不足 ¥100 | 5 | 100 | 500,000 |
| V1 | ¥100 – ¥499 | 20 | 400 | 2,000,000 |
| V2 | ¥500 – ¥1,999 | 30 | 600 | 3,000,000 |
| V3 | ¥2,000 – ¥9,999 | 40 | 800 | 4,000,000 |
| V4 | ¥10,000 及以上 | 130 | 2,600 | 13,000,000 |

## 企业账户

有关[企业认证](/docs/zh/guides/organization/verification)账户的限速档位，请联系您的对接商务。企业预付费充值与累计充值金额的关系见[企业转账](/docs/zh/guides/organization/recharge)。


# 快速开始
Source: https://platform.stepfun.com/docs/zh/quickstart/overview



## 选择模型 ID

| 模型 | Model ID | 输入能力 |
| :- | :- | :- |
| Step 5 Preview | `step-5-preview` | 文本、图片、视频 |
| Step 3.7 Flash | `step-3.7-flash` | 文本、图片、视频 |
| Step 3.5 Flash | `step-3.5-flash` | 仅文本 |

将下面示例中的 `YOUR_MODEL_ID` 替换为上表中的 Model ID，并将 `YOUR_STEP_API_KEY` 替换为您的 API Key。

文档中的 `YOUR_STEP_API_KEY` 是待替换的密钥占位符，不是真实密钥。`STEP_API_KEY`、`STEPFUN_API_KEY` 等是示例或工具使用的变量名；例如 `export STEPFUN_API_KEY="YOUR_STEP_API_KEY"` 设置变量，`Bearer $STEPFUN_API_KEY` 读取其值。请保持同一示例的变量名一致，并保留工具要求的配置字段名。

## 申请 API 密钥

个人账号请先完成[个人实名认证](/docs/zh/quickstart/real-name-verification)。

1. 登录 [StepFun 开放平台](https://platform.stepfun.com/)。
2. 在页面右上角的 **用户中心** 菜单中，选择 **账户管理**，进入[开放平台控制台](https://platform.stepfun.com/account-info)。
3. 在控制台左侧导航栏中，选择 **账户管理 > 接口密钥**。
4. 在[接口密钥](https://platform.stepfun.com/interface-key)页面创建 API Key。
5. 复制 API Key。

## 环境准备

### Python 依赖安装

Python 示例使用 OpenAI SDK：

**macOS / Linux**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
python3 -m pip install --upgrade "openai>=1.0"
```

**Windows**

```powershell theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
py -m pip install --upgrade "openai>=1.0"
```

## 发送请求

**文本对话**

适用于三个模型。将 `YOUR_MODEL_ID` 替换为要调用的模型 ID。

**Python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

response = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[
        {"role": "user", "content": "你好，请用一句话介绍你自己。"}
    ],
)

print(response.choices[0].message.content)
```

**cURL**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_STEP_API_KEY" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "你好，请用一句话介绍你自己。"
      }
    ]
  }'
```

**图片理解**

Step 5 Preview 和 Step 3.7 Flash 支持图片输入。Step 3.5 Flash 不支持图片输入，请改用支持图片的模型。

**Python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

response = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "请提取图中的关键信息并概括主要结论。"},
            {
                "type": "image_url",
                # 请将此占位地址替换为您自己的可访问图片 URL。
                "image_url": {"url": "https://example.com/image.jpg"},
            },
        ],
    }],
)

print(response.choices[0].message.content)
```

**cURL**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# 请将此占位地址替换为您自己的可访问图片 URL。
curl https://api.stepfun.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_STEP_API_KEY" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "请提取图中的关键信息并概括主要结论。"},
        {
          "type": "image_url",
          "image_url": {"url": "https://example.com/image.jpg"}
        }
      ]
    }]
  }'
```

**视频理解**

Step 5 Preview 和 Step 3.7 Flash 支持通过 `video_url` 传入视频。Step 3.5 Flash 不支持视频输入，请改用支持视频的模型。

**Python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

response = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "请按时间顺序总结视频中的主要内容。"},
            {
                "type": "video_url",
                # 请将此占位地址替换为您自己的可访问视频 URL。
                "video_url": {"url": "https://example.com/video.mp4"},
            },
        ],
    }],
)

print(response.choices[0].message.content)
```

**cURL**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# 请将此占位地址替换为您自己的可访问视频 URL。
curl https://api.stepfun.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_STEP_API_KEY" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "请按时间顺序总结视频中的主要内容。"},
        {
          "type": "video_url",
          "video_url": {"url": "https://example.com/video.mp4"}
        }
      ]
    }]
  }'
```

## 响应请求

非流式请求的生成内容位于 `choices[0].message.content`：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "model": "所选模型 ID",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "模型生成的回复"
      },
      "finish_reason": "stop"
    }
  ]
}
```

完整响应还包含请求 ID、token 用量等字段，详见 [Chat Completions API](/docs/zh/api-reference/chat/chat-completion-create)。

如果请求失败，请根据返回的错误信息查阅[错误码文档](/docs/zh/api-reference/error-codes)。

## 深入使用

> **[模型列表](/docs/zh/guides/models/list)**
>
> 对比 Step 5 Preview、Step 3.7 Flash 和 Step 3.5 Flash 的定位与能力。

> **[图片理解](/docs/zh/guides/developer/image-chat)**
>
> 查看图片格式、传入方式和参数建议。

> **[视频理解](/docs/zh/guides/developer/video-chat)**
>
> 查看视频输入方式、限制和常见问题。

> **[API 参考](/docs/zh/api-reference/chat/chat-completion-create)**
>
> 查看完整请求参数、响应字段和用量信息。


# 个人实名认证
Source: https://platform.stepfun.com/docs/zh/quickstart/real-name-verification



个人实名认证通过支付宝完成人脸识别核验。免费套餐用户需完成认证才能继续使用，所有用户在付费前均需完成认证。

## 完成个人实名认证

1. 登录 [StepFun 开放平台](https://platform.stepfun.com/)。
2. 在页面右上角的 **用户中心** 菜单中，选择 **账户管理**，进入[开放平台控制台](https://platform.stepfun.com/account-info)。
3. 在控制台左侧导航栏中，选择 **账户管理 > 账户信息**。
4. 在**账号设置**一行点击**前往设置**。
5. 在**实名认证**一行点击**认证**。
6. 选择**个人实名认证**。
7. 填写本人姓名和身份证号码。
8. 点击**开始认证**。
9. 使用手机支付宝扫描二维码，按支付宝提示完成人脸识别。
10. 返回开放平台。
11. 点击**已完成刷脸认证**查看认证结果。

认证通过后，用户中心的**实名认证**一行显示为**已实名认证**。认证失败、次数限制等问题请参阅[常见问题](/docs/zh/faq/common-questions)。


# 数据路径
Source: https://platform.stepfun.com/docs/zh/step-code/configuration/data-paths



了解配置、凭据、会话和项目资源的存放位置，以便备份、迁移和排查问题。

## 数据根目录

| 系统 | 默认目录 |
| - | - |
| macOS | `/Users/<用户名>/.stepcode` |
| Linux | `/home/<用户名>/.stepcode` |
| Windows | `C:\Users\<用户名>\.stepcode` |

`~` 表示用户主目录，Agent 配置子目录为 `~/.stepcode/agent`。`.step-harness` 已退役，不再写入；启动时仅读取旧凭据做一次性迁移。

## 目录结构

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
~/.stepcode/
├── config.toml
├── auth.json
├── models.json
├── .credentials.json
├── device-id
├── models-store.json
├── bin/
├── logs/
├── marketplaces/
├── telemetry/
└── agent/
    ├── AGENTS.md
    ├── prompts/
    ├── skills/
    ├── agents/
    ├── themes/
    ├── extensions/
    ├── sessions/
    ├── trust.json
    ├── bin/
    ├── npm/
    └── git/
```

部分目录在首次使用对应功能时才创建。`bin/` 保存主程序和运行资源，`agent/bin/` 保存托管的搜索工具。

用户目录增加 `~/.claude/skills`、`~/.stepcode/skills`；项目目录增加受信任扫描范围内的 `.claude/skills`。Claude 目录自动发现，不必重复加入 `skills` 数组；`~/.codex/skills` 等非默认目录仍需显式指定。

## 关键文件

| 文件 | 内容 |
| - | - |
| `config.toml` | 全局设置和 MCP 服务器声明 |
| `auth.json` | API Key 与 OAuth 凭据；密钥值支持 `!command` 与 `$VAR` 取值 |
| `models.json` | 自定义模型和覆盖设置，打开 `/model` 时热重载 |
| `.credentials.json` | MCP OAuth 令牌 |
| `models-store.json` | 模型目录缓存 |
| `agent/trust.json` | 项目信任记录 |

凭据文件应限制为当前用户可读写。POSIX 环境使用 `0600` 权限；Windows 应检查对应账户的文件访问权限。不要将整个数据目录提交到 Git 或上传到公共网盘。

各配置字段的说明见[配置文件](/docs/zh/step-code/configuration/files)。

## 会话数据

会话位于 `agent/sessions/<编码后的工作目录>/`，每个会话使用一个 JSONL 文件，包含消息、工具调用、输出以及上下文摘要。使用 `/session` 查看当前文件的准确路径。

使用 `--session-dir` 指定会话目录；默认位置也可通过 `sessionDir` 或环境变量配置，以 `/session` 显示的路径为准。每条记录包含 `id` / `parentId`，当前位置为活跃叶子；压缩摘要、分支摘要、工具调用和输出都保存在同一文件中。

CLM 在会话目录下的 `live-context/<会话 ID>/` 维护工作副本（`mirror-*/LIVE_CONTEXT.md`）与归档（`archive/`）。没有会话文件时写入临时目录。它们与原始会话 JSONL 不是同一份文件。备份和清理时检查相关会话数据，不把归档全部当作短期缓存删除。

会话树和输入历史的使用见[会话与上下文](/docs/zh/step-code/guides/sessions)。不要直接编辑会话内部记录。

## 内置工具缓存

`rg`（ripgrep）和 `fd` 按需下载到 `~/.stepcode/agent/bin/`，Windows 对应 `rg.exe` / `fd.exe`。查找顺序为注入的自定义路径 > 已下载的本地副本 > 系统 PATH。

内容搜索的回退顺序为 ripgrep > `git grep`（搜索路径位于 Git 仓库时）> POSIX `grep`，全部不可用时报错。

删除该缓存后，下次使用可能重新下载。受限网络环境中请先检查系统 PATH 和下载访问权限。

## 日志

* `logs/`：运行日志，排查启动、连接或工具错误时优先查看。
* `telemetry/`：遥测缓冲，与会话记录分开保存。

日志可能包含错误详情和环境信息，分享前请审查。

模型调用、MCP、插件和部署会按操作需要访问外部服务。

遥测配置见[配置文件](/docs/zh/step-code/configuration/files#遥测)，代理与目录设置见[环境变量](/docs/zh/step-code/configuration/environment)。

## 项目级数据

| 位置 | 内容 |
| - | - |
| `.stepcode/config.toml` | 项目配置，需要项目信任 |
| `.stepcode/cron/tasks.json` | 持久定时任务 |
| `.stepcode/workflows/runs/` | workflow 运行记录 |
| `.stepcode/agents/`、`skills/`、`themes/`、`plugins/` | 项目自定义资源 |
| `.stepcode/plans/` | Plan 模式文件；`STEP_CODING_AGENT_PLAN_DIR` 可指定其他目录，相对路径按工作目录解析；已有会话仍沿用保存的计划路径，不自动搬迁 |
| `.stepcode/npm/` | 项目范围安装的 npm 包 |

可共享的配置和资源可按团队约定纳入版本管理；运行记录、缓存、私有路径和凭据应排除。不要直接将整个 `.stepcode/` 目录加入 Git。

## 清理数据

> [!WARNING]
>
> 删除项目 `.stepcode/` 会删除其中的配置、任务和自定义资源。

清理前退出 Step Code，并备份仍需使用的配置和会话。

| 需求 | 操作 |
| - | - |
| 重置配置 | 备份后移除 `config.toml` |
| 清理会话 | 删除不再需要的 `agent/sessions/` 内容 |
| 清理日志 | 删除旧的 `logs/` 文件 |
| 重新下载搜索工具 | 移除 `agent/bin/` 中对应工具 |
| 退出模型登录 | 使用 `/logout` |
| 清除 MCP 授权 | `step mcp logout <名称>` |
| 清理遥测缓冲 | 删除 `telemetry/`；这不会自动关闭遥测设置 |
| 刷新模型缓存 | 备份后移除 `models-store.json` |
| 彻底清理 | 备份后删除 Step Code 专用的数据目录，并清理安装器 PATH 项 |


# 环境变量
Source: https://platform.stepfun.com/docs/zh/step-code/configuration/environment



环境变量用于标记 Step Code 子进程、控制权限与多代理，以及在 CI 或容器中临时注入模型配置。设置后请从同一终端启动 Step Code。

## 供应商凭证

各供应商使用自己的 API Key 环境变量，例如 `ANTHROPIC_API_KEY`、`OPENAI_API_KEY`，常用供应商列表见[登录与模型](/docs/zh/step-code/configuration/models#api-key-供应商)。

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export STEP_API_KEY="YOUR_STEP_API_KEY"
```

将 `YOUR_STEP_API_KEY` 替换为实际密钥；请勿提交真实密钥。保存的账号及自定义模型配置也会影响所用凭据，排查方法见[登录与模型](/docs/zh/step-code/configuration/models)。

静态托管插件 steppage 使用 `STEPFUN_API_KEY`，请保留工具要求的变量名。

`STEP_BASE_URL` 指定阶跃模型服务基础地址，按账号地区和计费通道选择，见[阶跃 API 端点](/docs/zh/step-code/configuration/models#阶跃-api-端点)。

## 运行时开关

| 变量 | 说明 |
| - | - |
| `STEP_PERMISSION_PRESET`、`STEP_APPROVAL_MODE` | 覆盖权限模式，见[权限与安全](/docs/zh/step-code/guides/permissions#权限模式) |
| `STEP_DISABLE_WORKFLOW` | 设置为 `1` 关闭 workflow / ultraloop 注册 |

## 数据与计划目录

| 变量 | 用途 |
| - | - |
| `STEP_CODING_AGENT_DIR` | Agent 资源根目录，其父目录保存配置、凭据和模型文件 |
| `STEP_CODING_AGENT_SESSION_DIR` | 会话目录 |
| `STEP_CODING_AGENT_PLAN_DIR` | 新计划文件目录，可放到工作区外；相对路径按工作目录解析，已有会话仍沿用保存的计划路径，不自动搬迁 |

目录结构见[数据路径](/docs/zh/step-code/configuration/data-paths)。

## 用环境变量注入模型

| 变量 | 说明 |
| - | - |
| `STEPCODE_CONFIG_PATH` | 指向 JSON 模型配置，启动时注入模型目录 |
| `STEP_API_KEY` | 内置 `step` 平台的密钥变量 |
| `STEP_MAX_CONTEXT_TOKENS` | 覆盖注入模型的上下文窗口 |
| `STEP_MAX_OUTPUT_TOKENS` | 覆盖注入模型的最大输出 |

`STEPCODE_CONFIG_PATH` 保存模型和权限偏好时会写回该 JSON 文件，而不是 `models.json`；不要将其视为只读临时模型目录。

适合 CI、容器等场景临时接入模型端点。请在注入配置中明确所需的模型能力与兼容选项，并按服务端支持的参数配置。

持久的自定义模型配置见[登录与模型](/docs/zh/step-code/configuration/models)。

## 代理

`HTTP_PROXY` / `HTTPS_PROXY` 配置出站代理，也可在全局 `config.toml` 设置 `httpProxy`。`NO_PROXY` 按主机名或后缀匹配绕过代理的目标。

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1"
step
```

将端口替换为实际代理端口。此例让回环请求不经过代理。

## 进程标记

| 变量 | 说明 |
| - | - |
| `AI_AGENT=step` | 通用进程标记，让外部工具识别进程由 Step Code 启动 |

该标记会被子进程继承；SDK 嵌入时不自动设置。

## 遥测

遥测使用全局 `config.toml` 配置，开关见[配置文件](/docs/zh/step-code/configuration/files#遥测)。模型请求与主动反馈分别管理。


# 配置文件
Source: https://platform.stepfun.com/docs/zh/step-code/configuration/files



使用 `config.toml` 设置默认模型、权限、上下文压缩、界面和 MCP 服务器。临时启动参数不会自动改写配置文件。

## 配置文件位置

| 级别 | 默认位置 | 作用 |
| - | - | - |
| 全局 | `~/.stepcode/config.toml` | 对所有项目生效 |
| 项目 | `<项目>/.stepcode/config.toml` | 覆盖全局设置，需要项目信任 |

项目配置按字段覆盖全局配置：嵌套对象逐键合并，数组整体替换。代理、项目信任默认值等标为“仅全局”的配置不接受项目级覆盖。

全局配置在首次运行时自动创建。写入使用临时文件加改名的原子替换方式，并保留文件头注释块。TOML 不支持 `null`，不支持的表达会被剥离；取消可选值时应删除对应配置项。

其他本地数据的位置见[数据路径](/docs/zh/step-code/configuration/data-paths)。

### 外部 JSON 注入配置

`STEPCODE_CONFIG_PATH` 指向外部 JSON 配置。保存模型和权限偏好时会写回该 JSON 文件，而不是 `models.json`；不要将其视为只读临时模型目录。

## 配置示例

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
theme = "step-blue"
defaultProvider = "step"
defaultModel = "step-3.7-flash"
permissionPreset = "approve-for-me"
autoResume = true

[telemetry]
enabled = true
```

示例使用 Approve for Me 权限模式；需要修改文件和运行命令前确认时，将 `permissionPreset` 改为 `"ask"`。各权限模式的行为见[权限与安全](/docs/zh/step-code/guides/permissions)。

## 顶层字段

### 模型与思考

| 字段 | 说明 |
| - | - |
| `defaultProvider`、`defaultModel` | 默认平台和模型，可在 `/model` 中按 Ctrl+S 保存 |
| `defaultThinkingLevel` | 默认思考级别 |
| `modelThinkingLevels` | 按 `provider/modelId` 设置单个模型的思考级别 |
| `thinkingBudgets` | 各思考级别的 token 预算 |
| `hideThinkingBlock` | 隐藏思考块展示，默认 `false` |
| `showCacheMissNotices` | 显示缓存未命中和压缩成本提示，默认 `false` |

客户端级别包括 `off`、`minimal`、`low`、`medium`、`high`、`xhigh` 和 `max`。可用级别及其实际行为取决于供应商和模型。

平台接入与模型选择见[登录与模型](/docs/zh/step-code/configuration/models)。

### 界面

| 字段 | 默认值 | 说明 |
| - | - | - |
| `theme` | `step-blue` | 主题名称；选择与创建方法见[自定义主题](/docs/zh/step-code/customization/themes) |
| `statusTips` | `true` | 每轮显示一条工作行提示，设为 `false` 可关闭 |
| `quietStartup` | `false` | 精简启动信息 |
| `collapseChangelog` | `false` | 折叠更新日志 |
| `doubleEscapeAction` | `tree` | 空输入框连续按 Esc 的动作：`tree`、`fork`、`none` |
| `treeFilterMode` | `default` | `default`、`no-tools`、`user-only`、`labeled-only`、`all` |
| `editorPaddingX` | `0` | 输入框水平内边距，范围 0–3 |
| `outputPad` | `1` | 输出水平留白，取 0 或 1 |
| `autocompleteMaxVisible` | `5` | 补全菜单显示数量，范围 3–20 |
| `showHardwareCursor` | `false` | 显示终端硬件光标 |
| `externalEditor` | 未设置 | 外部编辑器；未设置时依次读取 `VISUAL`、`EDITOR` |

关闭工作行提示：

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
statusTips = false
```

### 会话与网络

| 字段 | 默认值 | 说明 |
| - | - | - |
| `sessionDir` | 未设置 | 自定义会话存储目录 |
| `transport` | `auto` | 模型传输方式：`auto`、`sse`、`websocket`、`websocket-cached`，需供应商支持 |
| `steeringMode`、`followUpMode` | `one-at-a-time` | 流式期间消息投递方式 |
| `httpProxy` | 未设置 | 出站代理，仅全局 |
| `httpIdleTimeoutMs` | 300,000 | HTTP 空闲超时，单位毫秒；0 关闭 |
| `websocketConnectTimeoutMs` | 15,000 | WebSocket 连接超时，单位毫秒；0 关闭 |

环境变量配置见[环境变量](/docs/zh/step-code/configuration/environment)。

### Shell 与命令

| 字段 | 默认值 | 说明 |
| - | - | - |
| `shellPath` | 未设置 | 自定义 Shell 路径，支持 `~` 展开，适用于 Windows Cygwin 等场景 |
| `shellCommandPrefix` | 未设置 | 在每条 Shell 命令前执行的内容，例如启用 alias |
| `npmCommand` | 未设置 | npm 调用命令，argv 形式，例如 `["mise", "exec", "node@20", "--", "npm"]` |

### 项目与权限

| 字段 | 说明 |
| - | - |
| `permissionPreset` | 默认 `approve-for-me`，可选 `ask`、`approve-for-me` 或 `full-access`；已保存的旧权限模式会重置为 Ask。模式通过 `/permissions` 选择，行为见[权限与安全](/docs/zh/step-code/guides/permissions) |
| `defaultProjectTrust` | 未信任项目的资源加载策略，默认 `ask`，仅全局 |
| `enableAnalytics` | 可选使用分析开关，默认 `false`；与反馈及其他服务设置分别管理 |

项目资源的加载与工具审批见[权限与安全](/docs/zh/step-code/guides/permissions)。

## 分节配置

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[compaction]
enabled = true
reserveTokens = 16384
keepRecentTokens = 20000
contextProjection = "clm-v1"

[branchSummary]
reserveTokens = 16384
skipPrompt = false

[retry]
enabled = true
maxRetries = 3
baseDelayMs = 2000

[thinkingBudgets]
minimal = 1024
low = 4096
medium = 10240
high = 32768

[images]
autoResize = true
blockImages = false

[terminal]
showImages = true
imageWidthCells = 60
clearOnShrink = false
showTerminalProgress = false
hyperlinks = "auto"
images = "auto"
trueColor = "auto"

[markdown]
codeBlockIndent = "  "
mermaid = "streaming"
```

* `[compaction]` 的 `enabled = false` 只关闭自动压缩；`reserveTokens` 为预留窗口，`keepRecentTokens` 为保留的近期消息量。
* `[compaction].contextProjection` 未显式设置且自动压缩启用时默认为 `clm-v1`；`off` 只保留原有摘要压缩，不启用 CLM；`lightweight-v1` 为轻量投影。关闭自动压缩会同时关闭隐式 CLM。
* `[branchSummary].skipPrompt = true` 时切换分支不再询问，默认不生成摘要。
* `[retry]` 的 `baseDelayMs = 2000` 采用指数退避，等待 2、4、8 秒。`provider.maxRetries` 保持默认 `0`；设为正值会使 SDK 重试先于 Step 处理配额耗尽错误，可能等待至配额重置。`provider.timeoutMs` 可设置单请求超时。
* `[thinkingBudgets]` 配置各思考级别的 token 预算。
* `[images].autoResize = true` 将图片压缩到 2,000 px 以内。
* `[images].blockImages = true` 阻止向模型发送图片；`[terminal].showImages` 只控制显示。
* `[terminal].images` 可指定 `kitty`、`iterm2`、`auto` 或 `false`，应与终端能力匹配。
* `[terminal].imageWidthCells` 是行内图片的终端列宽；`clearOnShrink` 控制收缩时清理空行；`showTerminalProgress` 控制 OSC 9;4 进度指示；`hyperlinks` 可取 `true`、`false` 或 `"auto"`。
* `[markdown].mermaid` 可取 `streaming`、`final` 或 `off`。
* `[warnings].anthropicExtraUsage` 默认 `true`，控制 Claude Pro/Max 额外用量提示。

## MCP 服务器

`[mcp_servers.<名称>]` 声明全局 MCP 服务器。接入步骤、传输类型、鉴权和字段说明统一见[MCP](/docs/zh/step-code/customization/mcp)。

## 工具与资源数组

| 字段 | 作用 |
| - | - |
| `defaultTools` | 原生内置工具集合，如 `read`、`bash`、`edit`、`write`、`grep`、`find`、`ls`；Step 和扩展工具的选择见[内置工具](/docs/zh/step-code/reference/tools) |
| `enabledModels` | Ctrl+P 循环选择的模型集合，支持 glob，例如 `["claude-*", "gpt-4o"]` |
| `packages` | 安装和加载的资源包 |
| `extensions`、`skills`、`prompts`、`themes` | 额外资源路径，支持 glob、排除和精确选择 |
| `enableSkillCommands` | 将 Skills 注册为 `/skill:<名称>`，默认 `true` |

资源数组可填写文件或目录，支持 glob、`!` 排除以及 `+path` / `-path` 精确控制。全局相对路径按 `~/.stepcode/agent` 解析，项目相对路径按项目 `.stepcode` 解析。工具启动参数见[内置工具](/docs/zh/step-code/reference/tools)。

## TUI 相关设置

| 字段 | 默认值 | 说明 |
| - | - | - |
| `tuiMode` | `regular` | 可选实验性 `fullscreen` |
| `fullscreenExitOutput` | `transcript` | 退出时显示会话记录，或选择 `resume-hint` |
| `fullscreenScrollbar` | `auto` | 可选 `always`、`hidden` |
| `fullscreenCopyOnSelect` | `true` | 选中即复制；关闭后可用 Ctrl+X |

## 废弃项

| 项目 | 说明 |
| - | - |
| `~/.stepcode/agent/settings.json` | 已退役，不再读写；旧设置手动迁移到 `config.toml` |
| `~/.stepcode/agent/step-settings.json` | 已退役 |
| `~/.stepcode/agent/auth.json`、`agent/models.json` | 旧位置，已上提到 `~/.stepcode` 根目录 |
| `.step-harness` | 已退役，不再写入；启动时仅读取旧凭据做一次性迁移 |

## 遥测

在全局 `config.toml` 中关闭遥测：

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[telemetry]
enabled = false
```

此设置控制遥测；模型请求、MCP 调用和主动反馈分别管理。数据处理与分享要求见[权限与安全](/docs/zh/step-code/guides/permissions)。


# 登录与模型
Source: https://platform.stepfun.com/docs/zh/step-code/configuration/models



Step Code 支持订阅账号登录、API Key 和云平台，也可以通过 `models.json` 接入 OpenAI / Anthropic / Google 兼容端点，例如 Ollama、vLLM 和 LM Studio。

## 接入方式

| 方式 | 设置入口 |
| - | - |
| Step 账号登录 | `/login` 选择阶跃账号入口并完成授权 |
| API Key | 阶跃密钥可通过 `/login` 配置；其他供应商使用环境变量或自定义平台配置 |
| 云平台 | Azure OpenAI、Amazon Bedrock、Google Vertex AI、Cloudflare |
| 自定义模型 | `~/.stepcode/models.json` |

排查凭据时，请检查命令行 `--api-key`、已保存的 `auth.json`、`models.json` 中的平台配置及进程环境变量。使用同一平台的多个配置来源时，先确认实际选中的账号和端点。

## 订阅登录

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/login
```

阶跃账号选择 Step Plan（国内）或 Step Plan Oversea（海外）。OAuth 凭据会按登录流程刷新；使用 `/logout` 清除相应凭据。

| 平台 | 登录网站 | 计费通道 |
| - | - | - |
| Step Plan | `platform.stepfun.com` | 国内 Step Plan |
| Step Plan Oversea | `platform.stepfun.ai` | 海外 Step Plan |
| 国内开放平台 API Key | `platform.stepfun.com/interface-key` | 按量付费 |
| 海外开放平台 API Key | `platform.stepfun.ai/interface-key` | 按量付费 |

选择错误通道不会因为已有订阅而自动改用订阅额度。可用模型和额度取决于账户权限，套餐规则见 [Step Plan](/docs/zh/step-plan/overview)。

在 SSH、服务器或容器终端中登录的方式见[远程登录](#远程登录)。

## 阶跃 API 端点

通过环境变量配置阶跃 API Key 时，同时指定与账号匹配的 `STEP_BASE_URL`：

| 账号与通道 | 基础地址 |
| - | - |
| 国内 Step Plan | `https://api.stepfun.com/step_plan/v1` |
| 海外 Step Plan | `https://api.stepfun.ai/step_plan/v1` |
| 国内开放平台按量付费 | `https://api.stepfun.com/v1` |
| 海外开放平台按量付费 | `https://api.stepfun.ai/v1` |

国内 Step Plan 的 Bash 示例：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export STEP_API_KEY="YOUR_STEP_API_KEY"
export STEP_BASE_URL="https://api.stepfun.com/step_plan/v1"
step --provider step
```

请妥善保管 API Key，不要写入仓库或分享给他人。获得该 Key 的人可以使用您的账号调用模型并产生用量。

## API Key 供应商

| 供应商 | 环境变量 |
| - | - |
| Step | `STEP_API_KEY` |
| Anthropic | `ANTHROPIC_API_KEY` |
| OpenAI | `OPENAI_API_KEY` |
| Google Gemini | `GEMINI_API_KEY` |
| DeepSeek | `DEEPSEEK_API_KEY` |
| OpenRouter | `OPENROUTER_API_KEY` |
| Kimi For Coding | `KIMI_API_KEY` |
| MiniMax | `MINIMAX_API_KEY` |
| xAI | `XAI_API_KEY` |
| Groq | `GROQ_API_KEY` |
| Mistral | `MISTRAL_API_KEY` |

例如，在 Bash 或 Zsh 中配置 Anthropic：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export ANTHROPIC_API_KEY="YOUR_ANTHROPIC_API_KEY"
step --provider anthropic
```

占位符须替换为对应供应商的密钥，不能将 Step 密钥用于其他供应商。通过阶跃登录保存的密钥位于 `~/.stepcode/auth.json`，请勿提交到代码仓库。

运行时环境变量配置见[环境变量](/docs/zh/step-code/configuration/environment)。

## 云平台

| 平台 | 配置要求 |
| - | - |
| Amazon Bedrock | `AWS_PROFILE` 或 `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`；`AWS_REGION` 默认 `us-east-1`；支持 ECS task roles 和 IRSA |
| Google Vertex AI | 运行 `gcloud auth application-default login`，设置 `GOOGLE_CLOUD_PROJECT` 和 `GOOGLE_CLOUD_LOCATION`（如 `us-central1`） |
| Azure OpenAI | `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_BASE_URL`，根端点自动归一到 `/openai/v1`；`AZURE_OPENAI_DEPLOYMENT_NAME_MAP` 映射部署名 |

云平台的模型部署名、可用区域和 IAM 权限由该平台管理。请先确认账户可调用目标模型，再在 Step Code 中选择。

## 自定义模型（models.json）

编辑 `~/.stepcode/models.json`，重新打开 `/model` 加载变更。以下示例接入本地 Ollama：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        {"id": "llama3.1:8b"},
        {"id": "qwen2.5-coder:7b"}
      ]
    }
  }
}
```

先在 Ollama 中准备对应模型。这里的 `ollama` 是本地服务的非空 `apiKey` 占位值；本地无鉴权服务也需要该字段，才能出现在 `/model` 中。远程鉴权服务必须填写其实际凭据。

| 平台字段 | 说明 |
| - | - |
| `baseUrl` | OpenAI 兼容端点包含 `/v1`；`google-generative-ai` 填到 `/v1beta` 根 |
| `api` | 如 `openai-completions`、`openai-responses`、`azure-openai-responses`、`anthropic-messages`、`google-generative-ai` |
| `apiKey`、`headers` | 凭据和附加请求头 |
| `models` | 自定义模型列表 |
| `modelOverrides` | 覆盖已有模型属性 |
| `compat` | 调整兼容请求行为，按服务端支持设置 |

模型字段包括 `id`、`name`、`reasoning`、`contextWindow`、`maxTokens`、`cost`、`thinkingLevelMap` 和 `samplingParams`。`id` 必填，`contextWindow` 默认 128,000，`maxTokens` 默认 16,384；可按模型规格覆盖。

`samplingParams` 用于 OpenAI 兼容请求的采样参数合并，可能覆盖同名请求字段。不要添加服务端不支持的字段。仅覆盖 `baseUrl` 可以修改内置平台端点，提供 `models` 则按模型 ID 更新或添加。

Ollama / vLLM / SGLang 常需在 `compat` 中设置 `supportsDeveloperRole = false` 和 `supportsReasoningEffort = false`。

模型加载和登录问题见[常见问题](/docs/zh/step-code/reference/faq)。

## 切换模型

* `/model` 打开模型选择器，Ctrl+S 保存为启动默认。
* Ctrl+P 在 `enabledModels` 中循环选择，反向快捷键见[键盘快捷键](/docs/zh/step-code/reference/keyboard-shortcuts)。
* 命令行使用 `step --provider <平台> --model <模型 ID>`。
* `/effort` 调整思考级别；可选级别和执行档位由模型决定。

默认模型的配置字段见[配置文件](/docs/zh/step-code/configuration/files)。

## 远程登录

在 SSH、服务器或容器终端中，可运行 `step login --no-browser` 获取授权链接，在本机或其他设备的浏览器中完成登录。该命令仍要求交互终端，不依赖本地回调端口。


# Agent 与 subagent
Source: https://platform.stepfun.com/docs/zh/step-code/customization/agents



Step Code 提供四个内置子代理角色，并支持使用 Markdown 文件定义自定义 Agent，通过 workflow 编排多代理并行任务。

## 内置 agent

| 角色 | 职责 | 工具范围 |
| - | - | - |
| `general` | 通用实现任务 | 全部工具 |
| `explore` | 只读仓库侦察 | `read_file`、`find_files`、`search_files`、`list_directory` |
| `review` | 正确性与回归审查 | 只读工具和命令执行 |
| `planner` | 调查并制定实施计划 | 只读工具和命令执行 |

子代理不直接与用户对话，结果返回主代理。具备命令执行能力的角色仍可执行写入操作，实际行为受工具权限约束。

## subagent 工具

### single、parallel 与 chain

| 模式 | 行为 |
| - | - |
| single | 一个角色处理一个任务 |
| parallel | 多个任务并行执行 |
| chain | 顺序执行，后续任务通过 `{previous}` 引用前一步结果 |

您可以通过自然语言授权主代理使用这些能力：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请并行委派两个只读任务：一个检查 API 错误处理，一个检查对应测试覆盖。分别返回证据和建议，由主代理汇总，不修改文件。
```

### 后台 lane

后台任务需保持 Step Code 进程运行。

后台任务的完成通知会返回主代理；需要停止任务时，请明确指定对应的任务。

## workflow 与 ultraloop

workflow 在无网络、无文件系统的沙箱 VM 中运行 JavaScript 编排脚本，提供 `phase()`、`parallel()`、`pipeline()`、`agent()` 和 `iterate()` 原语。运行记录保存在项目 `.stepcode/workflows/runs/`，支持断点续跑，使用 `/workflows` 查看已保存的 workflow 与近期运行。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
ultraloop 按模块审查测试覆盖。各子代理只检查分配的目录，返回缺失场景；主代理去重并给出补测计划。
```

多代理调用要求显式授权，该要求通过提示词约束；未授权调用会被记录，但不会在执行层被拦截。在消息中使用 `ultraloop` 或 `ultracode`，或使用 `/ultraloop on` 开启会话级授权、`/ultraloop off` 关闭。单条消息的授权不自动延续，也不从任务规模推断。

`STEP_DISABLE_WORKFLOW=1` 禁用注册。

多代理任务示例见[常见使用案例](/docs/zh/step-code/guides/use-cases)。

`/ultracode [on|off|status|help]` 管理多代理协作，`/ultraloop` 为别名；`/workflows` 查看工作流与运行记录。开关按会话保存，恢复同一会话会恢复状态，没有保存状态的新会话默认关闭。

## 自定义 agent

使用 Markdown frontmatter 定义角色，正文作为系统指令：

```markdown theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
---
name: db-migrator
description: 设计可回滚的数据库迁移方案并审查迁移脚本
tools: read_file, run_command, edit_file
---

先检查现有迁移约定，再制定方案。所有迁移必须提供回滚步骤。
未经明确授权，不连接生产数据库，不执行生产迁移。
```

| 项目 | 说明 |
| - | - |
| 用户目录 | `~/.stepcode/agent/agents/*.md` |
| 项目目录 | `.stepcode/agents/` |
| 必填字段 | `name`、`description` |
| 可选字段 | `tools`、`model` |
| 同名优先级 | 项目覆盖用户，用户覆盖内置 |

`tools` 可以使用数组或逗号分隔列表。项目角色需显式纳入发现范围，调用时通过 `agentScope: "both"` 启用，并按提示确认。

专项工作流的定义见[Agent Skills](/docs/zh/step-code/customization/skills)。

通过插件分发 Agent 的方式见[插件与 Packages](/docs/zh/step-code/customization/plugins)。

## 上下文隔离与安全

沙箱 VM 的限制仅作用于 workflow 编排脚本，子任务进程仍受操作系统权限控制。

* 子代理拥有独立上下文和用量，主代理主要接收结果摘要。
* 子代理可能与主代理共享工作目录，文件修改会作用于同一工作树。
* 并行写入时应划分互不重叠的文件，或明确安排独立 Git worktree。
* Git worktree 只隔离工作树，不限制其他目录、网络或凭据访问。
* 完成后先检查差异和测试，再合并结果；未合并改动不要直接清理。

默认规模为 medium（约 15 个 Agent 以内），除非明确要求扩大。
通用审批与访问边界见[权限与安全](/docs/zh/step-code/guides/permissions)。


# MCP
Source: https://platform.stepfun.com/docs/zh/step-code/customization/mcp



MCP（Model Context Protocol）将本地或远程工具接入 Step Code。服务器连接后，模型可以按任务需要调用已注册的工具。

## 接入方式

| 传输 | 配置 | 适用场景 |
| - | - | - |
| stdio | `command`、`args`、可选 `env` | 启动本地工具进程 |
| Streamable HTTP | `url` | 连接远程 MCP 服务 |

不支持旧版 SSE 传输。插件也可以声明 MCP 服务器，安装和启用方式见[插件与 Packages](/docs/zh/step-code/customization/plugins)。

从其他工具导入已有配置的方式见[从其他工具迁移](/docs/zh/step-code/guides/migration)。

## 添加 MCP 服务

1. 确认本地服务的启动命令、参数与依赖，或远程服务的 URL 与鉴权要求。
2. 在 `~/.stepcode/config.toml` 的 `[mcp_servers.<名称>]` 中填写声明，字段格式见下方[配置](#配置)。修改已有配置时保留其他服务。
3. 完成对应鉴权后，重启 Step Code，并使用 `/mcp` 检查连接。

## 鉴权

Bearer token 应从运行 Step Code 的进程环境读取：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export EXAMPLE_TOKEN="YOUR_MCP_TOKEN"
step
```

OAuth 服务使用：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step mcp login <服务器名称>
step mcp logout <服务器名称>
```

OAuth 使用动态客户端注册、PKCE 和本地回调。令牌保存在 `~/.stepcode/.credentials.json`，权限为 `0600`。模型平台登录与 MCP 服务授权是两套凭据。

## 交互内查看

运行 `/mcp` 查看服务器状态和已加载工具数。常见状态包括 `connecting`、`connected` 和 `failed`。`enabled = false` 的服务器不进入列表。

连接失败时，先检查命令是否存在、环境变量是否传入、远程地址是否可达，以及授权是否有效。

请再指定一次低风险工具调用，检查实际返回结果。连接状态用于确认服务连接，工具结果用于确认所需功能可用。

## 工具命名与过滤

工具以 `<服务器名>__<工具名>` 命名，非法字符转换为下划线。通过 `enabled_tools` 和 `disabled_tools` 在注册阶段过滤：设置 `enabled_tools` 后，其他工具对模型不可达。

## 配置

在全局 `~/.stepcode/config.toml` 的 `[mcp_servers.<名称>]` 中声明服务器。项目级 MCP 来自已安装插件 manifest 的 `mcpServers` 叠加：

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[mcp_servers.local-tools]
command = "node"
args = ["/absolute/path/to/mcp-server.js"]
env = { LOG_LEVEL = "info" }

[mcp_servers.remote]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "EXAMPLE_TOKEN"

[mcp_servers.remote.oauth]
callback_port = 8976
```

示例中的本地路径和远程地址需替换为实际服务；Bearer 与 OAuth 按服务要求选择，不必同时配置。

| 字段 | 说明 |
| - | - |
| `command` | stdio 启动命令，与 `url` 二选一 |
| `args`、`env`、`cwd` | 命令参数、子进程环境变量和工作目录，按需填写 |
| `url` | Streamable HTTP 端点 |
| `bearer_token_env_var` | 保存 Bearer token 的环境变量名 |
| `http_headers` | 字面请求头，避免直接写入真实密钥 |
| `env_http_headers` | 请求头对应的环境变量名，缺少变量时报告错误 |
| `startup_timeout_sec` | 启动超时，默认 30 秒 |
| `tool_timeout_sec` | 单次调用超时，默认 300 秒 |
| `enabled` | 是否启用，默认 `true` |
| `enabled_tools`、`disabled_tools` | 启用或禁用的工具集合 |

全局配置文件说明见[配置文件](/docs/zh/step-code/configuration/files)。

## 命令行管理

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step mcp list
step mcp list --json
step mcp get <服务器名称>
step mcp add remote --url https://mcp.example.com/mcp
step mcp add local-tools -- node /absolute/path/to/mcp-server.js
step mcp remove <服务器名称>
```

`--url` 与本地命令互斥。`--bearer-token-env-var` 只用于 HTTP，`--env` 设置的是 stdio 子进程环境，并不是 HTTP 请求头。

## 安全性

stdio 服务会启动本地进程，远程服务会收到调用参数；服务返回内容也可能进入模型上下文。连接前请确认来源与访问范围，并关闭不需要的工具。通用审批规则见[权限与安全](/docs/zh/step-code/guides/permissions)。


# 插件与 Packages
Source: https://platform.stepfun.com/docs/zh/step-code/customization/plugins



Step Code 通过插件市场和 Packages 分发扩展、Skills、主题、Agent 和 MCP 服务器。

## 两种分发形态

| 形态 | 管理入口 | 内容 |
| - | - | - |
| Packages 资源包 | `step install` 等命令 | TypeScript 扩展、Skills、prompt 模板、主题 |
| 插件市场 | `/plugin` | 声明式 manifest、Skills、Agent、命令、MCP |

## 安装插件

1. 运行 `/plugin` 查看已配置市场中的插件。
2. 使用 `/plugin install <插件名称>` 安装需要的插件。
3. 安装含 MCP 的插件后重启 Step Code，通过 `/mcp` 检查服务，并验证实际需要的功能。

## 安装与管理 Packages

资源包使用独立的命令管理。命令格式如下，来源可以是本地目录、npm 包或 Git 仓库：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step install <资源包来源>
step list
step remove <资源包来源>
```

* 默认安装到用户范围并写入全局配置。
* `-l` 写入项目 `.stepcode/config.toml`；团队成员信任项目后，启动时自动补装。
* `step -e <来源>` 可临时加载扩展，不将它写入持久配置，但仍会执行扩展代码。

## 包过滤与启停

在 `config.toml` 中指定加载范围：

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[[packages]]
source = "npm:@example/package"
extensions = ["extensions/*.ts", "!extensions/legacy.ts"]
```

按需使用 glob、`!` 排除，以及 `+path` / `-path` 精确增删资源。也可以运行 `step config`，使用 Tab 切换全局与项目范围并管理启停。

同名包的项目级配置覆盖全局条目，项目资源仍受信任设置控制。

## StepPage

`steppage` 用于发布静态目录或 ZIP 并管理站点版本。先通过 `/mcp` 检查 StepPage 是否已就绪；插件缺失或此前主动卸载时，使用 `/plugin install steppage` 安装并重启。StepPage 自动准备需要外部 Node.js 20 或更新版本；这不是 Step Code 独立程序本身的依赖。准备失败可运行 `step mcp prepare` 后重启检查。安装、部署与回滚流程见[发布 StepPage](/docs/zh/step-code/reference/steppage)。内置市场还提供 `playwright` 浏览器操控插件。

## 创建本地资源包

创建 `my-step-package` 目录，保存以下两个文件。

`my-step-package/package.json`：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "name": "my-step-package",
  "version": "1.0.0",
  "private": true,
  "pi": { "skills": ["./skills"] }
}
```

`my-step-package/skills/project-summary/SKILL.md`:

```markdown theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
---
name: project-summary
description: 根据用户提供的 README 总结项目用途。用户需要项目摘要时使用。
---

阅读用户提供的 README，概括项目用途和已记录的启动方式。未提供的信息标记为“未说明”。不修改文件。
```

从 `my-step-package` 的父目录安装：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step install ./my-step-package
step list
```

在包含 `README.md` 的项目中运行 `step @README.md`，然后在交互输入框中执行 `/skill:project-summary`，检查摘要是否符合文件内容。本地包按路径加载，请保留源目录。

## 包来源与 manifest

| 来源 | 行为 |
| - | - |
| `npm:` | 通过包管理器安装；指定版本的条目保持锁定 |
| `git:` 或仓库 URL | 克隆仓库；配置的 tag 或 commit 不自动移动到新引用 |
| 本地文件 | 作为单个扩展加载 |
| 本地目录 | 按资源包规则发现内容 |

资源包在 `package.json` 的 `pi` 字段中声明 `extensions`、`skills`、`prompts`、`themes` 四类资源路径，支持 glob 和 `!` 排除；无 manifest 时按同名约定目录加载。资源路径相对包根目录解析。

用户级包通常保存在 `~/.stepcode/agent/npm/` 和 `git/`；项目级包保存在 `.stepcode/npm/` 或 `.stepcode/git/`。不要在托管克隆中保留唯一的未提交修改，更新可能重新对齐锁定引用。

Skill 格式见[Agent Skills](/docs/zh/step-code/customization/skills)。

## 插件清单格式

原生 manifest 使用 `step.plugin.json`，兼容 `.claude-plugin/plugin.json` 和市场清单 `marketplace.json`。字段包括 `id`、`name`、`description`、`version`、`entry`、`skills`、`agents`、`commands`、`mcpServers` 和 `provision`。`id` 为必填字段；插件清单文件的大小上限为 512 KiB；`entry` 是可执行入口字段，仅记录，不加载。

## 依赖与打包

第三方运行时依赖放在 `dependencies`，安装时使用 `npm install --omit=dev`。由运行时提供的核心包放在 `peerDependencies: "*"`，不重复打包。

依赖其他 Step 包时，在 `dependencies` 和 `bundledDependencies` 中声明，并通过 `node_modules/` 路径引用资源。

## 插件市场

| 命令 | 作用 |
| - | - |
| `/plugin` | 打开管理菜单 |
| `/plugin install <插件>` | 安装插件 |
| `/plugin remove <插件>` | 卸载插件 |
| `/plugin marketplace list` | 列出市场源 |
| `/plugin marketplace add` | 添加市场源 |
| `/plugin marketplace update` | 更新市场索引 |
| `/plugin marketplace remove` | 移除市场源 |

安装或卸载包含 MCP 的插件后，重启 Step Code 才会启动或停用对应服务器。使用 `/mcp` 检查加载结果。

MCP 服务器配置字段见[MCP](/docs/zh/step-code/customization/mcp)。

自定义 Agent 的格式见[Agent 与 subagent](/docs/zh/step-code/customization/agents)。

## 安全注意事项

扩展、包和 stdio MCP 可以按当前系统用户权限执行代码；Skills 和 Agent 指令也可能引导执行命令。安装包或 Git 依赖可能执行包管理器操作，请审查来源、版本和安装脚本，只安装可信来源，并为项目提供最小必要凭据。

Step Code 没有文件式 Hooks；等价的自动化拦截使用扩展事件 `tool_call`、`tool_result`、`input` 等实现。
通用工具审批和数据访问规则见[权限与安全](/docs/zh/step-code/guides/permissions)。


# 项目指引
Source: https://platform.stepfun.com/docs/zh/step-code/customization/project-instructions



项目指引记录团队的开发约定、检查命令和操作限制。Step Code 加载指引后，将其作为处理项目任务的上下文。

## 创建项目指引

1. 在项目根目录创建 `AGENTS.md`。已有该文件时，将需要的约定合并进去。
2. 写入适用于当前项目的要求。例如：

```markdown theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# 项目指引

- 修改代码前，阅读项目的构建配置与测试命令。
- 修改行为时补充对应测试，并报告实际执行的检查结果。
- 不连接生产数据库，不执行生产迁移。
- 不把密钥或私人配置写入提交内容。
```

3. 在 Step Code 中运行 `/reload` 或重新启动，以加载变更。

也可以运行 `/init`，让模型检查项目并生成指引；保存前请核对其中的命令、路径与约束。开始使用后，可要求模型说明本次任务适用的项目约定，检查其引用是否与文件一致。

## 加载范围与选择顺序

| 范围 | 位置 |
| - | - |
| 全局 | `~/.stepcode/agent/AGENTS.md` |
| 项目 | 当前目录及其父目录中的指引文件 |

每个目录按以下顺序选择第一个存在的文件：

1. `AGENTS.override.md`
2. `AGENTS.md`
3. `CLAUDE.md`

Step Code 向上查找到文件系统根。需要为整个团队共享的规则放在项目文件中，个人偏好放在全局文件中。启动参数 `--no-context-files` 可关闭自动发现，参数说明见 [`step` 命令](/docs/zh/step-code/reference/cli)。

## 复用现有指引

现有 `CLAUDE.md` 可以继续使用。复用前，请检查其中的工具名称、命令、路径与模型能力要求是否适用于 Step Code。其他资源的导入方式见[从其他工具迁移](/docs/zh/step-code/guides/migration)。

项目指引用于描述工作要求。需要限制工具操作或项目资源加载时，另行设置[权限与安全](/docs/zh/step-code/guides/permissions)。专项任务可封装为 [Agent Skills](/docs/zh/step-code/customization/skills)；子代理角色文件见 [Agent 与 subagent](/docs/zh/step-code/customization/agents)。


# Agent Skills
Source: https://platform.stepfun.com/docs/zh/step-code/customization/skills



将专项工作流、脚本和参考资料组织为 Skill，供模型按需读取或通过斜杠命令调用。

## Skill 结构

Skill 是以 `SKILL.md` 为入口的能力包，遵循 [Agent Skills](https://agentskills.io/) 格式。启动时主要加载名称和描述，模型判断相关后再读取完整指令，减少不必要的上下文占用。

## 创建 Skill

保存为 `~/.stepcode/agent/skills/api-review/SKILL.md`：

```markdown theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
---
name: api-review
description: 审查 REST API 变更的兼容性与文档完整性。当任务涉及路由、请求响应类型或 OpenAPI 变更时使用。
---

# API 变更审查

1. 使用 git diff 找出本次变更涉及的路由与类型。
2. 检查破坏性变更、错误码、鉴权要求和示例是否同步。
3. 参照 references/checklist.md 输出审查结论。
```

在同目录的 `references/checklist.md` 中编写项目审查清单，然后运行 `/reload`，使用 `/skill:api-review`。包含辅助脚本的 Skill 可能执行本地命令，只加载可信来源。

`references/checklist.md` 可使用以下内容：

```markdown theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# 接口检查清单

- 请求和响应字段是否与文档一致？
- 是否改变鉴权、错误码或已有客户端的行为？
- 是否补充对应测试与调用示例？
```

## 调用

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/skill:api-review 检查本次接口改动
```

`enableSkillCommands` 默认启用，将 Skill 注册为 `/skill:<名称>`。参数以 `User: <参数>` 追加到 Skill 内容后。

模型根据 `description` 判断何时读取 Skill，不一定会自动读取。需要明确执行某项工作流时，请使用斜杠命令；设置 `disable-model-invocation: true` 可关闭自动发现入口。

## 复用其他工具的 Skills

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
skills = ["~/.codex/skills"]
```

`~/.codex/skills` 等非默认目录需要加入 `skills` 数组；Claude 和 Step 目录会自动发现，不必重复加入。加入后无需复制文件。使用前检查其中引用的命令、路径、模型能力和工具名称，避免沿用其他工具专属的行为假设。

子代理的定义和调用见[Agent 与 subagent](/docs/zh/step-code/customization/agents)。

## 存放位置

优先级从高到低如下：

| 范围 | 位置 |
| - | - |
| 项目 | `.stepcode/skills/`、项目范围内的 `.agents/skills/` 和 `.claude/skills/`，需要项目信任 |
| 用户 | `~/.stepcode/agent/skills/`、`~/.stepcode/skills/`、`~/.agents/skills/`、`~/.claude/skills/` |
| 包 | 资源包声明的 Skills 目录 |
| 启动参数 | `--skill <路径>`，可重复，设置 `--no-skills` 后仍加载 |

项目 `.agents/skills/` 和 `.claude/skills/` 的发现会向上查找到 Git 根。上述目录自动发现，不必重复加入 `skills` 数组；`~/.codex/skills` 等非默认目录仍需使用 `config.toml` 的 `skills` 数组显式指定。

资源包的安装与分发见[插件与 Packages](/docs/zh/step-code/customization/plugins)。

## 文件格式

### 目录结构

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
api-review/
├── SKILL.md
├── scripts/
│   └── check.sh
└── references/
    └── checklist.md
```

在 `SKILL.md` 中使用相对路径引用包内资料。`scripts/` 和 `references/` 是可选目录。

### Frontmatter 字段

| 字段 | 要求 | 说明 |
| - | - | - |
| `name` | 必填 | 最多 64 字符，使用小写字母、数字和连字符，跨工具复用时建议与父目录名一致 |
| `description` | 必填 | 最多 1,024 字符，说明用途和触发场景 |
| `license` | 可选 | 许可证 |
| `compatibility` | 可选 | 环境和依赖要求 |
| `metadata` | 可选 | 其他元数据 |
| `allowed-tools` | 可选 | 空格分隔的工具列表，实验性能力 |
| `disable-model-invocation` | 可选 | `true` 时不自动展示给模型，只保留手动调用入口 |

### 校验规则

大写、首尾连字符、连续连字符和超长名称会告警但仍加载；缺少 `description` 不加载；重名保留第一个并告警。未知 frontmatter 字段忽略。

为跨工具复用，建议按标准修正全部命名和长度问题。Skill 的工具声明不能替代 Step Code 的权限控制。


# 自定义主题
Source: https://platform.stepfun.com/docs/zh/step-code/customization/themes



Step Code 自带六套主题，也可以用 JSON 文件定义自己的配色：放入主题目录后即可在 `/theme` 中选择，修改当前主题会即时热重载。

## 内置主题

| 主题 | 用途 |
| - | - |
| `step-blue` | 默认蓝色主题 |
| `step-violet` | 深色终端紫色主题 |
| `step-violet-light` | 浅色终端紫色主题 |
| `dark`、`light` | 通用深色和浅色主题 |
| `sage` | 深色终端绿色主题 |

## 切换主题

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/theme
/theme sage
```

也可在配置文件中设置：

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
theme = "sage"
```

仅对一次启动生效：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step --use-theme light
```

`/theme` 打开选择器，自定义主题即时可用，无需重启；`/theme <名称>` 直接切换。编辑当前使用的主题文件会热重载。

工作行提示通过 `config.toml` 的 `statusTips` 设置，见[配置文件](/docs/zh/step-code/configuration/files)。

## 主题文件

| 范围 | 路径 |
| - | - |
| 用户 | `~/.stepcode/agent/themes/*.json` |
| 项目 | `.stepcode/themes/*.json`，需要项目信任 |
| 包 | 资源包中的主题目录 |
| 启动参数 | `--theme <路径>`，可重复 |

文件名即主题名，例如 `my-theme.json`。放入目录后，自定义主题与内置主题一起出现在 `/theme` 中。建议以完整主题为起点，保留全部颜色字段后再调整配色。

通过资源包分发主题的方式见[插件与 Packages](/docs/zh/step-code/customization/plugins)。

## 主题 JSON 格式

主题由 `name`、可复用颜色变量 `vars` 和颜色映射 `colors` 组成。以下示例仅展示部分字段，不能直接作为完整主题使用：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "name": "my-theme",
  "vars": {"primary": "#7aa2f7"},
  "colors": {
    "accent": "primary",
    "text": "#c0caf5",
    "mdTableHeader": "#9d7cd8",
    "syntaxKeyword": "#bb9af7"
  }
}
```

完整主题需定义全部 52 个颜色 token，覆盖核心 UI、背景与内容、Markdown、diff、语法高亮、thinking 边框和 bashMode。

| 颜色值 | 含义 |
| - | - |
| `"#ff0000"` | 六位十六进制颜色 |
| `39` | xterm 256 色索引 |
| `"primary"` | 引用 `vars` 中的变量 |
| `""` | 使用终端默认颜色 |

支持真彩色的终端使用 24-bit 颜色；其他终端可能回退为接近的 256 色。

暗色终端宜选明亮且饱和的颜色，亮色终端宜选较暗且低饱和的颜色；公共基色放入 `vars` 复用。

## 出错时的行为

非法色值会使整份主题加载失败并回退到内置 `dark`；热重载中瞬时出错则保持当前主题不变。请检查 JSON 语法、颜色值、变量引用和字段完整性。


# 交互与任务控制
Source: https://platform.stepfun.com/docs/zh/step-code/guides/interaction



在交互输入框中引用文件、发送消息或执行命令。Plan、目标和定时任务用于不同的任务控制场景。

开始任务前，通过 `/permissions` 检查当前模式，详见[权限与安全](/docs/zh/step-code/guides/permissions)。Enter 发送消息，Shift+Enter 换行，Esc 中断输出；输入 `/` 选择命令。完整操作见[键盘快捷键](/docs/zh/step-code/reference/keyboard-shortcuts)和[斜杠命令](/docs/zh/step-code/reference/slash-commands)。

## 文件引用

输入 `@` 搜索项目文件，使用 Tab 补全路径。Git 和非 Git 目录均可使用，也可以从命令行传入文件：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step @README.md "总结这个项目的用途和运行方式"
step @src/app.ts @src/app.test.ts "审查这两个文件的实现与测试是否一致"
```

被引用或被工具读取的文件内容可能进入模型上下文。引用前请检查密钥、个人信息和业务敏感数据。

## 粘贴图片

使用 Ctrl+V 粘贴剪贴板图片；Windows / WSL 使用 Alt+V。支持的终端也可以拖入图片路径。

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step -p @screenshot.png "这张截图里的报错怎么修？"
```

请先选择支持图片输入的模型。默认图片缩放会将过大的图片限制在 2,000 px 以内，以减少输入体积；可通过 `[images]` 配置调整。终端内联显示与向模型发送图片分别控制，关闭内联显示后仍可发送图片。

## Shell 命令直通

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
!npm run lint
!!git status --short
```

`!` 执行本地 Shell 命令并将输出加入模型上下文；`!!` 执行但不将输出发给模型。这两个前缀对单条命令生效，无需切换模式；通过输入框执行的命令不支持后台运行。输出以卡片形式显示，长输出自动收起，可使用 Ctrl+O 展开。

## 流式输出期间

* Enter 将新消息排队，当前助手轮次的工具调用结束后投递。
* Esc 中止当前轮次，并将队列消息恢复到输入框。
* Alt+↑ 取回排队消息；Windows / WSL 使用 Alt+Q。
* Ctrl+O 折叠或展开工具输出。

`steeringMode` 和 `followUpMode` 控制消息投递方式，可在设置中调整。follow-up 默认没有单独快捷键。

## 外部编辑器

Ctrl+G 打开外部编辑器编辑当前输入，动作名为 `app.editor.external`。选择顺序为 `externalEditor` 设置、`VISUAL`、`EDITOR`，最后使用 Windows 记事本或其他系统的 nano。

## Plan 模式

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/plan 梳理鉴权模块的依赖，先给出迁移计划，不修改业务代码
```

`/plan` 切换模式，`/plan <任务>` 直接开始规划；启动时也可以使用 `step --plan`。模型先勘察项目并写入计划文件。

Plan 模式下，文件编辑仅允许修改计划文件；Shell 命令仍按正常权限执行。批准计划后退出 Plan 模式并开始实施。

## 目标模式

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/goal 将测试迁移到 Vitest，保持现有用例通过，并提供改动摘要
```

目标模式持续驱动多轮执行，直到目标达成或手动停止，适合几小时量级的长任务。任务期间请保持 Step Code 进程运行。

| 命令 | 作用 |
| - | - |
| `/goal status` | 查看目标、状态和用量 |
| `/goal pause` | 暂停自动续跑，中断进行中的目标续跑轮次 |
| `/goal resume` | 恢复目标 |
| `/goal edit` | 修改目标描述 |
| `/goal clear` | 清除目标 |

状态行显示活跃计时，例如 `Goal: active · 12m 3s`，仅累计目标活跃时间。

## 管理定时任务

定时任务使用五字段 cron 表达式；持久任务保存在项目 `.stepcode/cron/tasks.json`，需要项目信任。持久任务仍需在 Step Code 进程运行期间调度。

多代理编排与授权见[Agent 与 subagent](/docs/zh/step-code/customization/agents)。

创建任务后，通过 `/cron` 核对时间与任务内容，并删除不再需要的任务。


# 从其他工具迁移
Source: https://platform.stepfun.com/docs/zh/step-code/guides/migration



Step Code 可以接入 Claude Code / Codex 的现有工作流：首次启动导入 MCP 配置，兼容 Claude Code 插件布局，现有 `CLAUDE.md` 直接生效。登录凭据需要重新配置。

## 迁移范围

首次启动检测到本机 Claude Code 或 Codex 的 MCP 配置时，会显示导入界面。确认后，支持的服务器配置写入 `~/.stepcode/config.toml` 的 `[mcp_servers]`。

* 来源包括 `~/.claude.json` 和 `~/.codex/config.toml`。
* 源文件只读，不移动、删除或覆盖原配置。
* 每个来源只询问一次；重复内容不重复导入。
* 同名但配置不同的服务器自动加 `-claude` / `-codex` 后缀。
* 环境变量引用保留变量名，不将对应环境变量值展开写入配置。
* 无法转换的字段会提示，导入后需检查结果。

目前支持 stdio 和 Streamable HTTP；SSE、WebSocket 传输及 IDE 注入的服务器不自动导入。Claude Code 项目级 `mcpServers` 需要手动配置。

## MCP 配置自动导入

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step mcp list
step mcp get <服务器名称>
```

在交互界面使用 `/mcp` 检查连接状态和工具数。命令路径、环境变量和远程服务权限仍需在 Step Code 的运行环境中有效。

原工具与 Step Code 可以并存；导入后，两份配置各自独立，不自动同步。

服务器管理和鉴权见[MCP](/docs/zh/step-code/customization/mcp)。

## 直接使用 Claude Code 插件

Step Code 可读取 `.claude-plugin/plugin.json`，以及插件中的 `.mcp.json`、`skills`、`commands` 和 `agents`。市场清单兼容 `.claude-plugin/marketplace.json`。

安装后，请检查需要使用的 Skills 和 MCP 功能。安装方式见[插件与 Packages](/docs/zh/step-code/customization/plugins)。

## 复用已有 Skills

用户目录增加 `~/.claude/skills`、`~/.stepcode/skills`；项目目录增加受信任扫描范围内的 `.claude/skills`。Claude 目录自动发现，不必重复加入 `skills` 数组；`~/.codex/skills` 等非默认目录仍需显式指定。

## 项目指引文件

现有 `CLAUDE.md` 可以继续使用。请检查其中的命令、工具名称和路径是否适用于 Step Code；通用创建方法、加载范围与优先级见[项目指引](/docs/zh/step-code/customization/project-instructions)。修改后运行 `/reload` 或重启。

## 不迁移的内容

| 内容 | 处理方式 |
| - | - |
| 模型供应商凭据 | Step 账号重新执行 `/login`；其他供应商按[登录与模型](/docs/zh/step-code/configuration/models)配置 |
| MCP OAuth 授权 | 执行 `step mcp login <名称>` |
| 源工具项目级 MCP 配置 | 按需手动添加 |

不要直接复制不明格式的凭据文件，也不要将包含密钥的配置提交到项目仓库。

安装与登录步骤见[快速开始](/docs/zh/step-code/quickstart)。

## 验证迁移结果

1. 完成一次模型对话，确认所选账号和模型可用。
2. 在 `/mcp` 中检查已导入服务器，并验证实际需要的工具调用。
3. 核对项目指引与资源路径，确认原工具的配置仍保留。


# 权限与安全
Source: https://platform.stepfun.com/docs/zh/step-code/guides/permissions



权限模式控制 Step Code 执行工具前的审批方式。处理项目时，还需分别确认项目资源、模型服务和外部工具的访问范围。

## 权限模式

从 v0.1.4 起，交互界面提供以下模式：

| 模式 | 行为 |
| - | - |
| Ask | 修改文件或运行命令前询问 |
| Approve for Me（默认） | 常规操作自动执行；检测到危险或无法完整分析的命令、以及关键决策仍需确认 |
| Full Access | 确认风险后可直接执行风险命令，不再逐次确认；为个别工具设置的禁止或确认规则仍然生效 |

两个自动档默认启用模型错误后的自动重试，重试次数有上限。

Ask 和 Approve for Me 对检测到的危险或无法完整分析的命令要求确认。Full Access 在风险确认后跳过这类逐次确认；为个别工具设置的禁止或确认规则仍然生效。规则检查不能覆盖任意脚本或所有危险行为，不能作为沙箱使用。

## 选择权限模式

> [!WARNING]
>
> Full Access 允许直接执行风险命令。开启前，请确认工作目录、可访问的凭据与文件范围，并备份重要数据。

未取得风险确认不会进入 Full Access；没有交互界面的运行不会仅凭配置获得 Full Access。权限模式不是系统沙箱。

1. 在交互输入框中运行 `/permissions`。
2. 根据任务选择模式。首次处理项目时，建议选择 Ask，检查工具参数后再批准操作。
3. 工作范围变化时，重新检查当前模式。也可以使用 Shift+Tab 或 `/permissions cycle` 切换。

Ask 模式的批准或拒绝针对对应的工具调用。拒绝后，该调用取消，模型收到拒绝原因；批量调用可能分别请求确认。

## 信任项目资源

项目信任决定是否加载项目配置、扩展和资源。使用 `/trust` 管理信任；命令行的 `--approve` 和 `--no-approve` 控制本次是否加载需要信任的项目资源。

信任项目前，请检查 `.stepcode/` 中的配置与资源。项目指引的加载范围见[项目指引](/docs/zh/step-code/customization/project-instructions)，配置覆盖关系见[配置文件](/docs/zh/step-code/configuration/files)。

## 限制工具范围

只需要分析项目时，选择 Ask，并在任务中说明文件范围。需要限制可用工具时，使用 `--tools` 或 `--exclude-tools`，工具名称应与当前注册的工具一致，见[内置工具](/docs/zh/step-code/reference/tools)。

`defaultTools` 管理原生内置工具集合；Step 工具、扩展与 MCP 工具还需按各自配置处理。MCP 可通过 `enabled_tools` 和 `disabled_tools` 筛选工具，见[MCP](/docs/zh/step-code/customization/mcp#工具命名与过滤)。

权限模式和工具筛选不提供操作系统级隔离。处理不可信代码或要求限制文件、网络访问的任务时，请使用容器、虚拟机或操作系统权限。

## 设置非交互任务的审批策略

`step -p` 没有交互审批界面。通过 `--approval-mode` 和 `--non-interactive-approval` 设置任务的审批策略，并明确可用工具。参数格式见 [`step` 命令](/docs/zh/step-code/reference/cli)。

`--non-interactive-denial` 控制遇到需人工确认的操作被拒绝后的行为：默认 `terminate` 终止任务；`continue` 将失败原因返回模型，由其尝试其他方式。继续执行仍受所选权限限制。

## 保护数据与凭据

* 模型请求会发送提示词、相关文件和工具结果。提供材料前，请确认服务有权接收这些数据。
* MCP 与插件可能执行本地程序或访问外部服务。只加载可信来源，并使用最小必要凭据。
* 日志和导出的会话可能包含代码、路径或错误详情，分享前请审查。
* 部署会上传构建产物，执行前请检查其中的密钥、私有配置和用户数据。

本地文件位置与清理方法见[数据路径](/docs/zh/step-code/configuration/data-paths)；发布前的检查见[发布 StepPage](/docs/zh/step-code/reference/steppage)。


# 会话与上下文
Source: https://platform.stepfun.com/docs/zh/step-code/guides/sessions



Step Code 自动保存会话，支持恢复、分支导航、派生和导出。上下文接近模型窗口时，可通过压缩保留重要信息并继续工作。

## 启动与恢复会话

| 命令 | 作用 |
| - | - |
| `step` | 在当前目录新建会话 |
| `step -c` | 继续最近一次会话 |
| `step -r` | 浏览历史会话并选择恢复 |
| `step --session <路径或 ID>` | 恢复指定会话，支持部分 ID |
| `step --fork <路径或 ID>` | 从已有会话派生新会话文件 |
| `step --name "鉴权改造"` | 设置会话名称 |

Ultracode 开关按会话保存，恢复同一会话会恢复此前状态，没有保存状态的新会话默认关闭。可通过 `/ultracode status` 查看。

## 在 TUI 中切换会话

| 命令 | 作用 |
| - | - |
| `/new`、`/clear` | 新建会话，清空当前对话上下文 |
| `/resume` | 打开会话选择器 |
| `/name` | 为当前会话命名 |
| `/session` | 查看文件路径、ID、消息数、token 用量和成本信息 |
| `/fork` | 派生独立会话 |

会话选择器中可输入搜索词，Ctrl+S 切换排序，Ctrl+N 筛选命名会话，Ctrl+R 重命名，Ctrl+D 删除。删除前请确认是否还需要保留记录。

输入操作和权限模式见[交互与任务控制](/docs/zh/step-code/guides/interaction)。

## 会话树与派生

| 命令 | 行为 | 适用场景 |
| - | - | - |
| `/tree` | 在同一会话文件中选择历史节点继续 | 回到较早的决策点尝试另一种方案 |
| `/fork` | 从选定的用户消息派生新会话 | 隔离不同对话方案 |
| `/clone` | 将当前分支完整复制到新会话 | 保存当前状态后继续 |

`/tree` 中使用方向键导航、Enter 选择节点、Ctrl+O 切换过滤器（默认、无工具、仅用户消息、仅带标签）、Shift+L 编辑标签。选择用户消息时，其文本可回填到输入框，修改后重发形成新分支。

切换分支时，可以为离开的分支生成摘要，供切换后的对话使用。相关选项在 `[branchSummary]` 中配置。

> [!NOTE]
>
> 会话分支只隔离对话记录，不会撤销磁盘文件修改，也不会创建 Git 分支。需要隔离代码实验时，请另行使用 Git 分支或 worktree。摘要和后续模型请求仍可能产生用量。

项目任务示例见[常见使用案例](/docs/zh/step-code/guides/use-cases)。

## 管理上下文

从 v0.1.4 起，自动压缩启用且未指定上下文模式时，默认使用 CLM（Context Language Models），由模型选择性精简较早的上下文，不覆盖原始会话日志。精简失败或效果不足时回退到原有摘要压缩；模型用量计入会话统计。

| 命令 | 说明 |
| - | - |
| `/clm [status\|on\|off\|diff\|reset]` | 查看状态、切换当前会话开关、查看修改或清除整理结果 |
| `/clm-compact [要求]` | 主动请求模型整理当前上下文 |
| `/compact [保留要求]` | 使用原有摘要压缩 |

`/clm reset` 不撤销已经发生的原有摘要压缩。整理产生额外模型调用，用量计入会话统计。

## 上下文压缩

摘要压缩保留近期消息，并将较早内容整理为摘要。手动压缩时，可指定需要保留的信息：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/compact 保留鉴权改造的目标、接口约定、已改文件、验证结果和未解决的问题
```

自动摘要压缩的开关、预留窗口和近期消息量见[配置文件](/docs/zh/step-code/configuration/files#分节配置)。重要约定和验收结果也应记录在项目文件中。

## 导出与分享

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/export session.html
/export session.jsonl
```

也可以在命令行导出：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step --export /path/to/session.jsonl session.html
```

`/export [file]` 默认导出 HTML；使用 `.jsonl` 扩展名导出 JSONL。导出可能包含代码、命令输出与路径，分享前请检查。

## 导入会话

在交互界面中导入已保存的 JSONL 会话：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/import session.jsonl
```

将文件名替换为实际会话文件。HTML 导出用于阅读，恢复会话使用 JSONL 文件。

## 会话存储

会话按工作目录分组保存，使用 `/session` 查看当前文件路径。`--session-dir` 指定目录，`--no-session` 关闭本次会话保存。完整目录与清理方法见[数据路径](/docs/zh/step-code/configuration/data-paths#会话数据)。


# 常见使用案例
Source: https://platform.stepfun.com/docs/zh/step-code/guides/use-cases



## 理解陌生项目

先进行只读勘察，再决定是否实施修改。需要限制工具操作时，先用 `/permissions` 选择 Ask 并核对审批请求。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
刚接手这个仓库：先看入口和构建脚本，按“启动流程、核心模块、外部依赖”给我一份新人向导，先不要改任何文件。
```

确认结论后，可使用 `/init` 将项目约定整理到 `AGENTS.md`。

复用其他工具的项目指引见[从其他工具迁移](/docs/zh/step-code/guides/migration)。

## 实现新功能

将功能要求和验收条件一起提供；涉及多个模块时先制定计划。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
给订单列表加一个“按物流状态筛选”的下拉框。要求：复用现有的 FilterBar 组件、URL query 同步、移动端不破版。先列出要动的文件和顺序，我确认后再实现。
```

## 修复 Bug

提供现象、复现条件、预期结果和相关文件。可以附带截图，或用 `!` 将诊断命令的输出加入上下文。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
购物车金额偶尔少一分钱。金额计算在 src/cart/total.ts。先列出所有取整路径，构造可复现用例，确认根因后提交最小修改并补回归测试。
```

## 写测试与重构

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
为 src/utils/date.ts 的导出函数补充空值、月末和跨时区测试。先保证行为不变，再把重复的格式化逻辑抽为私有 helper，最后运行测试并总结改动。
```

尝试不同方案时可以使用 `/fork` 隔离会话，但代码修改仍在同一工作目录；需要文件隔离时另建 Git worktree。

## 长任务托管

几小时量级的任务可通过 `/goal` 托管，设定目标后持续推进。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/goal 把本仓库所有测试迁移到 vitest 并保持全绿。分模块推进，每完成一个模块跑一次全量测试再进入下一个。
```

使用 `/goal status` 查看进展，`/goal pause` 暂停，`/goal resume` 恢复。任务期间保持进程和网络连接可用，详细行为见[目标模式](/docs/zh/step-code/guides/interaction#目标模式)。

定期任务可以让模型创建 cron 调度，并通过 `/cron` 管理，例如定期检查依赖漏洞并汇总结果。定时任务需在 Step Code 进程运行期间调度。

## 并行多代理

批量同构任务（全量审计、多方案对比）可用 workflow 编排多个子代理并行。消息里写 `ultraloop` 或 `ultracode` 明确授权，不会因为任务大就自动开启：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
ultraloop 把 docs/ 下所有英文页翻成中文：每页一个子代理翻译，另一个子代理校对术语一致性，最后合并输出改动清单。
```

需要并行修改时，为各子任务划分不同文件，或明确要求独立 worktree。多代理会独立消耗 token。详见 [Agent 与 subagent](/docs/zh/step-code/customization/agents)。

## 发布静态网站

先用 `/mcp` 检查 StepPage 状态。已有 Step 登录或 `STEPFUN_API_KEY` 均可提供凭据；插件缺失或此前主动卸载时，使用 `/plugin install steppage` 安装并重启。准备好构建产物后，明确指定目录和是否上线：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
检查 ./dist 中是否有密钥或私有配置。向我确认发布范围后，再生成预览链接，暂不上线已有站点。
```

安装、部署、版本管理与发布前检查见[发布 StepPage](/docs/zh/step-code/reference/steppage)。

## 生成与维护文档

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
对比 src/ 实现与 docs/ 说明，更新过时段落。新增模块补充用途、入口和示例，不确定的信息列出来，不要编造。最后检查内部链接和代码示例。
```

重要讨论可以通过 `/export` 导出。


# 升级
Source: https://platform.stepfun.com/docs/zh/step-code/installation



首次安装见[快速开始](/docs/zh/step-code/quickstart)。

## 环境要求

* macOS 或 Linux 使用 Bash 命令。
* Windows PowerShell 支持处于 beta 阶段，Windows 用户也可以在 WSL 中按 Linux 方式操作。
* 建议使用 Kitty、Ghostty、iTerm2 或 Windows Terminal。图片显示和部分组合键取决于终端支持。
* 安装和升级时需要访问发行服务，使用模型时需要访问对应的模型服务。

## 指定安装版本和目录

通常使用 `step update <版本号>` 更新到指定发行版本。需要自定义程序目录或使用安装器时，在 macOS 或 Linux 中先下载安装器，再指定安装参数：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -fsSL https://static-openapi.stepfun.com/stepcode/install.sh -o install-stepcode.sh
bash install-stepcode.sh --version latest --install-dir "$HOME/.local/stepcode/bin"
```

`latest` 安装最新版本；固定版本时，将其替换为实际发行版本。`--install-dir` 指定程序目录。也可使用以下环境变量：

| 变量 | 用途 |
| - | - |
| `STEP_RELEASE_BASE_URL` | 发行源 |
| `STEP_INSTALL_DIR` | 程序安装目录 |
| `STEP_CODING_AGENT_DIR` | Agent 资源目录 |

配置、凭据与会话的目录规则见[数据路径](/docs/zh/step-code/configuration/data-paths)。

## 升级 Step Code

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step update
```

`step upgrade` 是别名。安装指定发行版本的命令格式为 `step update <版本号>`。升级完成后，运行 `step --version` 核对版本；各版本的变化见[版本记录](/docs/zh/step-code/release-notes)。

## 卸载 Step Code

1. 退出 Step Code，备份需要保留的配置和会话。
2. 删除安装目录中的 `step` 可执行文件；Windows 对应 `step.exe`。
3. 从 Shell 配置或 Windows PATH 中移除安装目录。zsh、Bash 和 POSIX 登录配置中的安装器 PATH 块带有标记；fish 使用 `fish_add_path` 管理路径。

卸载程序后，配置、凭据和会话仍会保留。需要清理时，按[数据清理说明](/docs/zh/step-code/configuration/data-paths#清理数据)分别处理；不要删除与其他工具共用的目录。


# Step Code 概述
Source: https://platform.stepfun.com/docs/zh/step-code/overview



Step Code 是阶跃星辰推出的终端编程智能体（CLI），用于阅读和修改代码、执行命令，以及处理软件开发任务。

## 开始使用

* [快速开始](/docs/zh/step-code/quickstart)：安装、登录并完成首次文件分析。
* [升级](/docs/zh/step-code/installation)：更新程序、选择版本或卸载。
* [登录与模型](/docs/zh/step-code/configuration/models)：配置账号、计费通道与模型。

## 使用与项目指引

* [常见使用案例](/docs/zh/step-code/guides/use-cases)：理解项目、实现功能、修复问题、编写测试与维护文档。
* [交互与任务控制](/docs/zh/step-code/guides/interaction)：规划任务、管理持续目标与定时任务。
* [Agent 与 subagent](/docs/zh/step-code/customization/agents)：委派任务和编排多个代理。
* [发布 StepPage](/docs/zh/step-code/reference/steppage)：发布构建产物并管理版本。
* [项目指引](/docs/zh/step-code/customization/project-instructions)：保存团队约定与检查要求。
* [权限与安全](/docs/zh/step-code/guides/permissions)：选择审批模式并检查访问范围。

## 参考与支持

* [CLI 命令参考](/docs/zh/step-code/reference/cli)

* [常见问题与排障](/docs/zh/step-code/reference/faq)

* [版本记录](/docs/zh/step-code/release-notes)：查看各版本的变化。


# 快速开始
Source: https://platform.stepfun.com/docs/zh/step-code/quickstart



Step Code 可在项目目录中读取文件并处理开发任务。产品能力与适用场景见 [Step Code 概述](/docs/zh/step-code/overview)。

## 准备条件

* 可用的 Step Plan 账号或阶跃 API Key，以及访问模型服务的网络连接。
* 一个可供分析、包含 `README.md` 的项目目录；请确认该文件可发送给所选模型服务。

## 安装

> [!NOTE]
>
> 安装命令会执行远程脚本。请先确认来源可信；指定安装版本或卸载时，见[升级](/docs/zh/step-code/installation)。

**macOS / Linux**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -fsSL https://static-openapi.stepfun.com/stepcode/install.sh | bash
```

**Windows PowerShell**

```powershell theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
irm https://static-openapi.stepfun.com/stepcode/install.ps1 | iex
```

PowerShell 支持处于 beta 阶段，也可以在 WSL 中使用 Linux 安装命令。

安装完成后重新打开终端，运行 `step --version`，确认输出版本号。

StepPage 自动准备需要外部 Node.js 20 或更新版本；这不是 Step Code 独立程序本身的依赖。准备失败可运行 `step mcp prepare` 后重启检查。原生 Windows 暂不自动安装，可使用 WSL 或自行准备。该命令是内置资源准备入口，不是所有第三方 MCP 的通用修复命令。

## 首次启动

进入准备好的项目目录，将示例路径替换为实际路径：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
cd /path/to/project
step
```

按首次启动提示登录并选择主题。检测到其他工具的 MCP 配置时会提示导入；已有配置的复用方式见[从其他工具迁移](/docs/zh/step-code/guides/migration)。

## 登录

1. 在交互输入框中运行 `/login`。
2. 按账号所在地区和计费方式选择阶跃登录入口。国内 Step Plan 订阅选择 Step Plan，海外订阅选择 Step Plan Oversea，并在浏览器完成授权；使用 API Key 时，选择与该 Key 对应的阶跃账号入口。
3. 运行 `/model`，选择账号可用的模型。

在 SSH、服务器或容器终端中，可运行 `step login --no-browser` 获取授权链接，在本机或其他设备的浏览器中完成登录。该命令仍要求交互终端，不依赖本地回调端口。

订阅与按量付费使用不同通道。完整登录说明、端点和其他供应商的接入方式见[登录与模型](/docs/zh/step-code/configuration/models)。

## 确认权限

未配置权限的新交互会话默认使用 Approve for Me：常规操作自动执行，检测到危险或无法完整分析的命令时仍需确认。需要在修改文件和运行命令前逐项确认时，运行 `/permissions` 并选择 Ask。权限模式不是系统沙箱，只在可信目录中运行。各模式行为与项目访问边界见[权限与安全](/docs/zh/step-code/guides/permissions)。

## 第一个对话

在交互输入框中引用 `README.md` 并发送任务：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
@README.md 根据这个文件，概括项目用途、启动方式和测试命令。未写明的信息请标注“未说明”。不修改文件，不运行命令。
```

## 检查结果

确认回答以 README 的实际内容为依据，未补写文件中不存在的启动方式或测试命令，并检查工具记录中是否有超出任务范围的操作。在 Git 项目中，可通过 `git diff` 检查文件改动。

使用 `/quit` 退出。需要继续同一任务时，按[会话与上下文](/docs/zh/step-code/guides/sessions)恢复会话。

## 下一步

* [项目指引](/docs/zh/step-code/customization/project-instructions)：配置团队约定与检查要求。
* [交互与任务控制](/docs/zh/step-code/guides/interaction)：引用图片、规划任务、管理目标与定时任务。
* [斜杠命令](/docs/zh/step-code/reference/slash-commands)和[键盘快捷键](/docs/zh/step-code/reference/keyboard-shortcuts)：查询完整操作列表。
* [数据路径](/docs/zh/step-code/configuration/data-paths)：查找配置、凭据和会话，备份或清理本地数据。
* [升级](/docs/zh/step-code/installation)：更新程序、指定版本或卸载；版本变化见[版本记录](/docs/zh/step-code/release-notes)。


# step 命令
Source: https://platform.stepfun.com/docs/zh/step-code/reference/cli



在终端中使用 `step` 启动会话，或通过子命令管理安装、资源包和 MCP。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step [选项] [--] [@文件...] [任务描述...]
```

查看当前版本提供的参数：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step --help
step --version
```

## 模型参数

| 参数 | 说明 |
| - | - |
| `--provider <名称>` | 平台名称，如 `step`、`anthropic`、`openai` |
| `--model <模型>` | 模型 ID 或匹配模式，支持 `provider/id` 和思考级别后缀 |
| `--api-key <密钥>` | 覆盖其他凭据来源；注意 Shell 历史和进程参数暴露风险 |
| `--thinking <级别>` | `off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`，需模型支持 |
| `--models <列表>` | Ctrl+P 循环模型列表，逗号分隔 |
| `--list-models [搜索词]` | 列出可用模型 |

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step --provider step --model step-3.7-flash
step --list-models flash
```

模型切换的完整快捷键见[键盘快捷键](/docs/zh/step-code/reference/keyboard-shortcuts)。

## 会话参数

| 参数 | 说明 |
| - | - |
| `-c`、`--continue` | 继续最近一次会话 |
| `-r`、`--resume` | 浏览并选择历史会话，可附带路径或 ID |
| `--session <路径或 ID>` | 指定会话，支持部分 ID |
| `--fork <路径或 ID>` | 派生指定会话 |
| `--session-dir <目录>` | 自定义会话目录 |
| `--no-session` | 不保存本次会话 |
| `--name <名称>`、`-n <名称>` | 设置会话名称 |
| `-p`、`--print` | 执行一次任务并退出，支持 stdin 和 `@文件` |

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step --name "接口审查" @README.md "梳理接口约定"
step -p @screenshot.png "解释这张截图中的错误"
step --no-session -p "解释语义化版本号"
```

交互界面的会话管理命令见[斜杠命令](/docs/zh/step-code/reference/slash-commands)。

## 工具参数

| 参数 | 说明 |
| - | - |
| `--tools <列表>`、`-t <列表>` | 工具白名单，逗号分隔；作用于内置和扩展工具 |
| `--exclude-tools <列表>`、`-xt <列表>` | 排除工具 |
| `--no-builtin-tools`、`-nbt` | 关闭内置工具，保留扩展工具 |
| `--no-tools`、`-nt` | 关闭所有工具 |

例如，传入已有的 README，且不启用工具：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step --no-tools -p @README.md "概括这个 README 中的项目用途"
```

权限与危险操作说明见[权限与安全](/docs/zh/step-code/guides/permissions)。

## 资源参数

| 参数 | 说明 |
| - | - |
| `-e <来源>`、`--extension <来源>` | 临时加载扩展，可重复 |
| `--skill <路径>` | 显式加载 Skill，可重复 |
| `--prompt-template <路径>` | 加载 prompt 模板，可重复 |
| `--theme <路径>` | 加载主题资源，可重复 |
| `--no-extensions`、`--no-skills`、`--no-prompt-templates`、`--no-themes` | 关闭对应资源的自动发现 |
| `--no-context-files`、`-nc` | 不自动加载项目指引 |

显式指定的资源可与关闭自动发现的选项配合使用；它们仍需来自可信来源。

持久资源配置见[配置文件](/docs/zh/step-code/configuration/files)。

## 自动化与上下文

| 参数 | 说明 |
| - | - |
| `--mode <模式>` | 选择输出或集成模式：`text`、`json` 或 `rpc`；`rpc` 用于集成，不等同普通文本输出 |
| `--context-projection <模式>` | 设置本次上下文模式：`clm-v1`（默认）、`lightweight-v1` 或 `off` |
| `--completion-check git-committed` | 仅 print/JSON 模式；检查提交、工作区状态和最终答复 |
| `--completion-check-attempts <1..3>` | 最多追加轮次，默认 2；需同时启用完成检查 |
| `--completion-review` | 请求自查；依赖完成检查，与其共用追加轮次 |
| `--non-interactive-approval <模式>` | 无人工审批界面时的策略：`allow` 或 `deny` |
| `--non-interactive-denial <模式>` | 被拦截后的处理：`terminate`（默认）终止，或 `continue` 将原因返回模型继续处理 |
| `--tool-override <工具=模式>` | 单个工具的策略，可重复；模式为 `allow`、`confirm` 或 `deny` |

完成检查不等于测试通过或代码质量保证；`continue` 不绕过权限。

## 其他参数

| 参数 | 说明 |
| - | - |
| `--plan` | 启动即进入 Plan 模式 |
| `--tui-mode <模式>` | `regular` 或实验性 `fullscreen` |
| `--approval-mode <模式>` | 工具审批模式，可选 `confirm` 或 `auto`，适用于交互和非交互运行 |
| `--version` | 查看版本 |
| `--use-theme <名称>` | 本次启动使用的主题 |
| `--export <会话文件> [输出文件]` | 导出会话为 HTML |
| `--` | 结束选项解析，其后作为消息或文件引用 |

## 子命令

| 命令 | 说明 |
| - | - |
| `step login --no-browser` | 在 SSH、服务器或容器终端中获取授权链接，在本机或其他设备的浏览器中完成登录；该命令仍要求交互终端，不依赖本地回调端口 |
| `step update` | 更新到最新稳定版，别名 `step upgrade` |
| `step update <版本号>` | 安装实际发行的指定版本 |
| `step install <来源>` | 安装资源包 |
| `step remove <来源>` | 移除资源包 |
| `step list` | 列出资源包 |
| `step config` | 可视化管理资源，Tab 切换全局与项目范围 |
| `step mcp` | MCP 的 `list`、`get`、`add`、`remove`、`login`、`logout` |
| `step mcp prepare` | 准备或重试内置可选资源（如 StepPage），准备后重启检查；不用于修复任意第三方 MCP 服务 |
| `step login`、`step logout` | Step 账号登录或退出 |
| `step login status` | 查看 Step 登录方式和状态 |

升级和卸载步骤见[升级](/docs/zh/step-code/installation)。


# 常见问题
Source: https://platform.stepfun.com/docs/zh/step-code/reference/faq



## 安装与升级

### 安装后找不到 step？

重新打开终端，使 PATH 配置生效。默认安装目录为 `~/.stepcode/bin`；Windows 为 `%USERPROFILE%\.stepcode\bin`。检查可执行文件是否存在，以及是否配置了自定义安装路径。

安装脚本写入的 PATH 块带标记，可检查对应 Shell 登录配置。

### 如何升级？

运行 `step update`。选择版本和卸载步骤见[升级](/docs/zh/step-code/installation)。

## 登录与模型

### /login 中应该选择哪个平台？

国内阶跃订阅选择 Step Plan，海外订阅选择 Step Plan Oversea。按量付费使用对应地区的开放平台 API Key。其他供应商按[登录与模型](/docs/zh/step-code/configuration/models)使用环境变量或自定义平台配置。

### 远程终端如何登录？

在 SSH、服务器或容器终端中，可运行 `step login --no-browser` 获取授权链接，在本机或其他设备的浏览器中完成登录。该命令仍要求交互终端，不依赖本地回调端口。

### 更新环境变量后仍在使用旧密钥？

保存的账号或自定义模型配置可能影响所用凭据。请同时检查 `auth.json`、`models.json`、启动参数和进程环境，并从设置了变量的终端重启。完整说明见[登录与模型](/docs/zh/step-code/configuration/models)。

### 自定义模型没有出现在 /model？

检查 `models.json` 的 JSON 格式、模型 ID 和平台配置。本地无鉴权服务也需要非空 `apiKey` 占位值。保存后重新打开 `/model`；涉及登录和环境变量时还需重启。

### 切换模型后用量增加？

切换模型可能无法复用之前的提示词缓存，价格和分词方式也可能不同。查看当前模型、会话用量和账户账单，不要仅根据对话长度判断成本。

## 交互

### Shift+Enter 发送了消息，而没有换行？

改用 Ctrl+J 或 Alt+Enter。部分终端会拦截组合键，需要调整终端按键转发或 Step Code 的键位配置。

### 为什么工具不弹审批？

未配置权限的新交互会话默认使用 Approve for Me，普通调用不逐项审批。需要修改文件和运行命令前确认，可选择 Ask。危险命令规则命中的操作会另行处理，但规则不是覆盖所有风险的安全沙箱。各模式行为见[权限与安全](/docs/zh/step-code/guides/permissions#权限模式)。

### 升级后为什么重新出现审批？

已保存的旧权限模式会重置为 Ask。运行 `/permissions` 选择需要的模式。

### 粘贴图片失败？

使用 Ctrl+V，Windows / WSL 使用 Alt+V。确认剪贴板中确实是图片、终端快捷键没有冲突，并选择支持图片的模型。可改用 `step @screenshot.png` 引用文件。

## MCP 与插件

### MCP 显示 failed？

运行 `step mcp get <名称>` 检查声明。stdio 服务重点检查命令路径、参数、依赖和环境变量；HTTP 服务检查地址、鉴权变量和授权状态。不要在反馈中粘贴真实 token。

### 安装插件后 MCP 没有生效？

安装或卸载插件后需重启 Step Code，再通过 `/mcp` 检查。确认程序已安装，项目已信任，服务器没有被设置为 `enabled = false`。

### StepPage 未就绪怎么办？

StepPage 自动准备需要外部 Node.js 20 或更新版本；这不是 Step Code 独立程序本身的依赖。准备失败可运行 `step mcp prepare` 后重启检查。原生 Windows 暂不自动安装，可使用 WSL 或自行准备。该命令是内置资源准备入口，不是所有第三方 MCP 的通用修复命令。

## 数据与隐私

### 数据保存在哪里？

默认全局数据在 `~/.stepcode/`，项目资源在项目 `.stepcode/`。自定义路径和清理方式见[数据路径](/docs/zh/step-code/configuration/data-paths)。

### 本地 Agent 是否意味着代码不会发送出去？

不是。模型调用会发送任务相关内容，工具和插件也可能访问外部服务。只读工具不修改文件，但读取内容仍可能进入模型上下文。处理敏感项目时应先确认供应商、数据处理要求和可访问范围。

### 如何关闭遥测？

在全局 `config.toml` 设置：

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[telemetry]
enabled = false
```

遥测与模型请求、MCP 和主动反馈分别管理。具体配置见[配置文件](/docs/zh/step-code/configuration/files#遥测)。

## 反馈

使用 `/feedback` 提交问题。建议附上 `step --version` 的结果、操作系统、终端类型、复现步骤，以及脱敏后的错误信息。分享会话导出或日志前检查代码、路径和凭据。


# 键盘快捷键
Source: https://platform.stepfun.com/docs/zh/step-code/reference/keyboard-shortcuts



使用 `/hotkeys` 查看当前快捷键。部分组合键受操作系统和终端设置影响，遇到冲突时可使用替代键或修改键位。

## 输入与编辑

| 快捷键 | 作用 |
| - | - |
| Enter | 发送输入 |
| Shift+Enter、Alt+Enter、Ctrl+J | 换行 |
| ↑ / ↓（空输入框） | 浏览输入历史 |
| Home / Ctrl+A；End / Ctrl+E | 移动到行首或行尾 |
| Alt+← / →、Ctrl+← / → | 按词移动 |
| Ctrl+] / Ctrl+Alt+] | 向前或向后跳到指定字符 |
| Backspace；Delete / Ctrl+D | 向后或向前删除字符 |
| Ctrl+W / Alt+Backspace；Alt+D | 向后或向前删除词 |
| Ctrl+U；Ctrl+K | 删除到行首或行尾 |
| Ctrl+Y、Alt+Y | 恢复删除内容，或切换删除记录 |
| Ctrl+- | 撤销；Windows 使用 Ctrl+Z，WSL 使用 Alt+Z |

输入框和消息队列的使用方式见[交互与任务控制](/docs/zh/step-code/guides/interaction)。

## 全局与应用

| 快捷键 | 作用 |
| - | - |
| Esc | 中断输出或取消当前操作 |
| Ctrl+C | 清空输入；输入为空时退出 |
| Ctrl+D | 空输入框时退出 |
| Ctrl+Z | 将进程挂起到后台，原生 Windows 不适用 |
| Ctrl+G | 打开外部编辑器 |
| Ctrl+V | 粘贴图片；Windows / WSL 使用 Alt+V |

## 模型与输出

| 快捷键 | 作用 |
| - | - |
| Ctrl+L | 重绘屏幕 |
| Ctrl+P | 切换到下一个已选模型 |
| Shift+Ctrl+P | 切换到上一个模型；Windows / WSL 使用 Alt+P |
| Shift+Tab | 循环权限模式 |
| Ctrl+T | 折叠或展开思考块 |
| Ctrl+O | 折叠或展开工具输出 |
| Ctrl+X | 复制响应、所选消息或全屏选区，取决于当前界面 |
| Alt+↑ | 取回排队消息；Windows / WSL 使用 Alt+Q |

对应的交互命令见[斜杠命令](/docs/zh/step-code/reference/slash-commands)。

## 会话记录滚动与搜索（fullscreen 模式）

| 快捷键 | 作用 |
| - | - |
| Ctrl+End | 返回底部并跟随新输出 |
| PageUp / PageDown | 按页滚动 |
| Ctrl+Shift+F | 搜索会话记录；Windows / WSL 使用 Ctrl+F |
| Enter / Ctrl+G | 下一个搜索结果 |
| Shift+Enter | 上一个搜索结果 |
| Ctrl+Shift+↑ / ↓ | 跳到上一条或下一条标记消息 |

fullscreen 是实验性模式，可通过 `step --tui-mode fullscreen` 启动。

## /tree 内

| 快捷键 | 作用 |
| - | - |
| ↑ / ↓ | 浏览节点 |
| Enter | 选择节点 |
| Ctrl+← / →、Alt+← / → | 折叠或展开跳段 |
| Shift+L | 编辑标签 |
| Ctrl+O | 切换过滤器 |

## 选择器通用

方向键和 PageUp / PageDown 用于浏览，Enter 确认，Esc 取消。

`/resume` 选择器中，Ctrl+S 切换排序、Ctrl+N 筛选命名会话、Ctrl+R 重命名、Ctrl+D 删除。模型选择器中的 Ctrl+S 用于保存默认值；思考级别选择器按 Enter 即应用并保存默认值。

## 自定义

键位文件位于 `~/.stepcode/agent/keybindings.json`，动作名如 `tui.input.newLine`、`app.model.select`，修改后运行 `/reload`。例如，指定换行键：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "tui.input.newLine": ["shift+enter", "ctrl+j"]
}
```

只覆盖需要调整的动作，避免同一上下文中绑定重复组合键。设置无效时，先检查终端是否拦截按键，再检查动作名称和 JSON 格式。

其他界面设置见[配置文件](/docs/zh/step-code/configuration/files)。


# 斜杠命令
Source: https://platform.stepfun.com/docs/zh/step-code/reference/slash-commands



在 Step Code 交互输入框中输入 `/` 查看命令补全。以下命令在交互界面中执行，不是终端 Shell 命令。

## 会话

| 命令 | 作用 |
| - | - |
| `/new`、`/clear` | 新建会话 |
| `/resume` | 浏览并恢复历史会话 |
| `/name` | 设置会话名称 |
| `/session` | 查看会话路径、ID 和用量 |
| `/tree` | 浏览会话树 |
| `/fork` | 派生会话 |
| `/clone` | 复制当前分支到新会话 |
| `/export [文件]` | 导出 HTML 或 JSONL |
| `/import <文件>` | 导入 JSONL |
| `/copy` | 复制响应内容 |

会话分支与文件修改的关系见[会话与上下文](/docs/zh/step-code/guides/sessions)。

命令行启动与恢复会话的参数见[`step` 命令](/docs/zh/step-code/reference/cli)。

## 模型与思考

| 命令 | 作用 |
| - | - |
| `/model` | 选择模型，Ctrl+S 保存默认值 |
| `/effort` | 选择思考级别，按 Enter 应用并保存默认值；`/effort <级别>` 同样保存 |
| `/scoped-models` | 管理 Ctrl+P 循环的模型集合 |
| `/llama` | 管理 llama.cpp 路由服务器模型 |

## 上下文与配置

| 命令 | 作用 |
| - | - |
| `/clm [status\|on\|off\|diff\|reset]` | 查看状态、切换当前会话开关、查看修改或清除整理结果 |
| `/clm-compact [要求]` | 主动请求模型整理上下文 |
| `/compact [保留要求]` | 使用原有摘要压缩 |
| `/settings` | 打开设置菜单 |
| `/reload` | 重载配置和资源 |
| `/theme [名称]` | 选择主题 |
| `/trust` | 管理项目信任 |

`/clm reset` 不撤销已经发生的原有摘要压缩。整理产生额外模型调用，用量计入会话统计。

配置字段的完整说明见[配置文件](/docs/zh/step-code/configuration/files)。

## 权限与模式

| 命令 | 作用 |
| - | - |
| `/permissions` | 选择工具审批模式 |
| `/permissions cycle` | 循环切换权限模式 |
| `/plan [任务]` | 切换 Plan 模式，或开始规划指定任务 |

## 长任务与多代理

| 命令 | 作用 |
| - | - |
| `/ultracode [on\|off\|status\|help]` | 管理多代理协作；`/ultraloop` 为别名 |
| `/workflows` | 查看工作流与运行记录 |
| `/goal <目标>` | 设置目标 |
| `/goal status` | 查看目标和状态 |
| `/goal pause`、`/goal resume` | 暂停或恢复目标 |
| `/goal edit <目标>` | 修改目标 |
| `/goal clear` | 清除目标 |
| `/cron` | 定时任务列表与删除 |
| `/todos` | 查看任务清单 |

目标模式用于持续推进长任务，多代理编排和授权方式见 [Agent 与 subagent](/docs/zh/step-code/customization/agents#workflow-与-ultraloop)。

Ultracode 开关按会话保存，恢复同一会话会恢复状态，没有保存状态的新会话默认关闭。

## 扩展与项目指引

| 命令 | 作用 |
| - | - |
| `/plugin` | 插件和市场管理 |
| `/mcp` | 查看 MCP 服务状态 |
| `/init` | 生成项目指引 `AGENTS.md` |
| `/skill:<名称> [参数]` | 调用已加载的 Skill |

插件安装或卸载涉及 MCP 时，重启后再检查加载结果。

## 账号与其他

| 命令 | 作用 |
| - | - |
| `/login`、`/logout` | 平台登录或退出 |
| `/status` | 查看会话与模型状态 |
| `/hotkeys` | 查看快捷键 |
| `/feedback` | 提交反馈 |
| `/quit`、`/exit` | 退出 |

提交反馈前检查正文和附件是否含敏感数据。

完整快捷键列表见[键盘快捷键](/docs/zh/step-code/reference/keyboard-shortcuts)。


# 发布 StepPage
Source: https://platform.stepfun.com/docs/zh/step-code/reference/steppage



通过 `steppage` 插件，将本地静态产物发布到 StepFun Page，获取预览链接并管理版本。

`steppage` 通过 MCP 服务器 `steppage-mcp` 提供部署、站点查询、版本管理、上线和回滚等工具。它接收本地目录或 ZIP，用于静态网页托管，不提供应用后端或数据库运行环境。

## 安装条件

| 项目 | 要求 |
| - | - |
| 凭据 | `STEPFUN_API_KEY` 环境变量；已登录 Step 账号时可使用已保存的登录凭据 |
| MCP 程序 | `steppage-mcp`；缺少时经官方安装器自动补齐 |
| 生效方式 | 安装后重启 Step Code，并通过 `/mcp` 检查状态 |
| Windows | 暂不自动安装 MCP 程序，可使用 WSL 或手动配置 |

StepPage 自动准备需要外部 Node.js 20 或更新版本；这不是 Step Code 独立程序本身的依赖。准备失败可运行 `step mcp prepare` 后重启检查。原生 Windows 暂不自动安装，可使用 WSL 或自行准备。该命令是内置资源准备入口，不是所有第三方 MCP 的通用修复命令。

## 安装插件

从 v0.1.1 起，首次启动会自动预装 StepPage；主动卸载后不会重复安装。先通过 `/mcp` 检查 StepPage 状态，仅在插件缺失或此前主动卸载时，在 Step Code 中运行：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/plugin install steppage
```

官方安装器地址为 `https://dl.stepfun.com/steppage-mcp/p/install.sh`，可通过 `STEPCODE_STEPPAGE_INSTALLER_URL` 覆盖。需要手动执行时：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -fsSL https://dl.stepfun.com/steppage-mcp/p/install.sh | sh
```

Bash / Zsh 环境变量方式示例：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export STEPFUN_API_KEY="YOUR_STEP_API_KEY"
step
```

将占位符替换为您的密钥，修改环境变量后重新启动 Step Code。独立 CLI 与 MCP 的使用方式见[静态托管 CLI 与 MCP](/docs/zh/guides/developer/page-hosting-cli-mcp)。

插件的安装与管理见[插件与 Packages](/docs/zh/step-code/customization/plugins)。

MCP 连接与鉴权见[MCP](/docs/zh/step-code/customization/mcp)。

## 部署

> [!WARNING]
>
> 部署会将产物上传到外部托管服务。公开链接可能被他人访问和转发，发布前应检查内容与访问权限。

1. 将前端项目构建为静态产物，如 `dist/`。
2. 检查入口页面、资源路径和产物目录，排除密钥、私有配置和用户数据。
3. 向 Step Code 明确指定要发布的目录及是否上线。
4. 检查工具返回的预览链接、版本和管理入口，并在浏览器中检查页面和静态资源。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
把 ./dist 发布成网页，生成预览链接。
```

模型通过 `page_deploy` 将指定目录或 ZIP 发布为站点版本，返回结果自动附管理入口链接。更新已有站点时，请提供明确的站点标识。

其他项目任务示例见[常见使用案例](/docs/zh/step-code/guides/use-cases)。

## 上线版本

1. 列出站点与版本，核对目标站点标识和待上线的版本。
2. 向 Step Code 明确指定站点与版本，请求上线；`promote` 将该版本设为线上版本。
3. 访问线上地址，核对页面和资源。

## 回滚版本

1. 查看当前线上版本和历史版本，确认要恢复的版本。
2. 向 Step Code 明确指定站点与目标版本，请求回滚。
3. 重新访问线上页面，验证回滚结果。

可以先请求回滚计划，不执行操作：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
列出这个站点的最近版本和当前线上版本，给出回滚到上一稳定版本的操作计划，先不要执行。
```

## 管理入口

在[站点管理](https://platform.stepfun.com/sites)查看站点、版本和发布状态。托管额度、访问规则和平台限制以[静态托管文档](/docs/zh/guides/page-hosting)及账户实际状态为准，不应将 Step Plan 模型额度直接当作托管额度。


# 内置工具
Source: https://platform.stepfun.com/docs/zh/step-code/reference/tools



默认 Step 工具使用 `read_file`、`run_command` 等名称。原生工具集使用 `read`、`bash` 等名称；参数应按实际注册的工具查询。

## 工具总表

| Step 工具 | 对应原生工具 | 用途 |
| - | - | - |
| `read_file` | `read` | 读取文本和图片 |
| `write_file` | `write` | 创建或覆盖文件 |
| `edit_file` | `edit` | 精确替换文本 |
| `run_command` | `bash / powershell` | 执行命令 |
| `search_files` | `grep` | 搜索文件内容 |
| `find_files` | `find` | 按名称或 glob 查找文件 |
| `list_directory` | `ls` | 列出目录 |

## read\_file

支持文本文件和 JPG、PNG、GIF、WebP、BMP 图片。使用 `path` 指定文件；文本可通过 `start_line`、`end_line` 指定行范围，`max_chars` 控制返回字符数。图片作为附件返回，能否用于推理取决于模型能力。

## run\_command

使用 `command` 指定命令，`cwd` 指定目录，`max_output_chars` 限制返回文本。前台默认超时为 120 秒（v0.1.3 起），可用 `timeout_ms` 调整，取值范围 1000 至 600000 毫秒。

Windows 的 Bash 命令优先使用原生 Git Bash，不自动改用 WSL；PowerShell 是另一执行路径。需要 WSL 时可在 WSL 内启动 Step，或配置对应的 `shellPath`。

`run_in_background` 启动分离进程并返回 PID 与日志文件。通过日志检查状态，使用返回的停止命令清理进程；会话结束时仍运行的进程会被清理。后台模式下 `timeout_ms` 和 `max_output_chars` 均不适用。输入框中的 `!` 和 `!!` 行为见[交互与任务控制](/docs/zh/step-code/guides/interaction)。

## edit\_file

对单个文件进行精确文本替换。模型侧 `edit_file` 使用 `path`、`search`、`replace`、`replace_all` 和 `then_run`；`search` 是待替换的字面量文本（不是正则），`replace` 是新文本。`search` 默认必须唯一匹配，重复出现时报错；设置 `replace_all=true` 时替换全部匹配。匹配失败时先重新读取文件，避免根据过期内容修改。

## write\_file

使用 `path` 和 `content` 创建或完整覆盖文件。保留原内容的局部修改使用 `edit_file`。

v0.1.3 起，`edit_file` 和 `write_file` 支持可选参数 `then_run`：修改或写入成功后运行验证命令并返回结果。命令遵守正常审批；验证失败不会撤销已写文件。

## search\_files

模型侧 `search_files` 使用 `pattern`、`path`、`glob`、`context_lines` 和 `max_results`，其中 `pattern` 为正则表达式。后端顺序为 ripgrep（自动下载或系统）> `git grep`（在 Git 仓库内时）> POSIX `grep`，全部不可用时报错。搜索工具缓存见[数据路径](/docs/zh/step-code/configuration/data-paths#内置工具缓存)。

## find\_files

使用 `path`、`pattern` 和 `max_results` 按文件名或 glob 查找。返回路径后，使用读取工具检查文件。

## list\_directory

使用 `path` 指定目录，`include_hidden` 控制隐藏项，`max_entries` 限制条目数。

## 工具开关

`defaultTools` 控制原生内置工具，例如：

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
defaultTools = ["read", "grep", "find", "ls"]
```

Step 工具和扩展工具需要另行选择，不能把上述原生工具配置当作整个会话的只读限制。原生 `read` 使用 `offset` / `limit`，原生 `edit` 使用 `oldText` 等字段；不要将这些参数传给同用途的 Step 工具。

| 启动参数 | 用途 |
| - | - |
| `--tools` | 按注册名称选择工具 |
| `--exclude-tools` | 排除指定工具 |
| `--no-builtin-tools` | 禁用原生内置工具 |
| `--no-tools` | 禁用全部工具 |

工具审批与访问边界见[权限与安全](/docs/zh/step-code/guides/permissions)，完整启动参数见 [`step` 命令](/docs/zh/step-code/reference/cli)。


# 版本记录
Source: https://platform.stepfun.com/docs/zh/step-code/release-notes



## v0.1.6

2026 年 10 月 23 日

### 新功能

* 子代理后台运行：subagent 新增 `run_in_background`，后台任务立即返回通道编号，结束后推送含摘要、用量与子会话路径的通知；`agent_send` 按通道编号操作，支持 reply / stop / status（旧的别名、分组、扇出寻址已移除）。并发上限 8，空闲 10 分钟自动停止，`[subagent] background = false` 可退回前台。
* 飞书（Lark）远程连接（实验性）：`/connect lark` 将终端会话连接到飞书：授权后向机器人发首条消息绑定会话（群聊需 @机器人），工具审批同步为飞书卡片，可远程批准/拒绝；远程审批需在连接成功后完成一次回调配置。`/connect lark off` 断开。
* 一次性侧问：`/btw <问题>` 在浮层中提问并作答，不写入会话文件、不进入主对话的模型上下文；回答基于当前对话分支的副本生成。侧问历史仅存内存（20 条），只用于追问。
* 指定工作目录：新增 `-C` / `--cwd <目录>` 参数，供脚本与 IDE 集成固定项目目录，会话存储与设置发现均以该路径为准；路径无效则启动即报错。
* 终端标签页忙碌指示：Agent 工作或压缩上下文时，终端标签页显示忙碌指示（Otty / Ghostty 默认开启，其余终端可在 `/settings` 强制）；失败的工具行不再显示恢复提示行。
* 最近使用的模型：`/model` 选择器顶部新增 Recent 区，显示最近选用过的模型（最多 10 个，重复选用置顶），全局保存、跨会话共享。
* 会话搜索索引：新增 SQLite 全文会话索引供 Web / 桌面端搜索，JSONL 仍是唯一数据源、可随时重建，子代理会话不入搜索；CLI 新增 `step session-index status / reindex / clear`。
* 反馈报告附带证据：`/feedback` 自动附上排查证据：会话摘要（模型、token、成本、缓存命中率等）、请求耗时与中断阶段、超长对话首尾归档及工具输出；统一脱敏并记录版本环境，提交前有确认页。

### 优化

* 计划模式不再使提示缓存失效：提示缓存按请求公共前缀命中，工具列表位于前缀最前；此前进入计划模式会重排工具列表、令整段对话缓存失效（实测 233k token 只回 1.6k，约 0.7%）。现在默认工具列表不动，只读限制由执行时守卫拦截编辑类工具的越界写入。
* 任务状态快照只在变化时追加：上下文状态提示也固定在原始位置，请求前缀更稳定，缓存复用更好。
* `/model` 回车即保存：回车直接选中并保存为默认模型（`/model <provider/id>` 同样保存），Ctrl+S 移除；此前回车仅当次会话生效，两条路径会悄悄漂移。
* `run_command` 标题按宽度截断：折叠时标题只显示命令首行、按终端宽度截断，长脚本与 heredoc 不再占满会话记录；展开仍见完整命令。

### 修复

* Windows 上 `step update` 始终失败：下载与校验成功后仍必失败，原因是更新器按 Unix 包的外层目录查找 `step.exe`，而 Windows zip 为平铺布局；现按二进制实际位置判定根目录。
* 更新失败可诊断：安装失败信息附带最后 20 行安装器输出（注明省略行数），不再只有退出码。
* 非交互命令提前返回：`-p` / JSON 模式下 `/plan <任务>` 这类命令会在回合进行中销毁会话（报 ctx is stale、不写会话文件）；现在等回合结束才返回。
* `search_files` 行号误判：匹配文本含 `:数字:` 时被误当行号，读错源码行或误报无匹配；现直接读取结构化匹配结果，不再二次解析渲染文本。
* `find_files` 误丢路径：以 `[` 或 `WARNING:` 开头的路径被误当通知丢弃；现优先读取结构化匹配列表。
* workflow `phase()` 静默零运行：`phase(title)` 只是里程碑标签，把 agent 调用包进回调传给它会零运行却报告完成；现在静态检查直接拒绝并指出行号。
* 压缩失败重试：压缩遇响应流不完整（SSE 提前断开）时按瞬态错误重试；仍失败则将脱敏诊断写入会话文件。

## v0.1.5

2026 年 10 月 16 日

### 新功能

* 用量面板：新增 `/usage` 命令，提供总览与账户两个标签页：总览展示近期活跃热力图和每日 token 用量，账户页查询个人 Step Plan 剩余额度与重置时间。`/usage overview`、`/usage account` 可直接打开对应页。
* 状态面板：新增 `/status` 命令，一屏查看当前模型、思考档位、权限模式、工作目录和账户信息。
* 任务自查：在 `-p`/JSON 非交互模式中，加 `--completion-review` 可让 Agent 收尾前对照原始任务自查一遍，检查是否做全、接口与边界是否覆盖、测试是否跑过；发现问题先修再总结。

### 优化

* 编辑后验证：`edit_file` / `write_file` 的 `then_run` 改走与 `run_command` 一致的执行路径，超时、输出上限和审批规则与 `run_command` 相同。
* 无界面模式计划审批：`-p`/JSON 非交互模式下提交计划后，若无法直接询问用户，会明确返回计划内容并停止。

### 修复

* 技能冲突提示：修复同一技能同时安装于 `~/.agents/skills` 和 `~/.claude/skills` 时启动刷屏的问题。
* 无套餐账户登录：修复没有套餐的账户登录后无法使用的问题，现在会引导改用 API Key 登录。
* Workflow 重试与并发：修复 workflow 重试与限流误判的问题，按错误类型而非错误文本判断是否重试；同时修复 workflow 与并行子代理同时运行可能超过并发上限的问题。
* Workflow 恢复与失败上报：修复断点恢复时单个调用失败会拖累后续调用全部重跑的问题；失败节点和回调错误现在会出现在最终结果中。

## v0.1.4

2026 年 10 月 12 日

### 新功能

* 新增 CLM（Context Language Models）上下文管理。长对话接近上下文上限时默认启用，由模型选择性精简较早的上下文，原始会话日志不被覆盖；精简失败时回退到原有的摘要压缩。`/clm` 提供 `status`、`on`、`off`、`diff`、`reset` 子命令管理状态，`/clm-compact` 主动请求模型整理上下文，相关模型用量计入会话统计。
* 权限模式调整为 Ask、Approve for Me 和 Full Access。Ask 在修改文件或运行命令前询问；Approve for Me 自动执行常规操作，对检测到的危险命令或无法完整分析的命令仍要求确认；Full Access 允许直接执行风险命令，不再逐次确认。开启 Full Access 前需确认风险，可选择仅本次会话生效或记住选择。

### 优化

* 思考档位统一使用 `/effort` 调整，原 `/thinking` 命令已移除。
* 重新打开同一会话时，自动恢复此前设置的 Ultracode 开关及状态栏提示；新会话仍默认关闭。

### 修复

* 修复首次启动时 StepPage 尚未就绪即连接失败、导致当前会话无法使用网页发布功能的问题。StepPage 准备失败不影响 Step Code 的其他功能，后续启动时会重试。
* 修复安装或升级后重新打开终端可能提示找不到 `step` 命令的问题。
* 修复在用户主目录下启动时同一插件被重复识别、错误提示存在插件覆盖冲突的问题。
* 修复在全局配置中禁用 MCP 服务后，同名插件声明仍可能使其被重新发现的问题。
* 修复工具已经完成、界面却仍显示 Running、Reading 或 Editing 的问题。
* 修复不同项目路径映射到同一会话目录时，会话列表混入其他项目记录、`--continue` 继续到错误项目会话的问题。
* 修复子代理多步骤任务返回结果不完整、后台任务完成后未继续处理，以及长报告被截断的问题；同时修复任务状态显示错误、列表闪烁和进度通知刷屏的问题。
* 修复 Git 安装在自定义目录时误用 WSL 环境运行命令、导致找不到 Windows 中已安装工具的问题。
* 修复 Windows 下 Git Bash 后台命令退出失败、日志为空的问题。

## v0.1.3

2026 年 10 月 9 日

### 新功能

* 新增 Step Plan 远程登录。在 SSH、远程服务器或容器中运行 `step login --no-browser`，会返回完整的授权链接，可在本机或其他设备的浏览器中打开并完成登录，不依赖本地回调端口。
* `edit_file` 与 `write_file` 新增可选参数 `then_run`：文件修改成功后直接运行验证命令并返回结果，无需再单独发起一次验证调用。
* 新增 `--completion-check git-committed` 选项。在 `-p` 或 JSON 模式下，检查本轮改动是否已提交、是否还有未提交文件，以及是否已给出最终答复；未满足条件时会在原会话中提醒 Agent 继续完成，默认最多追加两轮。配合 `--completion-review` 可再进行一次自查，两者共用追加轮次。

### 优化

* 可通过 `STEP_CODING_AGENT_PLAN_DIR` 将计划文件存放在工作区之外，计划文件不会进入代码提交，也不影响工作区状态检查。

### 修复

* 修复已有 Skill 未被自动扫描的问题。`~/.claude/skills`、已信任项目的 `.claude/skills` 与 `~/.stepcode/skills` 现在会自动加载，无需手动配置路径。
* `run_command` 默认超时调整为 120 秒，可通过 `timeout_ms` 参数指定其他值，减少命令长时间无响应导致任务挂起的情况。
* 修复 Linux 下子进程残留导致任务持续等待的问题；命令被系统信号终止时，会正确报告为失败状态。
* 修复命令输出被缩短时完整日志路径或退出状态丢失的问题。退出码、超时或中止原因会一并保留，便于 Agent 查看完整日志后继续排查。
* 修复多次压缩上下文时已有历史摘要未被保留的问题，长任务可以继续使用此前总结的工作信息；同时修复摘要输出超过模型允许上限的问题。
* 修复 Ultracode 欢迎提示与命令入口不一致、缺少使用帮助与命令补全，以及开启状态在常见终端宽度下不可见的问题。
* 新增 `/ultracode` 命令，用于开启、关闭和查看多代理协作状态；原 `/ultraloop` 命令保留，两者功能相同。

## v0.1.2

2026 年 9 月 30 日

### 新功能

* 新增 `--non-interactive-denial continue` 选项。在非交互运行中（如 `-p` 模式），需要人工确认的危险操作被拦截后，将失败原因反馈给 Agent，由其尝试更安全的方式继续执行任务。默认值仍为 `terminate`，即终止任务；两种策略均遵循原有权限限制。

### 优化

* 插件市场的插件列表支持搜索，并移除同名重复项。在交互界面添加市场时显示进度，支持取消，添加成功后进入插件列表。
* 过长的工具返回文本以预览形式呈现，并提供全文文件路径，减少模型上下文占用。
* 对话中仅展示最近一次成功的任务计划更新，减少重复内容；恢复会话时同样生效。
* 优化单行输入时使用上方向键浏览历史记录的行为。全屏模式新增 `Ctrl+End` 快捷键，可返回底部并跟随新输出。

### 修复

* 修复启动或切换 Step 模型时，思考级别被强制设置为最高级别的问题。
* 修复 Skill 扫描卡住，以及 Skill 命令无法识别换行输入的参数的问题。
* 修复内置上下文压缩后丢失已加载 Skill 指令的问题。
* 上下文压缩的摘要请求超限时，尝试缩减旧历史记录并重试。
* 修复已安装插件的 Skill 和提示词命令未加载的问题，重新加载资源后即可使用。
* 修复插件 MCP 的配置识别、服务器名称识别和登录授权复用问题；本地 MCP 服务器默认从插件目录启动。
* 修复 MCP 分页工具列表加载不完整，以及后加载的可用 MCP 工具和扩展工具无法被搜索到的问题；工具列表随服务器通知更新。

## v0.1.1

2026 年 9 月 24 日

### 新功能

* 首次启动时自动预装 StepPage 插件；用户主动卸载后不会重复安装。

### 优化

* 减少子代理任务列表的频繁重绘，减轻闪烁，提升任务信息的可读性。
* macOS / Linux 安装完成后新增启动提示，引导用户运行 `step`。
* 更新中英文 README，补充 StepPage 发布说明与演示。

### 修复

* 修复正式安装版中 Workflow 和 Ultraloop 无法使用的问题，工作流沙箱由 `isolated-vm` 切换为 QuickJS WebAssembly。
* 修复 Workflow 在未等待异步任务、并行任务运行较久及资源清理等场景下的异常退出和错误超时。
* 修正 Step Plan 联网搜索的计费路径，改用订阅对应接口。
* 修复已登录用户仍被插件诊断提示缺少 `STEPFUN_API_KEY` 的问题。


# StepFun 开放平台文档中心
Source: https://platform.stepfun.com/docs/zh/welcome



# 开始使用 StepFun

模型接入、应用开发与运行维护的指南和参考。

[API 快速开始](/docs/zh/quickstart/overview)
[获取 API Key](https://platform.stepfun.com/interface-key)
[API 参考](/docs/zh/api-reference/chat/chat-completion-create)

## 了解模型与首次调用

## 开发与验证应用

[异常处理](/docs/zh/guides/developer/exception)
[故障排查](/docs/zh/guides/developer/troubleshooting)

### 开发工具与订阅

## 平台使用与管理


# 图像模型下线公告
Source: https://platform.stepfun.com/docs/zh/announcements/image-model-retirement



`step-2x-large`、`step-image-edit-2` 已于 **2026 年 10 月 10 日** 下线；`step-1x-edit` 在此之前已停止服务。文生图、图生图、图片编辑三类接口已在国内和海外同步停止服务，继续调用无法正常返回结果。

> [!NOTE]
>
> 上述模型与接口均已停止服务，相关业务请迁移到其他模型。

## 下线信息

| 项目 | 内容 |
| - | - |
| 下线时间 | 2026 年 10 月 10 日 |
| 影响范围 | 国内、海外同步下线 |
| 涉及模型 | `step-2x-large`、`step-image-edit-2`（已下线）；`step-1x-edit`（在此之前已停止服务） |
| 涉及能力 | 文生图、图生图、图片编辑 |

## 下线接口及影响

以下开放平台 API 和 Step Plan 图像接口已于 **2026 年 10 月 10 日** 在国内和海外同步停止服务：

| 服务 | 能力 | 请求方式 | 接口路径 |
| - | - | - | - |
| 开放平台 API | 文生图 | POST | `/v1/images/generations` |
| 开放平台 API | 图生图 | POST | `/v1/images/image2image` |
| 开放平台 API | 图片编辑 | POST | `/v1/images/edits` |
| Step Plan | 文生图 | POST | `/step_plan/v1/images/generations` |
| Step Plan | 图片编辑 | POST | `/step_plan/v1/images/edits` |

* **开放平台 API 和 Step Plan**：上述图像接口已停止服务。Step Plan 的文本、推理、语音与智能路由等其余模型不受影响。
* **Studio**：生图能力已不再提供。

## 常见问题

> **这些模型现在还能调用吗？**
>
> 不能。`step-2x-large` 和 `step-image-edit-2` 已于 **2026 年 10 月 10 日** 下线，`step-1x-edit` 在此之前已停止服务。开放平台 API 和 Step Plan 图像接口均已停止服务，继续调用无法正常返回结果。

> **step-1x-edit 现在还能调用吗？**
>
> 不能。`step-1x-edit` 已停止服务；`step-2x-large`、`step-image-edit-2` 也已于 2026 年 10 月 10 日下线。

> **已经生成的图片链接还能访问吗？**
>
> 图片下载链接本身存在有效期限制，与本次下线无关。建议将需要长期保留的图片及时下载并存储到您自己的存储服务。

如有疑问，可通过[联系我们](/docs/zh/guides/contact-us)获取支持。


# Step 5 Preview API 缓存价格调整公告
Source: https://platform.stepfun.com/docs/zh/announcements/step-5-preview-price-adjustment



自北京时间 2026 年 10 月 14 日 00:30 起，开放平台调整 Step 5 Preview 按量付费 API 的缓存命中输入价格。Step Plan 接入地址下的缓存命中输入价格不在本次调整范围内。

## 调整内容

| 计费项 | 调整前 | 调整后标准价格 |
| - | - | - |
| 缓存命中输入 | 0.35 元／百万 tokens | 0.70 元／百万 tokens |
| 缓存未命中输入 | 7 元／百万 tokens | 保持不变 |
| 输出 | 20 元／百万 tokens | 保持不变 |

> [!NOTE]
>
> 北京时间 2026 年 10 月 14 日 00:30 前，已通过按量付费 API 调用过 Step 5 Preview 的用户，后续调用继续按原缓存命中输入价格 0.35 元／百万 tokens 计费，不受本次调价影响。

完整的模型价格见 [API 定价](/docs/zh/guides/pricing/details)。


# Step Plan 升级公告
Source: https://platform.stepfun.com/docs/zh/announcements/step-plan-upgrade



> [!NOTE]
>
> 本公告记录 2026 年 6 月 18 日的套餐升级方案。后续续订与升级规则已有更新，请以 [Step Plan 套餐调整公告](/docs/zh/announcements/step-plan-usage-adjustment#原套餐权益保留规则)中的规则为准。

Step Plan 自 2026 年 6 月 18 日起升级为 **Credit 月池** 计费，新套餐为 **Token Plan**。旧版 **Coding Plan** 当前周期权益不受影响；已开启自动续费的用户可继续按 Coding Plan 自动续订，未开启自动续费的用户到期后需升级至 Token Plan 才能继续使用。升级至 Token Plan 为单向操作，确认后不可回退。

## 本次变更

Token Plan 在计量单位、套餐方式与超额承接三方面进行了升级：

| 改动项 | 旧版 Coding Plan | 新版 Token Plan |
| - | - | - |
| 计量单位 | 按请求次数（Prompt） | Credit（统一计费单位，1M Credit = ¥1） |
| 套餐方式 | 5 小时 / 周限额 | Credit 月池：额度按月发放，月内任意时段消耗，月末清零 |
| 超额承接 | 额度用尽即切断 | 加油包当月加购补充额度，周期单独 30 天 |

新套餐的档位价格、Credit 额度、加油包与计费规则，详见 [套餐与计费](/docs/zh/step-plan/pricing)。

## 旧套餐用户须知

如果您正在使用旧版 Coding Plan，当前周期内的额度、权益与到期时间保持不变，可正常使用至周期结束。后续是否需要升级，取决于您是否开启了自动续费：

* **已开启自动续费**：将继续按旧版 Coding Plan 自动续订下一周期，无需升级即可持续使用。您也可以随时主动升级至 Token Plan。请注意，续费扣款失败会导致 Coding Plan 被取消。Coding Plan 被取消后无法重新订购，如需继续使用 Step Plan，只能购买新版 Token Plan。若希望继续使用 Coding Plan，请在每次续费日前确认绑定的支付方式可用、额度充足。
* **未开启自动续费**：Coding Plan 不支持手动续订，当前周期到期后如需继续使用 Step Plan，需升级至新版 Token Plan。

> [!WARNING]
>
> 升级至 Token Plan 为单向操作，确认后无法回退至旧版 Coding Plan。Coding Plan 一旦到期未续或被取消，均无法重新订购，届时只能购买 Token Plan，建议及时处理以免服务中断。

## 升级到 Token Plan

旧套餐用户可在控制台主动升级至新版 Token Plan，升级规则如下：

* **到期时间保持不变**：原本几号到期，升级后仍是几号到期。
* **完整额度发放**：升级后立即按新套餐当月完整 Credit 额度发放，不按剩余天数折算。
* **自动续费选项**：若升级前已开启自动续费，升级时会展示续费勾选项（默认勾选），您可选择保留或取消；若升级前未开启自动续费，则不展示该选项。目前暂不支持手动开启自动续费。
* **单向操作**：升级确认后不可回退至旧套餐。
* **暂不支持升级同时升档**：本次升级仅完成「旧套餐 → 新套餐同档」切换，不支持在升级的同时变更档位。如需更高档位，请在升级完成后再进行档位升级（见下文）。

## 档位升级

完成升级后，您可在周期内将当前 Token Plan 档位升级至更高档位，按剩余时间比例补差价：

* **补差价金额** = 原档位价格 ×（1 − 已用时间 / 总周期），仅就尚未使用的周期部分计算差价，不涉及 Credit 余量折算。
* 升级后立即按新档位刷新整月 Credit。
* 升档约束：新档位价格须不低于原档位价格，且新档位周期须不短于当前剩余权益时间。

以上规则的具体金额与展示，均以控制台订阅页实际为准。

## 常见问题

> **旧套餐（Coding Plan）到期后还能继续用吗？**
>
> 取决于是否开启了自动续费。已开启自动续费的用户，会继续按旧版 Coding Plan 自动续订下一周期，无需升级即可继续使用；未开启自动续费的用户，Coding Plan 不支持手动续订，到期后需升级至 Token Plan 才能继续使用。

> **我开启了 Coding Plan 自动续费，会被强制升级到 Token Plan 吗？**
>
> 不会。只要自动续费正常完成，您会继续按旧版 Coding Plan 自动续订，是否升级至 Token Plan 完全由您决定。但如果续费扣款失败，Coding Plan 会被取消，且无法重新订购，此后只能购买 Token Plan。

> **自动续费扣款失败会怎样？**
>
> Coding Plan 将被取消。Coding Plan 被取消后无法重新订购，如需继续使用 Step Plan，只能购买新版 Token Plan。建议提前确认绑定的支付方式可用、额度充足。

> **升级会改变我的到期时间吗？**
>
> 不会。升级后到期时间与原套餐保持一致，原本几号到期仍是几号到期。

> **升级后我的 Credit 会按剩余天数折算吗？**
>
> 不会。升级后立即按新套餐当月完整额度发放，与升级时点在周期内的位置无关。

> **升级可以回退到旧套餐吗？**
>
> 不可以。升级为单向操作，确认后无法回退至旧版 Coding Plan。

> **可以在升级的同时升档吗？**
>
> 暂不支持。本次升级仅完成「旧套餐 → 新套餐同档」切换。如需更高档位，请在升级完成后再单独进行档位升级，届时按剩余时间比例补差价。

> **1M Credit 等于多少钱？**
>
> Credit 与支付金额按 1M Credit = ¥1 换算。各档位的 Credit 月度额度与价格，详见 [套餐与计费](/docs/zh/step-plan/pricing#套餐档位)。

更多关于 Credit、月池、加油包与档位的说明，请参阅 [套餐与计费](/docs/zh/step-plan/pricing)。


# Step Plan 套餐调整公告
Source: https://platform.stepfun.com/docs/zh/announcements/step-plan-usage-adjustment



自北京时间 2026 年 10 月 15 日 00:00 起，Step Plan 中的 Step 5 Preview 将实行分时段 Credit 扣减。调整生效前已付费且订阅仍有效的用户，可保留原套餐权益。

## Step 5 Preview Credit 扣减规则调整

| 时段 | 时间（北京时间） | Credit 扣减标准 |
| - | - | - |
| 高峰时段 | 周一至周五 09:00–12:00、14:00–18:00 | 按原标准的 2 倍扣减 |
| 低谷时段 | 上述高峰时段以外的全部时间 | 按原标准扣减 |

通过免费赠送、活动免费领取或全额使用代金券购买、兑换获得的订阅，如在调整生效前未付费购买 Step Plan，自生效时起调用 Step 5 Preview 将适用上述规则。

套餐档位、Credit 额度与完整计费规则见[套餐与计费](/docs/zh/step-plan/pricing)。

## 原套餐权益保留规则

北京时间 2026 年 10 月 15 日 00:00 前已实际付费购买 Step Plan，且在调整生效时订阅仍有效的用户，保留原套餐价格、额度、月限额及对应的扣减规则，不受本次分时段扣减调整影响。

实际付费包括微信、支付宝直接付款，实际充值余额支付，以及实际充值余额与代金券混合支付。仅有按量付费 API 充值或消费记录，或仅通过免费赠送、活动免费领取、全额代金券获得订阅，均不符合上述条件。

符合上述条件的用户在续订或升级套餐时，原套餐权益按以下规则延续：

* 续订：可按原套餐方案续费，是否开启自动续费不影响资格。但订阅到期后，需在 15 天内完成续费；超过 15 天仍未续费，将取消原套餐权益保护资格。
* 升级：可在系统支持的 Plus、Pro 档位范围内升级，继续按原扣减规则执行。[Coding Plan](/docs/zh/announcements/step-plan-upgrade) 升级时需转为 Token Plan。补缴差价及剩余订阅周期的处理方式，以升级页面说明为准。

如无法完成续费，请[提交工单](https://platform.stepfun.com/ticket)，并提供账号 UID、套餐档位、到期时间及相关支付记录，由客服核实原套餐权益保护资格和续订方式。


# 获取账户信息
Source: https://platform.stepfun.com/docs/zh/api-reference/accounts/get



查询当前账户的信息，支持查询当前账户可用余额.

## 请求地址

`GET https://api.stepfun.com/v1/accounts`

## 请求参数

无

## 请求响应

* `object` `string`\
  &#x20;固定为 `account`

* `type` `string` \
  &#x20;账户类型，可选项为 `prepaid` 预付费 和 `postpaid` 后付费

* `balance` `float` \
  &#x20;当前账户可用余额

* `total_cash_balance` `float`\
  &#x20;当前账户总充值金额

* `total_voucher_balance` `float`\
  &#x20;当前账户总赠送金额

### 示例

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl --location 'https://api.stepfun.com/v1/accounts' \
  --header 'Authorization: Bearer YOUR_STEP_API_KEY'
```

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import requests

url = "https://api.stepfun.com/v1/accounts"

payload = {}
headers = {
    "Authorization": "Bearer YOUR_STEP_API_KEY"
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
```

**响应**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "object": "account",
  "type": "prepaid",
  "balance": 0.00,
  "total_cash_balance": 0.00,
  "total_voucher_balance": 26.00
}
```


# 音频文件识别
Source: https://platform.stepfun.com/docs/zh/api-reference/audio/asr



将音频文件中的人声内容异步识别为文本，适合较长音频的离线转写。当前支持中英文识别（暂不支持中文方言及其他语种），支持分句与字 / 词级时间戳、双声道分轨、说话人识别（Speaker Diarization），暂不支持热词。推荐使用模型 `stepaudio-2.5-asr`。

> [!NOTE]
>
> 如需实时流式识别，请参考 [流式语音识别（双向流式）](/docs/zh/api-reference/audio/asr-stream) 或 [语音识别（流式返回文本）](/docs/zh/api-reference/audio/asr-sse)。

## 提交任务

创建一个新的语音识别任务。

请求地址：`POST https://api.stepfun.com/v1/audio/asr/file/submit`

### 请求头

* `Authorization` `string` ***required***\
  认证令牌，格式为 `Bearer $STEPFUN_API_KEY`。
* `Content-Type` `string` ***required***\
  固定为 `application/json`。
* `X-Trace-Id` `string` ***optional***\
  调用方自定义 Trace ID；不传则由服务端生成。
* `X-Request-Id` `string` ***optional***\
  调用方自定义 Request ID；不传则由服务端生成。

### 请求参数

* `audio` `object` ***required***\
  音频配置。`format` 必填；`pcm` 格式需额外填写采样率等相关参数。

  * `format` `string` ***required***\
    音频容器格式，支持 `wav`、`mp3`、`pcm`、`ogg`、`m4a`。
  * `codec` `string`\
    编码格式，可选 `raw` / `opus`，默认 `raw`（pcm）。
  * `rate` `int`\
    采样率；`pcm` 格式必填。
  * `bits` `int`\
    采样位深，默认 `16`，当前仅支持 16bit。
  * `channel` `int`\
    声道数，`1`（单声道）/ `2`（双声道），默认 `1`；须与音频实际声道数一致。
  * `url` `string`\
    公网可访问的音频文件地址，支持 `wav`、`mp3`、`ogg`、`pcm`、`m4a`，文件需小于 100MB。

* `request` `object` ***required***\
  识别配置：模型能力与输出格式。

  * `model_name` `string` ***required***\
    模型名称，例如 `stepaudio-2.5-asr`、`step-asr-1.1`。
  * `enable_channel_split` `bool` ***optional***\
    是否启用双声道分轨识别，默认 `false`；前提是 `audio.channel` 为 `2`。
  * `show_utterances` `bool` ***optional***\
    是否输出分句、分词及时间戳信息，默认 `false`。
  * `enable_speaker_info` `bool` ***optional***\
    是否启用说话人识别，默认 `false`；开启后每个 utterance 附带 `speaker.id`，需同时设置 `show_utterances=true`。单个任务最多可区分 10 个说话人。

### 请求示例

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "audio": {
    "format": "wav",
    "codec": "pcm",
    "rate": 16000,
    "bits": 16,
    "channel": 1,
    "url": "https://example.com/audio.wav"
  },
  "request": {
    "model_name": "stepaudio-2.5-asr",
    "enable_channel_split": false,
    "show_utterances": false
  }
}
```

### 返回

* `task_id` `string`\
  任务 ID，用于后续查询结果。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "task_id": "018f2f1a-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## 查询结果

根据任务 ID 查询识别进度或获取最终结果。

请求地址：`POST https://api.stepfun.com/v1/audio/asr/file/query`

### 请求参数

* `task_id` `string` ***required***\
  提交任务时返回的任务 ID。

### 返回字段

* `status` `string`\
  任务状态。排队中返回 `PENDING`、运行中返回 `RUNNING`，此时响应体仅含该字段；处理失败时返回 `FAILED`。

* `error` `object`\
  失败原因，仅 `status` 为 `FAILED` 时返回。

  * `stage` `string`\
    失败阶段，例如 `audio_download`（音频下载失败）。
  * `message` `string`\
    失败描述，例如 `invalid audio url`。

* `duration` `float`\
  音频时长（秒），仅识别成功时返回。

* `result` `object array`\
  识别结果，仅识别成功时返回。

  * `text` `string`\
    整段音频的识别文本。
  * `utterances` `object array`\
    分句信息，开启 `show_utterances` 时返回。

    * `text` `string`\
      分句文本。

    * `start_time` `int`\
      分句起始时间（毫秒）。

    * `end_time` `int`\
      分句结束时间（毫秒）。

    * `words` `object array`\
      字 / 词级信息。

      * `text` `string`\
        字 / 词文本。
      * `start_time` `int`\
        起始时间（毫秒）。
      * `end_time` `int`\
        结束时间（毫秒）。

    * `speaker` `object`\
      该句所属说话人，开启 `enable_speaker_info` 且 `show_utterances=true` 时返回。

      * `id` `string`\
        说话人 ID（如 `spk_1`），同一任务内稳定、跨任务不保证。

#### 示例

处理中（排队时返回 `PENDING`，运行中返回 `RUNNING`）：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{ "status": "RUNNING" }
```

处理成功：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "duration": 5.901375,
  "result": [
    {
      "text": "识别出的完整文本",
      "utterances": [
        {
          "text": "你好",
          "start_time": 0,
          "end_time": 500,
          "words": [
            { "text": "你", "start_time": 0, "end_time": 200 },
            { "text": "好", "start_time": 200, "end_time": 500 }
          ]
        }
      ]
    }
  ]
}
```

处理失败：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "status": "FAILED",
  "error": {
    "stage": "audio_download",
    "message": "invalid audio url"
  }
}
```

### 声道拆分说明

当 `enable_channel_split=true` 且输入为立体声时，服务端会拆分为多个声道分别识别，`result` 数组长度可能为 2，每个元素对应一个声道的输出。

### 说话人识别说明

在本接口可选开启说话人识别：

* `enable_speaker_info=true`：每个 utterance 附带 `speaker.id`，标识该句属于哪个说话人。需同时设置 `show_utterances=true`（`speaker.id` 挂在 utterance 下，无 utterances 则无处体现）。
* 单个任务最多可区分 10 个说话人。
* `speaker.id`（如 `spk_1`）同一任务内稳定、跨任务不保证。
* 可与 `enable_channel_split` 并存：分声道后在各声道内再区分说话人。

请求示例（开启说话人识别）：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "audio": { "format": "wav", "url": "https://example.com/meeting.wav" },
  "request": {
    "model_name": "stepaudio-2.5-asr",
    "show_utterances": true,
    "enable_speaker_info": true
  }
}
```

返回示例（含说话人标记，节选）：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "duration": 8.5,
  "result": [
    {
      "text": "你好请问有什么可以帮助您的吗在的我想咨询一下退款流程",
      "utterances": [
        { "text": "你好请问有什么可以帮助您的吗", "start_time": 0, "end_time": 1820, "speaker": { "id": "spk_1" } },
        { "text": "在的我想咨询一下退款流程", "start_time": 2000, "end_time": 4500, "speaker": { "id": "spk_2" } }
      ]
    }
  ]
}
```

## 错误处理

接口以标准 JSON 错误响应返回失败原因（HTTP 状态码与错误结构以网关 / 服务端实现为准）。常见场景：

* 鉴权失败：未提供或提供了错误的 `Authorization` 头（`Bearer $STEPFUN_API_KEY`）。
* 模型不支持：`request.model_name` 非 `stepaudio-2.5-asr`。
* 限流 / 白名单限制：请求被限流或不在白名单。
* 任务不存在：`task_id` 不存在或不属于当前 uid。
* 任务失败：后台处理失败（下载失败 / 转码失败 / 识别失败等）。

完整错误码参见 [错误码](/docs/zh/api-reference/error-codes)。

## 示例

**提交任务**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -sS -X POST "https://api.stepfun.com/v1/audio/asr/file/submit" \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer $STEPFUN_API_KEY' \
    -d '{
        "audio": {
            "format": "wav",
            "codec": "pcm",
            "rate": 16000,
            "bits": 16,
            "channel": 1,
            "url": "https://example.com/audio.wav"
        },
        "request": {
            "model_name": "stepaudio-2.5-asr",
            "enable_channel_split": false,
            "show_utterances": true
        }
    }'
```

**轮询查询**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -sS -X POST "https://api.stepfun.com/v1/audio/asr/file/query" \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer $STEPFUN_API_KEY' \
    -d '{"task_id":"018f2f1a-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}'
```

## 最佳实践

* 轮询节流：建议 1s\~3s 轮询一次，避免过于频繁造成限流。
* 超时控制：客户端设置总体超时，避免无限等待。
* URL 可达性：确保 `audio.url` 可被服务端直接下载（建议 HTTPS、可公网访问，或在服务网络内可访问）。
* 结果粒度：只需整段文本时用 `show_utterances=false`；需要时间戳 / 字幕对齐时用 `show_utterances=true`。
* 声道拆分：双人对话、左右声道分别录制的场景可开启 `enable_channel_split=true`。

## 音频建议

* 优先使用清晰、背景噪音较少的录音。
* 若可控制录制格式，建议 16kHz / 16bit / 单声道。
* 立体声场景如需分别识别两路说话人，可开启声道拆分。


# 语音识别（流式返回文本）
Source: https://platform.stepfun.com/docs/zh/api-reference/audio/asr-sse



基于 HTTP + SSE 的语音识别：一次性提交音频，服务端通过 SSE 持续推送增量与最终识别结果，适合服务端调用、文件转写、准实时处理。推荐使用模型 `stepaudio-3-asr-max`。

> [!NOTE]
>
> 如需基于 WebSocket 的实时双向流式识别，请参考 [流式语音识别（双向流式）](/docs/zh/api-reference/audio/asr-stream)。

## 服务地址

`POST https://api.stepfun.com/v1/audio/asr/sse`

> [!NOTE]
>
> Step Plan 场景请使用 `POST https://api.stepfun.com/step_plan/v1/audio/asr/sse`。

## 请求头

* `Content-Type` `string` ***required***\
  固定为 `application/json`。
* `Accept` `string` ***required***\
  固定为 `text/event-stream`。
* `Authorization` `string` ***required***\
  认证令牌，格式为 `Bearer $STEPFUN_API_KEY`。

## 请求参数

* `audio` `object` ***required***\
  音频数据与识别配置。

  * `data` `string` ***required***\
    Base64 编码的音频数据。
  * `input` `object` ***required***\
    识别与音频格式配置。

    * `transcription` `object`\
      识别配置。

      * `language` `string`\
        识别语言，如 `zh`。
      * `hotwords` `array`\
        热词列表，形如 `["热词1", "热词2"]`。
      * `model` `string`\
        模型名称，支持 `stepaudio-3-asr-max`、`stepaudio-2.5-asr`、`stepaudio-2-asr-pro`。
      * `enable_itn` `bool` ***optional***\
        是否开启 ITN 文本规范化，默认 `true`。
      * `enable_timestamp` `bool` ***optional***\
        是否返回识别文本对应的音频时间戳，默认 `false`。

    * `format` `object`\
      音频格式。

      * `type` `string`\
        音频容器格式，支持 `ogg`、`mp3`、`wav`、`pcm`、`m4a`。
      * `codec` `string`\
        编码格式；当 `type=pcm` 时通常传 `pcm_s16le`。
      * `rate` `int`\
        采样率；`pcm` 格式必填，其他格式选填。
      * `bits` `int`\
        位深；`pcm` 格式必填，其他格式选填。
      * `channel` `int`\
        通道数；`pcm` 格式必填，其他格式选填。

### 请求示例

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "audio": {
    "data": "audioData",
    "input": {
      "transcription": {
        "language": "zh",
        "hotwords": ["热词1", "热词2"],
        "model": "stepaudio-3-asr-max",
        "enable_itn": true,
        "enable_timestamp": true
      },
      "format": {
        "type": "pcm",
        "codec": "pcm_s16le",
        "rate": 16000,
        "bits": 16,
        "channel": 1
      }
    }
  }
}
```

> [!NOTE]
>
> 兼容性说明：
>
> * SSE 不再支持 `full_rerun_on_commit`（二遍识别纠错）参数；存量代码中如仍传入该参数，将被服务端忽略，不影响识别结果。如需二遍识别能力，请改用 WebSocket 接入（见 [流式语音识别（双向流式）](/docs/zh/api-reference/audio/asr-stream)）。

补充说明：

* 音频数据需使用 Base64 编码。
* 支持的音频格式包括 `ogg`、`mp3`、`wav`、`pcm`、`m4a`。
* 当音频格式为 `pcm` 时，`rate`、`bits`、`channel` 为必填参数；为 `ogg`、`mp3`、`wav`、`m4a` 时为选填。

## 响应

SSE 流式响应，包含以下事件类型。

### Delta 事件（transcript.text.delta）

表示增量转录文本。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "type": "transcript.text.delta",
  "meta": {
    "session_id": "sse_1642694400123456789",
    "timestamp": 1642694400123
  },
  "delta": "识别的",
  "item_id": "item_xxx",
  "content_index": 0,
  "start_time": 0,
  "end_time": 500
}
```

* `type` `string`\
  事件类型，固定为 `transcript.text.delta`。
* `meta.session_id` `string`\
  会话 ID。
* `meta.timestamp` `int64`\
  服务端事件 Unix 时间戳，单位毫秒。
* `delta` `string`\
  增量转录文本。
* `item_id` `string`\
  对话项 ID。
* `content_index` `int`\
  内容索引。
* `start_time` `int64`\
  识别文本对应的音频开始时间，单位毫秒。
* `end_time` `int64`\
  识别文本对应的音频结束时间，单位毫秒。

> [!NOTE]
>
> 当请求参数 `enable_timestamp=true` 时，Delta 事件返回结果中新增 `item_id`、`content_index`、`start_time`、`end_time` 字段；`meta.timestamp` 是服务端事件 Unix 时间戳，`start_time` / `end_time` 是识别文本在音频中的时间位置，二者单位均为毫秒。

### Done 事件（transcript.text.done）

表示完整转录文本已经生成。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "type": "transcript.text.done",
  "meta": {
    "session_id": "sse_1642694400123456789",
    "timestamp": 1642694400456
  },
  "text": "识别的完整文字内容",
  "usage": {
    "type": "realtime_asr",
    "input_tokens": 1000,
    "input_token_details": {
      "text_tokens": 0,
      "audio_tokens": 1000
    },
    "output_tokens": 50,
    "total_tokens": 1050
  }
}
```

* `type` `string`\
  事件类型，固定为 `transcript.text.done`。
* `meta.session_id` `string`\
  会话 ID。
* `meta.timestamp` `int64`\
  Unix 时间戳，单位毫秒。
* `text` `string`\
  完整转录文本。
* `usage` `object`\
  使用统计信息。

### 错误事件（error）

表示识别过程出错。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "type": "error",
  "meta": {
    "session_id": "sse_1642694400123456789",
    "timestamp": 1642694400789
  },
  "message": "错误描述信息"
}
```

* `type` `string`\
  事件类型，固定为 `error`。
* `meta.session_id` `string`\
  会话 ID。
* `meta.timestamp` `int64`\
  Unix 时间戳，单位毫秒。
* `message` `string`\
  错误描述信息。

完整错误码参见 [错误码](/docs/zh/api-reference/error-codes)。


# 流式语音识别（双向流式）
Source: https://platform.stepfun.com/docs/zh/api-reference/audio/asr-stream



基于 WebSocket 的双向流式语音识别：实时发送音频分片并持续接收增量与最终识别结果，支持服务端 VAD 语音活动检测，适合实时对话、语音助手、会议字幕等场景。推荐使用模型 `stepaudio-2.5-asr-stream`。

> [!NOTE]
>
> 如需基于 HTTP + SSE 一次性提交音频并接收流式识别结果，请参考 [语音识别（流式返回文本）](/docs/zh/api-reference/audio/asr-sse)。

## 服务地址

通过 WebSocket 连接：`wss://api.stepfun.com/v1/realtime/asr/stream`

## 鉴权

* `Authorization` `string` ***required***\
  认证令牌，格式为 `Bearer $STEPFUN_API_KEY`。

## 客户端消息

### 会话更新（session.update）

更新会话配置，包括音频格式、识别参数等。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "event_id": "event_123",
  "type": "session.update",
  "session": {
    "audio": {
      "input": {
        "format": {
          "type": "pcm",
          "codec": "pcm_s16le",
          "rate": 16000,
          "bits": 16,
          "channel": 1
        },
        "transcription": {
          "model": "stepaudio-2.5-asr-stream",
          "language": "zh",
          "prompt": "请记录下你所听到的语音内容。",
          "full_rerun_on_commit": true,
          "enable_itn": true
        },
        "turn_detection": {
          "type": "server_vad",
          "silence_duration_ms": 800,
          "threshold": 0.6
        }
      }
    }
  }
}
```

* `event_id` `string` ***required***\
  当前消息事件 ID。

* `type` `string` ***required***\
  消息类型，固定为 `session.update`。

* `session.audio.input.format` `object`\
  音频格式。

  * `type` `string`\
    音频容器格式，支持 `pcm`、`ogg`。
  * `codec` `string`\
    音频编码格式；当 `type=pcm` 时传 `pcm_s16le`。
  * `rate` `integer`\
    音频采样率。
  * `bits` `integer`\
    音频位深。
  * `channel` `integer`\
    音频通道数。

* `session.audio.input.transcription` `object`\
  识别配置。

  * `model` `string`\
    转录模型名称，支持 `stepaudio-2.5-asr-stream`（推荐）、`step-asr-1.1-stream`（逐步废弃）。
  * `language` `string`\
    识别语言，如 `zh`。
  * `prompt` `string`\
    提示词，用于补充上下文或专业术语。
  * `full_rerun_on_commit` `boolean`\
    是否在提交后进行二遍识别纠错，默认 `false`。
  * `enable_itn` `boolean`\
    是否开启 ITN 文本规范化。
  * `enable_timestamp_align` `boolean`\
    仅 `stepaudio-2.5-asr-stream` 生效。是否开启字级时间戳对齐，默认 `false`；开启后 `completed` 事件的 `words` 返回更精确的字级时间戳。

* `session.audio.input.turn_detection` `object`\
  语音活动检测（VAD）配置。

  * `type` `string`\
    检测类型，支持 `server_vad`。
  * `silence_duration_ms` `integer`\
    静音阈值，超过该时长后认为一句话结束。
  * `threshold` `number`\
    VAD 检测阈值，值越大越严格。

补充说明：

* 当前支持 `stepaudio-2.5-asr-stream`、`step-asr-1.1-stream`。
* 如果不传 `turn_detection.type=server_vad`，服务端不会自动做 VAD，此时客户端需主动发送 `input_audio_buffer.commit`。

### 追加音频（input\_audio\_buffer.append）

发送音频数据进行实时识别。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "event_id": "event_124",
  "type": "input_audio_buffer.append",
  "audio": "base64_encoded_audio_data"
}
```

* `event_id` `string` ***required***\
  事件唯一标识。
* `audio` `string` ***required***\
  base64 编码的音频数据（WAV 格式）。

### 提交缓冲区（input\_audio\_buffer.commit）

仅在关闭 `server_vad` 时需要发送该消息，要求服务端提交音频缓冲区、触发转录处理。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "event_id": "event_125",
  "type": "input_audio_buffer.commit"
}
```

* `event_id` `string` ***required***\
  事件唯一标识。

## 服务端消息

### 会话创建确认（session.created）

确认会话创建成功。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "319612d9-aede-4456-a1fd-bb9c21493cd9",
    "type": "session.created",
    "meta": {
        "session_id": "test_trace_1766470129914296764",
        "timestamp": 1766468589040
    },
    "session": {
        "audio": {
            "input": {
                "transcription": {
                    "language": "zh"
                },
                "format": {
                    "type": "pcm",
                    "codec": "pcm_s16le",
                    "rate": 16000,
                    "bits": 16,
                    "channel": 1
                },
                "turn_detection": {
                    "type": "server_vad",
                    "silence_duration_ms": 800
                }
            }
        }
    }
}
```

### 会话更新确认（session.updated）

确认会话配置更新成功。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "319612d9-aede-4456-a1fd-bb9c21493cd9",
    "type": "session.updated",
    "meta": {
        "session_id": "test_trace_1766470129914296764",
        "timestamp": 1766468589040
    },
    "session": {
        "audio": {
            "input": {
                "transcription": {
                    "language": "zh"
                },
                "format": {
                    "type": "pcm",
                    "codec": "pcm_s16le",
                    "rate": 16000,
                    "bits": 16,
                    "channel": 1
                },
                "turn_detection": {
                    "type": "server_vad",
                    "silence_duration_ms": 800
                }
            }
        }
    }
}
```

### 语音开始（input\_audio\_buffer.speech\_started）

仅在开启 `server_vad` 时返回，表示服务端检测到语音开始。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "319612d9-aede-4456-a1fd-bb9c21493cd9",
    "type": "input_audio_buffer.speech_started",
    "meta": {
        "session_id": "test_trace_1766470129914296764",
        "timestamp": 1766470145337
    },
    "audio_start_ms": 15240,
    "item_id": "item_26cbd6a7-16e8-44c9-b6b4-d4d3b3c87b41"
}
```

### 语音结束（input\_audio\_buffer.speech\_stopped）

仅在开启 `server_vad` 时返回，表示服务端检测到语音结束。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "406d719a-3392-4ca4-88b3-9f12d8189b74",
    "type": "input_audio_buffer.speech_stopped",
    "meta": {
        "session_id": "test_trace_1766470129914296764",
        "timestamp": 1766470143512
    },
    "audio_start_ms": 13480,
    "item_id": "item_8228b4a6-f127-4a60-8f33-20fcb7d9ff7d"
}
```

### 缓冲区提交确认（input\_audio\_buffer.committed）

确认音频缓冲区已提交。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "event_id": "event_xxx",
  "type": "input_audio_buffer.committed",
  "meta": {
    "session_id": "sess_xxx",
    "timestamp": 1642694400000
  },
  "item_id": "item_xxx",
  "previous_item_id": "item_yyy"
}
```

### 对话项创建（conversation.item.created）

新的对话项（转录结果）已创建。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "event_id": "event_xxx",
  "type": "conversation.item.created",
  "meta": {
    "session_id": "sess_xxx",
    "timestamp": 1642694400000
  },
  "previous_item_id": "item_yyy",
  "item": {
    "id": "item_xxx",
    "object": "realtime.item",
    "type": "message",
    "status": "in_progress",
    "role": "user",
    "content": [
      {
        "type": "input_audio"
      }
    ]
  }
}
```

### 转录增量（conversation.item.input\_audio\_transcription.delta）

返回转录增量结果（流式输出）。

#### `stepaudio-2.5-asr-stream`（推荐）

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "event_id": "event_xxx",
  "type": "conversation.item.input_audio_transcription.delta",
  "meta": {
    "session_id": "sess_xxx",
    "timestamp": 1642694400000
  },
  "item_id": "item_xxx",
  "content_index": 0,
  "text": "你好请问有什么可以帮助您的",
  "stash": "退款",
  "words": [
    { "word": "你", "start": 0.00, "end": 0.20, "final": true },
    { "word": "好", "start": 0.20, "end": 0.45, "final": true },
    { "word": "退", "start": 1.80, "end": 1.95, "final": false },
    { "word": "款", "start": 1.95, "end": 2.10, "final": false }
  ]
}
```

* `item_id` `string`\
  对话项 ID。
* `content_index` `int`\
  内容索引。
* `text` `string`\
  截止当前的累计全量文本（含对前文的纠错）。客户端应整体替换展示，不要再追加拼接。
* `stash` `string`\
  可纠错的尾部文本（末尾若干字，后续可能被改写）。建议与 `text` 区分样式展示。
* `words` `list`\
  逐字时间数组，元素为 `{ "word", "start", "end", "final" }`。`start` / `end` 单位为秒（float）；`final=false` 表示该字在 `stash` 区、时间为临时估计。

#### `step-asr-1.1-stream`（逐步废弃）

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "event_id": "event_xxx",
  "type": "conversation.item.input_audio_transcription.delta",
  "meta": {
    "session_id": "sess_xxx",
    "timestamp": 1642694400000
  },
  "item_id": "item_xxx",
  "content_index": 0,
  "text": "你好",
  "start_time": 0,
  "end_time": 500
}
```

* `item_id` `string`\
  对话项 ID。
* `content_index` `int`\
  内容索引。
* `text` `string`\
  增量转录文本。
* `start_time` `int64`\
  开始时间（毫秒）。
* `end_time` `int64`\
  结束时间（毫秒）。

### 转录完成（conversation.item.input\_audio\_transcription.completed）

返回完整转录结果。

#### `stepaudio-2.5-asr-stream`（推荐）

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "event_id": "event_xxx",
  "type": "conversation.item.input_audio_transcription.completed",
  "meta": {
    "session_id": "sess_xxx",
    "timestamp": 1642694400000
  },
  "item_id": "item_xxx",
  "content_index": 0,
  "transcript": "你好，世界",
  "words": [
    { "word": "你", "start": 0.00, "end": 0.20, "final": true },
    { "word": "好", "start": 0.20, "end": 0.45, "final": true }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 10,
    "total_tokens": 10
  }
}
```

* `item_id` `string`\
  对话项 ID。
* `content_index` `int`\
  内容索引。
* `transcript` `string`\
  完整转录文本。
* `words` `list`\
  该段全部逐字时间，结构同 `delta`；此处 `final` 均为 `true`。开启 `enable_timestamp_align=true` 后为精确字级时间戳。
* `usage` `object`\
  使用统计信息。

#### `step-asr-1.1-stream`（逐步废弃）

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "event_id": "event_xxx",
  "type": "conversation.item.input_audio_transcription.completed",
  "meta": {
    "session_id": "sess_xxx",
    "timestamp": 1642694400000
  },
  "item_id": "item_xxx",
  "content_index": 0,
  "transcript": "你好，世界",
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 10,
    "total_tokens": 10
  }
}
```

* `item_id` `string`\
  对话项 ID。
* `content_index` `int`\
  内容索引。
* `transcript` `string`\
  完整转录文本。
* `usage` `object`\
  使用统计信息。

### 错误消息（error）

返回错误信息。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "event_id": "event_xxx",
  "type": "error",
  "meta": {
    "session_id": "sess_xxx",
    "timestamp": 1642694400000
  },
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_value",
    "message": "错误描述",
    "param": "audio",
    "event_id": "event_xxx"
  }
}
```

错误类型：

| 类型 | 描述 |
| - | - |
| `invalid_request_error` | 请求参数错误 |
| `internal_error` | 服务器内部错误 |
| `risk` | 内容安全风险 |

错误码：

| 错误码 | 描述 |
| - | - |
| `invalid_value` | 无效参数值 |
| `missing_param` | 缺少必需参数 |
| `internal_error` | 内部错误 |
| `max_idle_timeout` | 空闲超时 |
| `pong_timeout` | 心跳超时 |
| `risk_blocked` | 内容被拦截 |

## 故障排除

* 连接失败：检查服务是否可达、地址与鉴权是否正确。
* 音频无识别结果：确认音频格式、编码与质量。
* 识别准确性低：尝试使用 `prompt` 提示词或更换模型。
* 延迟过高：减小音频分块大小。

完整错误码参见 [错误码](/docs/zh/api-reference/error-codes)。


# 语音合成
Source: https://platform.stepfun.com/docs/zh/api-reference/audio/create-audio



调用 TTS 模型将文本合成为语音，返回音频文件。

## 请求地址

`POST https://api.stepfun.com/v1/audio/speech`

> [!NOTE]
>
> Step Plan 场景请使用 `POST https://api.stepfun.com/step_plan/v1/audio/speech`

## 请求参数

* `model` `string` ***required***\
  需要使用的模型名称，当前支持 `stepaudio-3-tts`、`stepaudio-2.5-tts`、`step-tts-2` 和 `step-tts-mini`。

  > [!NOTE]
  >
  > `step-tts-vivid` 模型名称不再推荐使用，但历史用户请求仍会继续支持。

* `input` `string` ***required***\
  要生成的文本，最大长度为 1000 个字符。在使用 `stepaudio-2.5-tts`、`stepaudio-3-tts` 时，括号 `()` 内的内容将作为指令处理，默认不发音；如需发音，请勿使用括号包裹。

* `voice` `string` ***required***\
  生成时使用的音色信息，支持[官方音色](/docs/zh/guides/developer/tts#官方音色清单)和开发者自生成音色。

* `response_format` `string` ***optional***\
  返回的音频格式，支持 `wav`、`mp3`、`flac`、`opus`、`pcm`，默认为 `mp3`。

* `speed` `float` ***optional***\
  语速，取值范围为 0.5\~2，默认值 1.0。0.5 表示 0.5 倍速。

* `volume` `float` ***optional***\
  音量，取值范围为 0.1\~2.0，默认值 1.0。0.1 表示缩小至 10% 音量；2.0 表示扩大至 200% 音量。

* `text_normalization` `string` ***optional***\
  文本归一化（Text Normalization）策略，可选值为 `standard` 和 `enhanced`，默认值为 `standard`。缺省（不传该参数）时按 `standard` 处理，与原有行为保持一致。
  * `standard`：标准归一化，适合实时对话等对时延敏感的场景。
  * `enhanced`：增强归一化，对数字、单位、英文、符号等的读法做更充分的处理，适合长文播报、正式播报等更看重合成效果的场景。

* `voice_label` `object` ***optional***\
  音色标签，使用自定义音色时需要传入。language、emotion 和 style 三个字段同一时间只能有一个有值，暂不支持多个组合。
  * `language` `string` ***optional***\
    语言，支持 `粤语`、`四川话`、`日语` 三个选项。
  * `emotion` `string` ***optional***\
    情绪，支持 `高兴`、`生气` 等最多 11 个选项， 不同模型的支持情况可参考[音色标签](/docs/zh/guides/developer/tts#音色标签)
  * `style` `string` ***optional***\
    支持最多17种语速或演绎风格，不同模型的支持情况可参考[音色标签](/docs/zh/guides/developer/tts#音色标签)

> [!WARNING]
>
> 注意：`stepaudio-2.5-tts`、`stepaudio-3-tts` 模型不支持该字段，若传入 `voice_label` 参数会报错。若使用上述模型，请直接使用 `instruction` 字段或文本内的 `()` 提示词控制情绪与风格。其他模型的支持情况可参考[音色标签](/docs/zh/guides/developer/tts#音色标签)。

* `instruction` `string` ***optional***\
  全局自然语言指导，用于设定整段音频的全局情绪基调、角色人设等。仅在使用 `stepaudio-2.5-tts`、`stepaudio-3-tts` 模型时生效；`stepaudio-2.5-tts` 最大支持 200 个字符，`stepaudio-3-tts` 最大支持 500 个字符。

* `sample_rate` `integer` ***optional*** \
  采样率，支持 8000、16000、22050、24000、48000 五个选项。默认值为 24000。采样率越高，音质越好，但文件体积也会更大。其中 48000 为最近几次迭代新增的采样率。

* `pronunciation_map` `object array` ***optional*** \
  &#x20;定义某个文字或符号注音或发音替换规则，在中文文本中，声调用数字表示：一声为1，二声为2，三声为3，四声为4，轻声为5。
  * `tone`  `string`  ***required*** \
    &#x20;具体发音映射规则，以“/”隔开，示例：`["绯闻/fei1闻","扁舟/偏舟","嫉妒/ji2妒"]`

* `stream_format` `string` ***optional*** \
  &#x20;流式返回，默认为返回语音，支持值 `sse` 和 `audio`,默认为 `audio`。当传入 `sse` 时，音频将会以 SSE 的方式返回，数据包格式如下：

  ```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  data: {"type":"speech.audio.delta","audio":"<BASE64 编码的音频片段>"}

  data: {"type":"speech.audio.delta","audio":"<BASE64 编码的音频片段>"}

  data: {"type":"speech.audio.done","audio":""}

  data: [DONE]
  ```

  事件类型说明：

  * `speech.audio.delta`：音频数据分片，`audio` 字段为该分片的 BASE64 编码二进制，拼接所有分片即为完整音频
  * `speech.audio.done`：生成完成，`audio` 为空字符串
  * `speech.audio.error`：生成过程中出错

* `markdown_filter` `bool` ***optional*** \
  &#x20;是否启用 Markdown 过滤。

* `return_url` `bool` ***optional*** \
  &#x20;仅对非流式生效，是否以 URL 而不是二进制流的形式返回，URL 12 小时内有效。

* `timestamp` `bool` ***optional*** \
  &#x20;词级时间戳（字幕）开关，置为 `true` 开启。开启后，服务端会返回每个切句的逐词时间轴（毫秒），可用于字幕高亮、卡拉 OK 式跟读、音画对齐等场景。字幕按两种模式投递：非流式需同时设置 `return_url=true`，字幕随文件 URL 一起返回；流式需设置 `stream_format="sse"`，字幕以 `response.subtitle` 事件随音频帧下发。两种模式的响应结构见[请求响应](#请求响应)。

  > [!WARNING]
  >
  > 开启 `timestamp` 时，必须满足 `return_url=true` 或 `stream_format="sse"` 之一。否则（如 `stream_format="audio"` 的裸音频流，或非流式但未设置 `return_url`）无法承载字幕，请求返回 HTTP 400：`timestamp requires return_url=true or stream_format=sse`。

## 请求响应

默认返回合成的音频文件（二进制流）。

开启 `timestamp` 后，服务端会额外返回每个切句的逐词时间戳（字幕），按投递模式分为两种。词级时间戳的 `start_time` / `end_time` 均已累加前序切句时长，可直接用于整段音频定位；服务端会自动按长度对文本切句，较长的文本会被切分为多个切句、每个切句对应一条字幕。

### 非流式 + 文件 URL（`timestamp=true` + `return_url=true`）

响应为 JSON，在 `data` 中新增 `subtitles` 数组，每个切句一条：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "created": 1782963404,
  "data": {
    "url": "https://.../xxxx.mp3",
    "subtitles": [
      {
        "text": "今天天气真好，我们出去玩吧！",
        "request_id": "c71567b716871b26176d305aab6a2a7e-0",
        "items": [
          { "text": "今", "start_time": 0, "end_time": 240 },
          { "text": "天", "start_time": 240, "end_time": 400 },
          { "text": "天", "start_time": 400, "end_time": 560 },
          { "text": "气", "start_time": 560, "end_time": 640 },
          { "text": "真", "start_time": 640, "end_time": 880 },
          { "text": "好，", "start_time": 880, "end_time": 1120 },
          { "text": "我", "start_time": 1840, "end_time": 2000 },
          { "text": "们", "start_time": 2000, "end_time": 2080 },
          { "text": "出", "start_time": 2080, "end_time": 2240 },
          { "text": "去", "start_time": 2240, "end_time": 2320 },
          { "text": "玩", "start_time": 2320, "end_time": 2560 },
          { "text": "吧！", "start_time": 2560, "end_time": 2800 }
        ],
        "timestamp": 1782963404434
      },
      {
        "text": "你想去公园还是去看电影呢？",
        "request_id": "c71567b716871b26176d305aab6a2a7e-1",
        "items": [
          { "text": "你", "start_time": 3440, "end_time": 3600 },
          { "text": "想", "start_time": 3600, "end_time": 3760 },
          { "text": "去", "start_time": 3760, "end_time": 3840 },
          { "text": "公", "start_time": 3840, "end_time": 4080 },
          { "text": "园", "start_time": 4080, "end_time": 4480 },
          { "text": "还", "start_time": 4640, "end_time": 4800 },
          { "text": "是", "start_time": 4800, "end_time": 4960 },
          { "text": "去", "start_time": 4960, "end_time": 5040 },
          { "text": "看", "start_time": 5040, "end_time": 5280 },
          { "text": "电", "start_time": 5280, "end_time": 5440 },
          { "text": "影", "start_time": 5440, "end_time": 5680 },
          { "text": "呢？", "start_time": 5680, "end_time": 5920 }
        ],
        "timestamp": 1782963404528
      }
    ]
  }
}
```

* `created` `int`\
  响应生成时间，Unix 时间戳，单位秒。
* `data.url` `string`\
  合成音频文件的下载 URL。
* `data.subtitles` `array`\
  字幕列表，每个切句一条；仅在 `timestamp=true` + `return_url=true` 时返回。

  * `text` `string`\
    切句文本。
  * `request_id` `string`\
    切句 ID。
  * `timestamp` `int64`\
    该条字幕的生成时间，单位毫秒。
  * `items` `array`\
    词级时间戳列表（对齐失败时可能为空）。

    * `text` `string`\
      分词文本。
    * `start_time` `int64`\
      词起始时间，单位毫秒，已累加前序切句时长。
    * `end_time` `int64`\
      词结束时间，单位毫秒，已累加前序切句时长。

### 流式 SSE（`timestamp=true` + `stream_format="sse"`）

在 SSE 流中，除音频帧 `speech.audio.delta` 外新增 `response.subtitle` 事件。每个切句对齐完成后下发一条，与音频帧在同一条流中交织下发，且所有字幕事件都会在 `speech.audio.done` 之前下发完毕：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
data: {"type":"speech.audio.delta","audio":"<BASE64 音频分片>"}

data: {"type":"response.subtitle","event_id":"...","data":{ ... }}

data: {"type":"speech.audio.delta","audio":"<BASE64 音频分片>"}

data: {"type":"speech.audio.done","audio":""}

data: [DONE]
```

其中 `response.subtitle` 事件结构如下，`data` 与非流式 `subtitles[]` 的单个元素一致：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "type": "response.subtitle",
  "event_id": "019f20e6858d73b5ad6da2f82af08ea5",
  "data": {
    "text": "今天天气真好，我们出去玩吧！",
    "request_id": "2b00a22c81e3c7f8f2a6378ac040df6f.019f20e6819a7aaab0d03ca8dc725e03",
    "items": [
      { "text": "今", "start_time": 0, "end_time": 160 },
      { "text": "天", "start_time": 160, "end_time": 320 },
      { "text": "天", "start_time": 320, "end_time": 480 },
      { "text": "气", "start_time": 480, "end_time": 560 },
      { "text": "真", "start_time": 560, "end_time": 720 },
      { "text": "好，", "start_time": 720, "end_time": 1120 },
      { "text": "我", "start_time": 1440, "end_time": 1520 },
      { "text": "们", "start_time": 1520, "end_time": 1680 },
      { "text": "出", "start_time": 1680, "end_time": 1760 },
      { "text": "去", "start_time": 1760, "end_time": 1920 },
      { "text": "玩", "start_time": 1920, "end_time": 2080 },
      { "text": "吧！", "start_time": 2080, "end_time": 2320 }
    ],
    "timestamp": 1782963406221
  }
}
```

* `type` `string`\
  事件类型，固定为 `response.subtitle`。
* `event_id` `string`\
  字幕事件 ID。
* `data` `object`\
  字幕内容，结构与非流式 `subtitles[]` 的单个元素一致（`text` / `request_id` / `items[]` / `timestamp`）。

## 示例

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import os
from pathlib import Path
from openai import OpenAI

speech_file_path = Path(__file__).parent / "step-tts.mp3"

client = OpenAI(
    api_key=os.environ["STEPFUN_API_KEY"],
    base_url="https://api.stepfun.com/v1"
)
with client.audio.speech.with_streaming_response.create(
    model="step-tts-mini",
    voice="cixingnansheng",
    input="智能阶跃，十倍每个人的可能.",
    extra_body={
        "volume": 1.0,  # volume 在拓展参数里
        # 文本归一化：standard / enhanced，默认 standard
        "text_normalization": "standard",
        # voice_label 的 language / emotion / style 同一时间只能设其中一个
        "voice_label": {
            "emotion": "高兴"
        },
        "pronunciation_map": {
            "tone": [
                "阿胶/e1胶",
                "扁舟/偏舟",
                "LOL/laugh out loudly"
            ]
        }
    }
) as response:
    response.stream_to_file(speech_file_path)
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";
import fs from "fs";
import path from "path";

const STEP_API_MODEL = "step-tts-mini";

const openai = new OpenAI({
    apiKey: process.env.STEPFUN_API_KEY,
    baseURL: "https://api.stepfun.com/v1"
});

async function main() {
    const speechFile = path.resolve("./speech.mp3");
    const mp3 = await openai.audio.speech.create({
        model: STEP_API_MODEL,
        voice: "cixingnansheng",
        input: "智能阶跃，十倍每个人的可能.",
        extra_body: {
            volume: 2.0, // volume 在拓展参数里
            // 文本归一化：standard / enhanced，默认 standard
            text_normalization: "standard",
            // voice_label 的 language / emotion / style 同一时间只能设其中一个
            voice_label: {
                emotion: "高兴"
            },
            pronunciation_map: {
                tone: [
                    "阿胶/e1胶",
                    "扁舟/偏舟",
                    "LOL/laugh out loudly"
                ]
            }
        }
    });
    console.log(speechFile);
    const buffer = Buffer.from(await mp3.arrayBuffer());
    await fs.promises.writeFile(speechFile, buffer);
}

main();
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl --location 'https://api.stepfun.com/v1/audio/speech' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $STEPFUN_API_KEY" \
  --data '{
    "model": "stepaudio-2.5-tts",
    "input": "2025 年第 4 季度营收同比增长 18.6%，约合 12.3 亿元。",
    "voice": "cixingnansheng",
    "text_normalization": "enhanced"
  }' \
  --output "step.mp3"
```

**StepAudio 2.5 TTS (python)**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import os
from pathlib import Path
from openai import OpenAI

speech_file_path = Path(__file__).parent / "step-tts.mp3"

client = OpenAI(
    api_key=os.environ["STEPFUN_API_KEY"],
    base_url="https://api.stepfun.com/v1"
)
with client.audio.speech.with_streaming_response.create(
    model="stepaudio-2.5-tts",
    voice="cixingnansheng",
    # 长度需 <=1000 字符；括号 () 内作为指令处理不发音，需发音文本请勿加括号
    input="（冷笑）你以为我们阶跃星辰北京公司的技术是开玩笑的吗！",
    extra_body={
        "volume": 1.0,  # volume 在拓展参数里
        # 文本归一化策略：standard / enhanced，默认 standard；enhanced 适合播报等更看重合成效果的场景
        "text_normalization": "enhanced",
        # 全局情绪指令，最长 200 字符
        "instruction": "语气极其愤怒，压迫感强，语速偏快",
        "pronunciation_map": {
            "tone": [
                "阿胶/e1胶",
                "扁舟/偏舟",
                "LOL/laugh out loudly"
            ]
        }
    }
) as response:
    response.stream_to_file(speech_file_path)
```

**字幕 · 非流式 (Python)**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import os
import requests

url = "https://api.stepfun.com/v1/audio/speech"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['STEPFUN_API_KEY']}"
}
payload = {
    "model": "step-tts-mini",
    "input": "今天天气真好。我们出去玩吧。",
    "voice": "cixingnansheng",
    "response_format": "mp3",
    "sample_rate": 24000,
    # 开启字幕；非流式需同时设置 return_url=true，字幕随文件 URL 返回
    "return_url": True,
    "timestamp": True
}

result = requests.post(url, headers=headers, json=payload).json()

# 音频文件下载地址
print("音频地址:", result["data"]["url"])

# 逐句、逐词时间戳
for subtitle in result["data"]["subtitles"]:
    print(f"\n切句: {subtitle['text']}")
    for item in subtitle["items"]:
        print(f"  {item['text']}: {item['start_time']}ms - {item['end_time']}ms")
```

**字幕 · 流式 SSE (Python)**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import os
import json
import requests

url = "https://api.stepfun.com/v1/audio/speech"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['STEPFUN_API_KEY']}"
}
payload = {
    "model": "step-tts-mini",
    "input": "今天天气真好。我们出去玩吧。",
    "voice": "cixingnansheng",
    "response_format": "mp3",
    "sample_rate": 24000,
    # 开启字幕；流式需设置 stream_format="sse"，字幕以 response.subtitle 事件下发
    "stream_format": "sse",
    "timestamp": True
}

resp = requests.post(url, headers=headers, json=payload, stream=True)

audio_chunks = []
for line in resp.iter_lines():
    if not line:
        continue
    line = line.decode("utf-8")
    if not line.startswith("data: "):
        continue
    data_str = line[6:]
    if data_str == "[DONE]":
        break
    event = json.loads(data_str)

    if event["type"] == "speech.audio.delta":
        # 音频分片：BASE64，拼接后即完整音频
        audio_chunks.append(event["audio"])
    elif event["type"] == "response.subtitle":
        # 字幕事件：该切句的逐词时间戳
        data = event["data"]
        print(f"字幕: {data['text']}")
        for item in data["items"]:
            print(f"  {item['text']}: {item['start_time']}ms - {item['end_time']}ms")
    elif event["type"] == "speech.audio.done":
        print("音频生成完成")
```


# 复刻音色
Source: https://platform.stepfun.com/docs/zh/api-reference/audio/create-voice



复刻音色，本 API 可以基于之前上传的 WAV、MP3文件，复制一个新的音色，用于 [TTS 生成音频](/docs/zh/api-reference/audio/create-audio)，或者用于 [Realtime 实时语音对话](/docs/zh/guides/developer/realtime)。

### 请求地址

`POST https://api.stepfun.com/v1/audio/voices`

> [!NOTE]
>
> Step Plan 场景请使用 `POST https://api.stepfun.com/step_plan/v1/audio/voices`

### 请求参数

* `model` `string` ***required***\
  &#x20;需要使用的模型名称，可选项有 `stepaudio-2.5-tts`、`step-tts-2`、`step-tts-mini`。

* `text` `string` **optional**\
  音频源文件对应的文本内容，如不传递，则调用系统 ASR 进行解析；为保证效果，建议传入。

* `file_id` `string` ***required*** \
  &#x20;用于复刻音色的音频源文件的 File ID。File ID 可以通过 [上传文件](/docs/zh/api-reference/files/create)
  获取，上传时，purpose 必须为 storage，支持文件格式为 mp3, wav。音频的时长范围应在 5 \~ 10 秒内;

### 请求响应

* `id` `string`\
  &#x20;音色 ID，可用于后续的音频生成。

* `object` `string`\
  &#x20;文件类型，固定为 audio.voice

* `duplicated` `boolean`\
  &#x20;是否重复请求。如果用户二次消费，则新增此字段，告诉用户已经创建过了。

### 示例

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -L 'https://api.stepfun.com/v1/audio/voices' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $STEP_API_KEY" \
-d '{
    "file_id":"file-Ckyl3cV09A",
    "model":"step-tts-mini",
    "text":"智能阶跃，十倍每一个人的可能"
}'
```


# 音频生成
Source: https://platform.stepfun.com/docs/zh/api-reference/audio/generate



基于文本描述统一生成人声、音效、环境音和背景音乐等多种声音要素。

## 服务地址

`POST https://api.stepfun.com/v1/audio/generate`

## 请求头

* `Content-Type` `string` ***required***\
  固定为 `application/json`。
* `Authorization` `string` ***required***\
  认证令牌，格式为 `Bearer $STEP_API_KEY`。

## 请求参数

* `model` `string` ***required***\
  模型名称，当前支持 `stepaudio-3-gen-preview`。

* `task` `string` ***required***\
  任务类型，当前仅支持 `text_to_audio`：通过自然语言描述设计音色，生成人声、音效、背景音乐等多种声音要素。使用该任务时，`scripts` 或 `instruction` 至少必填其一，`roles` 选填。

* `roles` `array` ***optional***\
  生成时使用的角色与音色描述，所有 `name` 和 `description` 合计最多 500 个字符。

  * `name` `string` ***optional***\
    自定义角色或音色名称，例如“主唱”。
  * `description` `string` ***optional***\
    自定义角色或音色描述，例如“二十多岁的青年男性，嗓音略带沙哑，演唱时气息饱满”。`name` 与 `description` 需要同时填写或同时留空。

* `scripts` `array` ***optional***\
  要生成的台词、音效或背景音乐描述，合计最多 1000 个字符。台词通过 `speaker` 指定说话人，并可用 `()` 描述说话的语气、风格、情绪等；音效和背景音乐描述用 `[]` 包裹，可不传 `speaker`。

  * `speaker` `string` ***optional***\
    台词对应的 `roles.name`。纯音效或 BGM 描述可以不传。
  * `text` `string` ***required***\
    台词、音效或 BGM 描述。

* `instruction` `string` ***optional***\
  全局自然语言指导，用于设定环境、BGM 和情绪基调，最多 500 个字符。

* `response_format` `string` ***optional***\
  返回音频格式，支持 `wav`、`mp3`、`flac`、`opus` 和 `pcm`。

* `speed` `number` ***optional***\
  语速，范围为 0.5～2。

* `volume` `number` ***optional***\
  音量，范围为 0.1～2.0。

* `sample_rate` `integer` ***optional***\
  采样率，支持 8000、16000、22050、24000 和 48000。

* `pronunciation_map` `object` ***optional***\
  发音替换规则。

* `text_normalization` `string` ***optional***\
  文本归一化策略，支持 `standard` 和 `enhanced`。

* `stream_format` `string` ***optional***\
  返回模式，默认为 `audio`：`audio` 直接返回生成的音频，`sse` 通过 Server-Sent Events 持续返回 Base64 编码的音频分片。

* `return_url` `boolean` ***optional***\
  是否返回音频 URL。

> [!NOTE]
>
> 使用官方音色或复刻音色合成的参考音色任务（`reference_to_audio`）暂未开放，后续支持后会在本页补充。

## 请求示例

### 音频生成

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl --location 'https://api.stepfun.com/v1/audio/generate' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer '"$STEP_API_KEY" \
  --data '{
    "model": "stepaudio-3-gen-preview",
    "task": "text_to_audio",
    "roles": [
      { "name": "地勤", "description": "三十岁上下的男性，声音干练利落，语速快，带着停机坪作业的专注，需盖过引擎噪音而略提高音量" },
      { "name": "机长", "description": "中年男性，声音通过无线电传来，带航空通讯特有的电子压缩与背景电流，沉稳职业" },
      { "name": "塔台", "description": "女性，声音同样经无线电传输，字正腔圆略带失真，冷静下达指令" }
    ],
    "scripts": [
      { "text": "[客机APU持续的高频呜鸣，混着牵引车低沉的引擎声]" },
      { "speaker": "地勤", "text": "（对着头戴通话器，略提高音量盖过噪音）左发进气口检查完毕，轮挡已撤，可以推出。" },
      { "speaker": "机长", "text": "（无线电话音，压缩失真）收到，请求后推许可，目视地面信号。" },
      { "text": "[无线电“嗤”的一声接通，传来带电流的话音]" },
      { "speaker": "塔台", "text": "（无线电话音，冷静）同意后推，跑道两三右，地面风零九零三节，祝一路顺风。" },
      { "speaker": "地勤", "text": "（挥动荧光棒指引，大声回应）明白，牵引车开始后推，注意左侧翼尖间距！" }
    ],
    "instruction": "夜间机场停机坪，一架客机正在做起飞前的最后地面检查",
    "response_format": "mp3"
  }'
```

## 限制与兼容性

* `instruction` 和 `roles` 字段最多 500 字符，`scripts` 字段最多 1000 字符。
* `stepaudio-3-gen-preview` 不支持 `voice`、`voice_label`、`timestamp` 参数。
* 超出长度限制或传入不支持的参数时，接口返回 HTTP 400。


# 查询已复刻音色
Source: https://platform.stepfun.com/docs/zh/api-reference/audio/list-voice



本 API 可用于查询当前用户下的复刻音色。官方音色可参看[支持音色](/docs/zh/guides/developer/tts#官方音色清单)

### 请求地址

`GET https://api.stepfun.com/v1/audio/voices`

### 请求参数

* `limit` `string` ***optional***\
  分页的数量，默认 20，最大 100 ，最小 1。默认值为 20。

* `order` `string` ***optional***\
  基于创建时间的返回顺序，支持参数 `asc` 和 `desc`，默认为 `desc`。\
  &#x20;`asc`：升序，创建早的音色先出现\
  &#x20;`desc` :降序，创建晚的音色先出现

* `before` `string` ***optional***\
  &#x20;指针 ID（音色 ID），可与 limit / order 联合使用

* `after` `string` ***optional***\
  &#x20;指针 ID（音色 ID），可与 limit / order 联合使用。

### 请求响应

* `object` `string`\
  固定为 `list`

* `data` `array`\
  &#x20;音色 ID 的列表
  * `id` `int` \
    &#x20;音色 ID，可用于后续的音频生成
  * `file_id` `int`\
    &#x20;用于复刻音色的音频源文件的 File ID
  * `created_at` `int`\
    &#x20;音色创建的时间

* `has_more` `boolean`\
  &#x20;是否有下一页

* `first_id` `string`\
  &#x20;第一个音色的 ID

* `last_id` `string`\
  &#x20;最后一个音色的 ID

### 示例

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl --location 'https://api.stepfun.com/v1/audio/voices' \
  --header 'Authorization: Bearer YOUR_STEP_API_KEY'
```

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import requests

url = "https://api.stepfun.com/v1/audio/voices"

payload = {}
headers = {
    "Authorization": "Bearer YOUR_STEP_API_KEY"
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
```

**响应**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "object": "list",
  "data": [
    {
      "id": "voice-tone-FmBrMBqicC",
      "file_id": "file-FmBrMBqicC",
      "created_at": 1742374363
    }
  ],
  "has_more": false,
  "first_id": "voice-tone-FmBrMBqicC",
  "last_id": "voice-tone-FmBrMBqicC"
}
```


# 音乐生成
Source: https://platform.stepfun.com/docs/zh/api-reference/audio/music



文本生成音乐接口采用异步的“提交 + 查询”模式：先创建生成任务并获取 `task_id`，再轮询任务状态，直到任务进入 `SUCCESS` 或 `FAILED` 终态。

> [!NOTE]
>
> 音乐生成是自回归长任务，生成一首完整歌曲通常需要数十秒到数分钟。

## 服务地址

`POST https://api.stepfun.com/v1/audio/music`

## 能力范围

本次提供三个任务类型，覆盖四种用法：

| 用法 | `task` | 输入 | 输出 |
| :- | :- | :- | :- |
| 歌曲生成 | `text_to_music` | 风格描述 + 可选歌词 | 带人声的完整歌曲 |
| 纯器乐生成 | `text_to_music` + `instrumental=true` | 风格描述 | 无人声器乐 |
| 歌曲翻唱 / 风格切换 | `music_cover` | 参考歌曲 + 风格描述 + 歌词 | 跟随原曲旋律的翻唱 |
| 干声配乐 | `vocal_to_music` | 无伴奏干声 + 风格描述 + 歌词 | 保留输入音色的完整歌曲 |

`text_to_music` 未提供 `lyrics` 时，服务端会自动生成歌词。

## 通用约定

### 请求头

| Header | 必填 | 说明 |
| :- | :- | :- |
| `Authorization` | 是 | `Bearer $STEP_API_KEY` |
| `Content-Type` | 是 | `application/json; charset=utf-8` |

### 统一错误响应

所有非 2xx 响应采用以下结构：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "error": {
    "message": "错误描述",
    "type": "错误类型标识"
  }
}
```

客户端应根据 `error.type` 做程序化判断，不要匹配 `message` 文本。

响应同时返回 `x-should-retry` 头：

* 参数、鉴权和资源类错误（400 / 401 / 404）：`false`
* 速率限制和临时服务故障（429 / 500 / 503）：`true`
* 额度类 429 重试无效，仍需根据 `error.type` 单独处理。

音频输入字段使用原始文件字节的 Base64 字符串，不包含 `data:` 前缀。

## 提交音乐生成任务

`POST https://api.stepfun.com/v1/audio/music/submit`

### 请求参数

* `task` `string` ***required***\
  任务类型，支持 `text_to_music`、`music_cover` 和 `vocal_to_music`。
* `model_id` `string` ***required***\
  音乐模型标识，固定填 `stepaudio-3-music-preview`。
* `caption` `string` ***required***\
  曲风、人声、情绪、调式等风格描述。
* `lyrics` `string` ***optional***\
  歌词，支持歌曲结构标签。`music_cover` 和 `vocal_to_music` 必填；`text_to_music` 不传时由服务端自动写词。
* `instrumental` `boolean` ***optional***\
  是否生成纯器乐，默认 `false`，仅 `text_to_music` 支持。
* `song_audio` `string` ***optional***\
  完整参考歌曲的 Base64 编码，`music_cover` 必填。
* `vocal_audio` `string` ***optional***\
  无伴奏干声的 Base64 编码，`vocal_to_music` 必填。
* `response_format` `string` ***optional***\
  输出格式，支持 `wav`、`flac`、`opus`、`mp3` 和 `pcm`，默认 `wav`。
* `sample_rate` `integer` ***optional***\
  输出采样率，默认 `48000`；省略或传 `0` 时保持模型原生采样率。
* `bit_rate` `integer` ***optional***\
  MP3 / Opus 比特率，单位为 kbps。
* `lyrics_rewrite` `boolean` ***optional***\
  是否改写传入的歌词，默认 `false`。
* `disable_caption_rewrite` `boolean` ***optional***\
  是否跳过 `caption` 自动改写，默认 `false`。
* `max_tokens` `integer` ***optional***\
  生成 token 数上限，默认 `16000`。
* `temperature` `number` ***optional***\
  采样温度，默认 `0.85`，暂不支持 `0`。
* `top_k` `integer` ***optional***\
  采样参数，默认 `80`。
* `top_p` `number` ***optional***\
  采样参数，默认 `0.92`。
* `repetition_penalty` `number` ***optional***\
  重复惩罚，默认 `1.08`。

### 参数适用矩阵

| 参数 | `text_to_music` 歌曲 | `text_to_music` 器乐 | `music_cover` | `vocal_to_music` |
| :- | :- | :- | :- | :- |
| `caption` | 必填 | 必填 | 必填 | 必填 |
| `lyrics` | 可选，留空自动写词 | 禁止传 | 必填 | 必填 |
| `instrumental` | 省略或 `false` | 必须为 `true` | 不支持 | 不支持 |
| `song_audio` | 不使用 | 不使用 | 必填 | 不使用 |
| `vocal_audio` | 不使用 | 不使用 | 不使用 | 必填 |

### 参数说明

#### 器乐与歌词

`instrumental=true` 时不得同时传入 `lyrics`。歌词中的 `[Instrumental]` 仅表示局部器乐段，不能代替顶层的 `instrumental=true`。

#### 翻唱

`music_cover` 的旋律跟随参考歌曲，`caption` 控制风格、音色、编曲和情绪。建议传入与原曲演唱内容一致的歌词。

#### 干声配乐

`vocal_to_music` 的旋律主要跟随干声，并保留输入干声的人声音色。干声实际演唱内容需要是 `lyrics` 的子集或全集。

#### Caption 改写

服务端默认将 `caption` 改写为规范的英文 style prompt，并通过查询接口的 `rewritten_caption` 返回。

`disable_caption_rewrite=true` 不能与 `lyrics_rewrite=true` 同时使用；在非器乐 `text_to_music` 场景使用时，必须显式提供歌词。

#### 输出时长

输出时长由模型决定，无法通过参数精确控制。同一输入多次生成的时长可能不同，通常为 1～3 分钟。

### 歌词结构标签

歌词结构标签需要独占一行。

常用标签：

* `[Intro]`
* `[Verse 1]`
* `[Pre-Chorus]`
* `[Chorus 1]`
* `[Bridge]`
* `[Instrumental]`
* `[Hook]`
* `[Break]`
* `[Drop]`
* `[Ad-lib]`
* `[Outro]`

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[Verse 1]
青椒还沾着晨露
你挑的番茄滚到脚边

[Instrumental]

[Chorus 1]
初秋的菜场挤着人潮
你背影越走越渺小
```

### Caption 写法建议

`caption` 支持中文或英文，建议描述以下维度：

| 维度 | 示例 |
| :- | :- |
| 曲风 | lo-fi、R\&B、city pop、dance-pop |
| 人声 | 女声、男声、温暖、气声、颤音 |
| 律动 | 缓慢、中速、轻快、适合跳舞 |
| 音色质感 | 温暖、开阔、颗粒感、朦胧 |
| 情绪 | 怀旧、惆怅、振奋、有希望 |
| 调式 | B 小调、D 小调、C 大调 |

### 响应

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "task_id": "01959f5e-0f31-7a2b-9c4d-1234567890ab"
}
```

`task_id` 用于查询任务结果和问题排查。

### 错误码

| HTTP | `error.type` | 触发条件 |
| :- | :- | :- |
| 400 | `request_params_invalid` | JSON 非法、缺少必填字段、参数值或参数组合错误 |
| 401 | `not_allowed` | 鉴权令牌缺失或无效 |
| 402 | `insufficient_credit` | Credit 余额不足 |
| 404 | `model_invalid` | 模型 ID 错误或账号没有模型权限 |
| 429 | `rate_limited` | 请求速率或并发超过限制 |
| 429 | `project_credit_limit_exceeded` / `member_project_credit_limit_exceeded` | 项目或成员达到 Credit 上限 |
| 503 | `service_unavailable` | 服务负载过高或任务入队失败 |

内容审核可能在提交阶段同步返回 451，也可能在任务执行阶段以 `FAILED` + `error.stage=censor` 返回。

### 调用示例

**歌曲生成**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -X POST "https://api.stepfun.com/v1/audio/music/submit" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "task": "text_to_music",
    "model_id": "stepaudio-3-music-preview",
    "caption": "A soul and R&B song, female vocal, D minor, warm and nocturnal",
    "lyrics": "[Verse 1]\n...\n[Chorus 1]\n...",
    "response_format": "mp3"
  }'
```

**纯器乐**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -X POST "https://api.stepfun.com/v1/audio/music/submit" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "task": "text_to_music",
    "model_id": "stepaudio-3-music-preview",
    "instrumental": true,
    "caption": "流行风格古筝曲，穿插长笛和萧声，温暖辽阔",
    "response_format": "mp3"
  }'
```

**歌曲翻唱**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -X POST "https://api.stepfun.com/v1/audio/music/submit" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "task": "music_cover",
    "model_id": "stepaudio-3-music-preview",
    "caption": "Soul and R&B with funk influences, warm and breathy vocal",
    "lyrics": "[Verse 1]\n...",
    "song_audio": "<base64 of reference song>",
    "response_format": "mp3"
  }'
```

**干声配乐**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -X POST "https://api.stepfun.com/v1/audio/music/submit" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "task": "vocal_to_music",
    "model_id": "stepaudio-3-music-preview",
    "caption": "Vibrant dance-pop with uplifting R&B influences",
    "lyrics": "[Verse 1]\n...",
    "vocal_audio": "<base64 of dry vocal>",
    "response_format": "mp3"
  }'
```

## 查询任务结果

`POST https://api.stepfun.com/v1/audio/music/query`

建议每 5 秒轮询一次，直到 `status` 进入终态；成功后请及时保存音频。

### 请求参数

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "task_id": "01959f5e-0f31-7a2b-9c4d-1234567890ab"
}
```

| 参数 | 类型 | 必填 | 说明 |
| :- | :- | :- | :- |
| `task_id` | string | 是 | 提交接口返回的任务 ID |

### 任务状态

| 状态 | 说明 |
| :- | :- |
| `PENDING` | 任务已入队 |
| `RUNNING` | 任务正在处理 |
| `SUCCESS` | 生成完成，可以获取音频 |
| `FAILED` | 生成失败，不会回退 |

### 进行中响应

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "status": "RUNNING",
  "task": "text_to_music",
  "caption": "A soul and R&B song, female vocal, D minor",
  "lyrics": "[Verse 1]\n...",
  "response_format": "mp3",
  "sample_rate": 48000
}
```

### 成功响应

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "status": "SUCCESS",
  "task": "text_to_music",
  "caption": "A soul and R&B song, female vocal, D minor",
  "lyrics": "[Verse 1]\n...",
  "response_format": "mp3",
  "sample_rate": 48000,
  "audio": "<base64-encoded generated audio>",
  "rewritten_caption": "A soul and R&B song, female vocal, D minor, warm and nocturnal",
  "rewritten_lyrics": "[Verse 1]\n...\n[Chorus 1]\n..."
}
```

### 失败响应

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "status": "FAILED",
  "task": "music_cover",
  "caption": "...",
  "lyrics": "...",
  "response_format": "mp3",
  "error": {
    "stage": "audio_transcode",
    "message": "unsupported audio format"
  }
}
```

`FAILED` 是业务终态，HTTP 状态码仍为 200。

### 响应字段

| 字段 | 类型 | 说明 |
| :- | :- | :- |
| `status` | string | `PENDING`、`RUNNING`、`SUCCESS`、`FAILED` |
| `task` | string | 提交时的任务类型 |
| `caption` | string | 提交时的风格描述 |
| `lyrics` | string | 提交或生成的歌词 |
| `response_format` | string | 输出格式 |
| `sample_rate` | integer | 输出采样率 |
| `audio` | string（Base64） | 生成音频，仅 `SUCCESS` 返回 |
| `rewritten_caption` | string | 服务端改写后的风格描述，仅 `SUCCESS` 返回 |
| `rewritten_lyrics` | string | 服务端生成或改写后的歌词，仅 `SUCCESS` 返回 |
| `error` | object | 失败原因，仅 `FAILED` 返回 |

### 失败阶段

| `error.stage` | 含义 | 建议处理 |
| :- | :- | :- |
| `audio_transcode` | 音频无法解码、转码或采样率非法 | 检查音频格式、文件和参数 |
| `no_speech_detected` | 干声中未检测到有效人声 | 更换清晰且空白较少的干声 |
| `censor` | 文本或音频被安全审核拦截 | 调整内容后重新提交 |
| `internal` | 服务端内部错误 | 稍后重试并保留 `task_id` |

### 查询错误码

| HTTP | `error.type` | 触发条件 |
| :- | :- | :- |
| 400 | `request_params_invalid` | 请求体非法或缺少 `task_id` |
| 401 | `not_allowed` | 鉴权 Header 缺失或无效 |
| 404 | `task_not_found` | 任务不存在或已超过保留期 |
| 429 | `rate_limited` | 查询过于频繁 |
| 503 | `service_unavailable` | 服务负载过高或结果读取失败 |

### 查询示例

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -X POST "https://api.stepfun.com/v1/audio/music/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "task_id": "01959f5e-0f31-7a2b-9c4d-1234567890ab"
  }'
```

## 音频与输出约束

| 项目 | 约束 |
| :- | :- |
| 输入编码 | 音频原始字节的 Base64，不含 `data:` 前缀 |
| 输入容器 | `wav`、`flac`、`opus`、`mp3` |
| 输出格式 | `wav`、`flac`、`opus`、`mp3`、`pcm` |
| 输出采样率 | 原生 48 kHz 立体声，支持服务端重采样 |

推荐使用 MP3 输出以降低响应体积。PCM 为无文件头裸流，需按 48 kHz、16 bit、立体声自行解析。

## 合规说明

生成内容对外分发、发布或用于商业用途时，调用方应根据适用法律法规添加人工智能生成内容标识。


# 获取官方音色详情
Source: https://platform.stepfun.com/docs/zh/api-reference/audio/system-voices



## 接口说明

本接口用于通过 API 获取对应模型的系统默认音色，支持查询指定模型下的所有系统音色，并返回每个音色的详细信息（名称、描述、推荐场景）。

如果将该接口提供给 agent，agent 可拿到当前全部官方音色和描述，并根据场景选择最适配的音色。

## 请求说明

### 请求方式

`GET`

### 请求路径

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/v1/audio/system_voices
```

### Query 参数

| 参数名 | 类型 | 是否必选 | 支持选项 | 说明 |
| - | - | - | - | - |
| model | string | 是 | `step-tts-2` | 指定要查询系统音色的模型，目前仅支持 `step-tts-2` |

### 请求示例

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
GET /v1/audio/system_voices?model=step-tts-2
```

## 返回说明

### 返回格式

`JSON`

### 返回参数说明

| 参数名 | 类型 | 说明 |
| - | - | - |
| voices | array\[string] | 系统音色 ID 列表，包含该模型下所有系统音色的唯一标识 |
| voices-details | object | 音色详细信息集合，key 为音色 ID，value 为该音色的具体详情 |
| voices-details.xxx.voice-name | string | 音色名称，部分音色可能为空字符串 |
| voices-details.xxx.voice-description | string | 音色描述，包含音色性别、音色特点等信息 |
| voices-details.xxx.recommended\_scene | string | 音色推荐使用场景，多个场景用顿号分隔 |

### 返回示例

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "voices": [
        "boyinnansheng",
        "cixingnansheng",
        "elegantgentle-female",
        "energeticconfident-female",
        "ganliannvsheng",
        "huolinvsheng",
        "jilingshaonv",
        "jingdiannvsheng",
        "lengyanyujie",
        "linjiajiejie",
        "linjiameimei",
        "lively-girl",
        "livelybreezy-female",
        "magnetic-voiced-male",
        "qingchunshaonv",
        "qingniandaxuesheng",
        "qinhenvsheng",
        "qinqienvsheng",
        "ruanmengnvsheng",
        "ruyananshi",
        "shenchennanyin",
        "shuangkuaijiejie",
        "shuangkuainansheng",
        "soft-spoken-gentleman",
        "tianmeinvsheng",
        "vibrant-youth",
        "wenjingxuejie",
        "wenrougongzi",
        "wenrounansheng",
        "wenrounvsheng",
        "wenroushunv",
        "yingwennansheng",
        "yingwennvsheng",
        "youyanvsheng",
        "yuanqinansheng",
        "yuanqishaonv",
        "zhengpaiqingnian",
        "zhixingjiejie",
        "zixinnansheng"
    ],
    "voices-details": {
        "cixingnansheng": {
            "voice-name": "磁性男声",
            "voice-description": "男，深情厚重，有感染力，霸总感",
            "recommended_scene": "有声书、情感陪伴"
        },
        "linjiameimei": {
            "voice-name": "邻家妹妹",
            "voice-description": "女，可爱亲和，稚气感",
            "recommended_scene": "视频配音、口播（解说、新闻）、语音助手"
        },
        "zhengpaiqingnian": {
            "voice-name": "正派青年",
            "voice-description": "男，音色具有感染力、说服力和亲和力，有激情和鼓动性",
            "recommended_scene": "营销"
        },
        "elegantgentle-female": {
            "voice-name": "气质温婉",
            "voice-description": "女，真诚温柔，亲和力强，给人安全感",
            "recommended_scene": "客服与业务办理、口播（解说、新闻）、教育与培训、情感陪伴"
        },
        "ruanmengnvsheng": {
            "voice-name": "软萌女声",
            "voice-description": "女，可爱、甜、嗲",
            "recommended_scene": "情感陪伴、语音助手、视频配音"
        },
        "yuanqinansheng": {
            "voice-name": "元气男声",
            "voice-description": "男，情绪饱满有活力",
            "recommended_scene": "有声书、口播（解说、新闻）"
        },
        "shuangkuaijiejie": {
            "voice-name": "爽快姐姐",
            "voice-description": "女，清澈有活力",
            "recommended_scene": "口播（解说、新闻）、语音助手"
        },
        "zixinnansheng": {
            "voice-name": "自信男声",
            "voice-description": "男，真诚亲和，有活力",
            "recommended_scene": "有声书、情感陪伴、教育与培训、营销"
        },
        "wenjingxuejie": {
            "voice-name": "文静学姐",
            "voice-description": "女，冷静沉稳，吐字清晰稳定",
            "recommended_scene": "口播（解说、新闻）、语音助手"
        },
        "qingchunshaonv": {
            "voice-name": "清纯少女",
            "voice-description": "女，温柔，轻盈有活力，亲和力强",
            "recommended_scene": "客服与业务办理、语音助手"
        },
        "livelybreezy-female": {
            "voice-name": "活力轻快",
            "voice-description": "女，音色具有感染力、说服力和亲和力，有活力",
            "recommended_scene": "情感陪伴、教育与培训、营销"
        },
        "ganliannvsheng": {
            "voice-name": "干练女声",
            "voice-description": "女，音色沉稳冷静、慢条斯理，专业感强",
            "recommended_scene": "客服与业务办理、语音助手"
        },
        "tianmeinvsheng": {
            "voice-name": "甜美女声",
            "voice-description": "女，甜美温柔，亲和力强",
            "recommended_scene": "情感陪伴、客服与业务办理"
        },
        "vibrant-youth": {
            "voice-name": "Vibrant Youth",
            "voice-description": "男，英文音色，温柔亲和",
            "recommended_scene": "有声书、视频配音、语音助手"
        },
        "ruyananshi": {
            "voice-name": "儒雅男士",
            "voice-description": "男，沉稳厚重，叙述感强，有亲和力、陪伴感",
            "recommended_scene": "有声书、情感陪伴、口播（解说、新闻）、语音助手"
        },
        "youyanvsheng": {
            "voice-name": "优雅女声",
            "voice-description": "女，成熟亲和，给人踏实感",
            "recommended_scene": "视频配音"
        },
        "jingdiannvsheng": {
            "voice-name": "经典女声",
            "voice-description": "女，语速较慢，真诚温柔",
            "recommended_scene": "客服与业务办理、情感陪伴"
        },
        "linjiajiejie": {
            "voice-name": "邻家姐姐",
            "voice-description": "女，有亲和力，邻家大姐姐的感觉，给人安全感",
            "recommended_scene": "口播（解说、新闻）、情感陪伴、语音助手、视频配音"
        },
        "energeticconfident-female": {
            "voice-name": "",
            "voice-description": "女，英文音色，有活力且自信",
            "recommended_scene": "客服与业务办理、语音助手"
        },
        "boyinnansheng": {
            "voice-name": "播音男声",
            "voice-description": "男，播音腔，中正平稳",
            "recommended_scene": "有声书、口播（解说、新闻）"
        },
        "yuanqishaonv": {
            "voice-name": "元气少女",
            "voice-description": "女，声线细腻，甜、嗲",
            "recommended_scene": "情感陪伴、语音助手"
        },
        "shuangkuainansheng": {
            "voice-name": "爽快男声",
            "voice-description": "男，音色沉稳冷静、慢条斯理，专业感强",
            "recommended_scene": "客服与业务办理、语音助手"
        },
        "qingniandaxuesheng": {
            "voice-name": "青年大学生",
            "voice-description": "男，沉稳厚实，播音专业感",
            "recommended_scene": "口播（解说、新闻）"
        },
        "zhixingjiejie": {
            "voice-name": "知性姐姐",
            "voice-description": "女，成熟沉稳，叙述有画面感",
            "recommended_scene": "视频配音、口播（解说、新闻）、语音助手"
        },
        "qinqienvsheng": {
            "voice-name": "亲切女声",
            "voice-description": "女，温柔带点甜美，亲和力强，邻家感",
            "recommended_scene": "口播（解说、新闻）、情感陪伴、语音助手"
        },
        "wenroushunv": {
            "voice-name": "温柔熟女",
            "voice-description": "女，成熟稳重，温柔有亲和力",
            "recommended_scene": "客服与业务办理、口播（解说、新闻）、教育与培训"
        },
        "qinhenvsheng": {
            "voice-name": "亲和女声",
            "voice-description": "女，冷静温柔、有亲和力",
            "recommended_scene": "客服与业务办理、语音助手"
        },
        "shenchennanyin": {
            "voice-name": "深沉男音",
            "voice-description": "男，有感情，代入感强，给人信心",
            "recommended_scene": "情感陪伴、有声书"
        },
        "huolinvsheng": {
            "voice-name": "活力女声",
            "voice-description": "女，轻盈有活力，亲和力强",
            "recommended_scene": "客服与业务办理、语音助手"
        },
        "wenrougongzi": {
            "voice-name": "温柔公子",
            "voice-description": "男，沉稳温柔，叙述感强",
            "recommended_scene": "情感陪伴、有声书"
        },
        "soft-spoken-gentleman": {
            "voice-name": "Soft-spoken Gentleman",
            "voice-description": "男，英文音色，沉稳温柔，给人安全感",
            "recommended_scene": "情感陪伴、有声书"
        },
        "lively-girl": {
            "voice-name": "Lively Girl",
            "voice-description": "女，英文音色，亲和感，有活力",
            "recommended_scene": "有声书、视频配音、语音助手"
        },
        "wenrounvsheng": {
            "voice-name": "温柔女声",
            "voice-description": "女，温柔甜美，叙述感强，有关怀感",
            "recommended_scene": "有声书、情感陪伴"
        },
        "wenrounansheng": {
            "voice-name": "温柔男声",
            "voice-description": "男，温柔亲和",
            "recommended_scene": "口播（解说、新闻）、情感陪伴、客服与业务办理、教育与培训"
        },
        "jilingshaonv": {
            "voice-name": "机灵少女",
            "voice-description": "女，声线细腻，有活力",
            "recommended_scene": "语音助手、口播（解说、新闻）"
        },
        "lengyanyujie": {
            "voice-name": "冷艳御姐",
            "voice-description": "女，播音感，专业不失亲和",
            "recommended_scene": "视频配音"
        },
        "magnetic-voiced-male": {
            "voice-name": "Magnetic-voiced Male",
            "voice-description": "男，英文音色，强烈的沉稳厚重感",
            "recommended_scene": "有声书、视频配音"
        }
    }
}
```

## 注意事项

* `voices` 数组中的音色 ID 与 `voices-details` 中的 key 一一对应，可通过音色 ID 查询对应详情。
* 推荐场景仅为参考，用户可根据实际需求选择合适的音色。


# 音频转写
Source: https://platform.stepfun.com/docs/zh/api-reference/audio/transcriptions



将上传的音频文件识别为文本，一次性返回完整结果，适合简单的整段转写场景。推荐使用模型 `stepaudio-2.5-asr`。

> [!NOTE]
>
> 如需分句与字 / 词级时间戳、双声道分轨、说话人识别等进阶能力，请使用 [音频文件识别](/docs/zh/api-reference/audio/asr)。

## 请求地址

`POST https://api.stepfun.com/v1/audio/transcriptions`

请求体为 `multipart/form-data`。

## 请求参数

* `model` `string` ***required***\
  模型名称，支持 `stepaudio-2.5-asr`、`step-asr`（旧模型名称）。
* `response_format` `string` ***required***\
  输出格式，支持 `json`、`text`。
* `file` `File` ***required***\
  待识别的音频文件，支持 `mp3`、`pcm`、`ogg`、`wav`，文件需小于 100MB。
* `hotwords` `string` ***optional***\
  热词列表，为可解析的 JSON 数组字符串，如 `["热词1", "热词2"]`。

## 返回

接口根据 `response_format` 返回对应格式的识别结果。

**json**

* `text` `string`\
  识别所得的完整文本。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{ "text": "测试录制音频" }
```

**text**

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
测试录制音频
```

## 示例

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -L 'https://api.stepfun.com/v1/audio/transcriptions' \
  -H "Authorization: Bearer $STEPFUN_API_KEY" \
  -F 'model="stepaudio-2.5-asr"' \
  -F 'response_format="json"' \
  -F 'file=@"sample.mp3"'
```


# 复刻试听
Source: https://platform.stepfun.com/docs/zh/api-reference/audio/voices-preview



复刻试听接口，本 API 可以基于用户上传的参考音频（WAV、MP3），生成对应的试听音频，用于快速验证音色效果。该接口**不会创建正式音色资产**，仅用于预览效果。

### 请求地址

`POST https://api.stepfun.com/v1/audio/voices/preview`

> [!NOTE]
>
> Step Plan 场景请使用 `POST https://api.stepfun.com/step_plan/v1/audio/voices/preview`

### 请求参数

* `model` `string` ***required*** \
  &#x20;复刻使用的模型，支持 `step-tts-2`、`step-tts-mini` 和 `stepaudio-2.5-tts`。

* `file_id` `string` ***required*** \
  &#x20;参考音频文件 ID。通过 [上传文件](/docs/zh/api-reference/files/create) 接口获取，上传时 purpose 必须为 storage。

* `text` `string` ***optional*** \
  &#x20;参考音频对应文本。不传则自动走 ASR 识别；为保证效果，建议传入。

* `sample_text` `string` ***required*** \
  &#x20;试听文本，长度建议限制在 50 字以内。

* `response_format` `string` ***optional*** \
  &#x20;返回的音频格式，支持 `wav`、`mp3`、`flac`、`opus`、`pcm`，默认为 `mp3` 格式。

* `speed` `float` ***optional*** \
  &#x20;语速，取值范围为 0.5\~2，默认值 1.0。0.5 表示 0.5 倍速。

* `volume` `float` ***optional*** \
  &#x20;音量，取值范围为 0.1\~2.0，默认值 1.0。0.1 表示缩小至 10% 音量；2.0 表示扩大至 200% 音量。

* `voice_label` `object` ***optional*** \
  &#x20;音色标签，使用自定义音色时需要传入。language、emotion 和 style 三个字段同时只能有一个字段有值，暂不支持多个组合。
  * `language` `string` ***optional***\
    &#x20;语言，支持 `粤语`、`四川话`、`日语` 三个选项。
  * `emotion` `string` ***optional***\
    &#x20;情绪，支持 `高兴`、`生气` 等最多 11 个选项，不同模型的支持情况可参考[音色标签](/docs/zh/guides/developer/tts#音色标签)。
  * `style` `string` ***optional***\
    &#x20;支持最多 17 种语速或演绎风格，不同模型的支持情况可参考[音色标签](/docs/zh/guides/developer/tts#音色标签)。

> [!WARNING]
>
> ⚠️ 注意：`stepaudio-2.5-tts` 模型不支持该字段，若传入 `voice_label` 参数会报错。若使用 `stepaudio-2.5-tts` 模型，请直接使用 `instruction` 字段或文本内的 `()` 提示词来控制情绪与风格。

* `instruction` `string` ***optional*** \
  &#x20;全局自然语言指导。仅在使用 `stepaudio-2.5-tts` 模型时生效，其他模型若传入该参数会报错。用于设定整段音频的全局情绪基调、角色人设等。最大长度限制为 200 个字符。

* `sample_rate` `integer` ***optional*** \
  &#x20;采样率，支持 8000、16000、22050、24000、48000 五个选项。默认值为 24000。采样率越高，音质越好，但文件体积也会更大。

* `pronunciation_map` `object array` ***optional*** \
  &#x20;定义某个文字或符号注音或发音替换规则。在中文文本中，声调用数字表示：一声为 1，二声为 2，三声为 3，四声为 4，轻声为 5。
  * `tone` `string` ***required*** \
    &#x20;具体发音映射规则，以“/”隔开，示例：`["绯闻/fei1闻","扁舟/偏舟","嫉妒/ji2妒"]`。

* `markdown_filter` `bool` ***optional*** \
  &#x20;是否启用 Markdown 过滤。

### 请求响应

* `sample_text` `string` \
  &#x20;试听音频对应的文本。

* `sample_audio` `string` \
  &#x20;试听音频的 base64 格式内容，格式为 WAV，可转换成文件后播放。

* `request_id` `string` \
  &#x20;本次请求的唯一标识。

### 示例

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -L 'https://api.stepfun.com/v1/audio/voices/preview' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $STEP_API_KEY" \
-d '{
    "file_id": "file-Ckyl3cV09A",
    "model": "stepaudio-2.5-tts",
    "text": "智能阶跃，十倍每一个人的可能",
    "sample_text": "今天天气不错",
    "instruction": "语气温柔，语速偏慢"
}'
```


# 流式语音合成
Source: https://platform.stepfun.com/docs/zh/api-reference/audio/ws-audio



通过 WebSocket 以流式方式将文本合成为语音，适合实时对话等边生成边播放的场景。

## 请求方式

WebSocket

## 请求地址

`wss://api.stepfun.com/v1/realtime/audio`

> [!NOTE]
>
> Step Plan 场景请使用 `wss://api.stepfun.com/step_plan/v1/realtime/audio`

## 请求头

* `Authorization` `string` ***required*** \
  &#x20;鉴权使用的 KEY，其值为 `Bearer YOUR_STEP_API_KEY`

## 请求参数

* `model` `string` ***required***

  需要使用的模型名称，当前支持 `stepaudio-3-tts`、`stepaudio-2.5-tts`、`step-tts-2` 和 `step-tts-mini`。

> [!NOTE]
>
> `step-tts-vivid` 模型名称不再推荐使用，但历史用户请求仍会继续支持。

> [!WARNING]
>
> 注意：`stepaudio-2.5-tts` 模型在 WebSocket 流式语音合成下的效果可能显著低于 HTTP 请求下的非流式语音合成，如果对时延没有要求，建议使用普通的非流式语音合成接口。

## 调用说明

流式生成音频需要在服务链接成功后，发送对应的 Client Event 事件，获取对应的 Server Event ，来完成音频的生成。

### Client Event & Server Event 对应关系

以下为流式调用过程中，客户端发送的 Client Event 事件及服务端返回的 Server Event 事件，详细说明见下文。

| **消息类型** | **客户端发送** | **服务端返回** | 备注 |
| - | - | - | - |
| 建联成功 | - | tts.connection.done | WebSocket 链接成功后下发的事件 |
| 创建会话 | tts.create | tts.response.created | 创建会话及对应响应。收到对应响应后，可进行进一步生成。 |
| 开始生成单句 | | tts.response.sentence.start | 累计的文本满足生成条件，开始生成 |
| 发送文本 | tts.text.delta | tts.response.audio.delta | 创建文本及对应的响应，收到响应后即可进行播放。 |
| 结束生成单句 | | tts.response.sentence.end | 累计的文本满足生成条件，结束生成 |
| 字幕时间戳 | | tts.response.subtitle | 开启 `timestamp` 后，每个切句对齐完成后异步下发该句词级时间戳 |
| 清空缓冲区 | tts.text.flush | tts.text.flushed | 可快速清空缓冲区，一次性获得当前尚未返回的音频内容。 |
| 发送文本结束 | tts.text.done | tts.response.audio.done | 完成本次生成，不再生成，服务端将会释放连接。 |
| 音频生成出错 | - | tts.response.error | 在生成过程中出现错误时的事件 |

> [!NOTE]
>
> 如果连续 60 秒无动作，则系统会自动断开链接。

## Client Event 详细说明

### 创建会话 `tts.create`

创建会话的事件，在完成建联后，收到 `tts.connection.done` Server Event 返回后发送此事件开始生成音频。

* `type` `string` ***required***\
  &#x20;固定为 `tts.create`

* `data` `object` ***required***\
  &#x20;事件内容
  * `session_id` `string` ***required***
    \
    &#x20;会话 ID，可用于判断具体沟通是哪个会话，由 `tts.connection.done` 事件返回。

  * `voice_id` `string` ***required***
    \
    &#x20;音色 ID，必填，可参考 [音色列表](/docs/zh/guides/developer/tts#官方音色清单) 查看支持的音色，试听对应音色。

  * `response_format` `string` ***optional***
    \
    &#x20;音频格式，支持 `wav`、`mp3`、`flac`、`opus`、`pcm`，以及 `mp3_stream`、`opus_stream`、`flac_stream` 三种流式格式。非必填，默认 `mp3`。
    \
    &#x20;说明：不带 `_stream` 后缀的格式，每个 `audio.delta` 返回的数据都是一个独立的完整文件，可直接单独播放或保存；带 `_stream` 后缀的格式则需要将所有 `audio.delta` 的数据按顺序拼接后才能得到一个完整的音频文件，同样支持边收边播，适合最终需要生成单个完整音频文件的场景。

  * `sample_rate` `int` ***optional***
    \
    &#x20;采样率，可选项为 `8000`、`16000`、`22050`、`24000`、`48000`，默认值为 `24000`。其中 `48000` 为最近几次迭代新增的采样率。

  * `pronunciation_map` `object array` ***optional***
    \
    &#x20;定义某个文字或符号注音或发音替换规则，在中文文本中，声调用数字表示：一声为1，二声为2，三声为3，四声为4，轻声为5。
    * `tone`  `string`  ***required*** \
      &#x20;具体发音映射规则，以"/"隔开，示例：`["绯闻/fei1闻","扁舟/偏舟","嫉妒/ji2妒"]`

  * `speed_ratio` `float` ***optional***
    \
    &#x20;语速，取值范围为 0.5\~2，默认值 1.0。0.5 表示 0.5 倍速。

  * `volume_ratio` `float` ***optional***
    \
    &#x20;音量，取值范围为 0.1\~2.0，默认值 1.0。0.1 表示缩小至 10% 音量；2.0 表示扩大至 200%音量

  * `text_normalization` `string` ***optional***
    \
    &#x20;文本归一化（Text Normalization）策略，可选值为 `standard` 和 `enhanced`，默认值为 `standard`。`standard` 为标准归一化，适合实时对话等对时延敏感的场景；`enhanced` 为增强归一化，对数字、单位、英文、符号等的读法做更充分的处理，适合播报类场景。缺省（不传该参数）时按 `standard` 处理，在 `tts.create` 时携带。

  * `mode` `string` ***optional***
    \
    &#x20;生成模式，可选项为 `sentence`  和 `default`。 `default` 表示按字生成，适合大模型流式生成场景，`sentence` 表示按句生成，适合已经生成好完整句子。默认为 `default`。

  * `markdown_filter` `bool` ***optional***
    \
    &#x20;是否启用 Markdown 过滤。

  * `timestamp` `bool` ***optional***
    \
    &#x20;词级时间戳（字幕）开关，置为 `true` 开启。开启后，每个切句对齐完成时会异步下发一条 `tts.response.subtitle` 事件，携带该切句的逐词时间戳。建议配合 `mode: "sentence"` 使用。

  * `instruction` `string` ***optional***
    \
    &#x20;全局自然语言指导，用于设定会话的全局情绪基调。仅在连接 `stepaudio-2.5-tts`、`stepaudio-3-tts` 模型时生效；`stepaudio-2.5-tts` 最大支持 200 个字符，`stepaudio-3-tts` 最大支持 500 个字符。

  * `voice_label` `object` ***optional***
    \
    音色标签，使用自定义音色时需要传入。language、emotion 和 style 三个字段同一时间只能有一个有值，暂不支持多个组合。
    * `language` `string` ***optional***\
      语言，支持 `粤语`、`四川话`、`日语` 三个选项。
    * `emotion` `string` ***optional***\
      情绪，支持 `高兴`、`生气` 等最多 11 个选项， 不同模型的支持情况可参考[音色标签](/docs/zh/guides/developer/tts#音色标签)
    * `style` `string` ***optional***\
      支持最多17种语速或演绎风格，不同模型的支持情况可参考[音色标签](/docs/zh/guides/developer/tts#音色标签)

> [!WARNING]
>
> 注意：`stepaudio-2.5-tts`、`stepaudio-3-tts` 模型不支持此字段。若使用上述模型，请勿传入 `voice_label`，直接使用 `instruction` 字段控制情绪与风格即可。其他模型的支持情况请参考[音色标签](/docs/zh/guides/developer/tts#音色标签)。

> [!NOTE]
>
> `default` 模式适用于 TTS 和大语言模型组合使用，该模式会自动进行攒句和切句，因此不会马上返回内容，而是当用户的输入满足一句话时才会进行生成；如果需要强制返回，则可以发送 `tts.text.flush`，模型则可快速返回内容。
>
> `sentence` 模式适用于已经有现成的长文本的场景，该模式会自动基于 `。！？!?` 进行切句，并进行生成。

**Example**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "type": "tts.create",
  "data": {
      "session_id": "01956e7388477cfcbdc3aaabf364bc70",
      "voice_id": "cixingnansheng",
      "response_format": "wav",
      "volume_ratio": 1.0,
      "text_normalization": "standard",
      "speed_ratio": 1.0,
      "sample_rate": 16000,
      "pronunciation_map":{
        "tone":[
          "阿胶/e1胶",
          "扁舟/偏舟",
          "LOL/laugh out loudly"
        ]
      }
  }
}
```

**Example（`stepaudio-2.5-tts`）**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "type": "tts.create",
    "data": {
        "session_id": "01956e7388477cfcbdc3aaabf364bc70",
        "voice_id": "cixingnansheng",
        "response_format": "wav",
        "volume_ratio": 1.0,
        "text_normalization": "enhanced",
        "speed_ratio": 1.0,
        "sample_rate": 16000,
        "instruction": "语气冰冷，压迫感强，语速偏慢",
        "pronunciation_map":{
            "tone":[
                "阿胶/e1胶",
                "扁舟/偏舟",
                "LOL/laugh out loudly"
            ]
        }
    }
}
```

**Example（开启 `timestamp`）**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "type": "tts.create",
    "data": {
        "session_id": "01956e7388477cfcbdc3aaabf364bc70",
        "voice_id": "cixingnansheng",
        "response_format": "mp3",
        "sample_rate": 24000,
        "mode": "sentence",
        "timestamp": true
    }
}
```

### 生成音频 `tts.text.delta`

生成音频的 Client Event。

> [!NOTE]
>
> 在生成过程中，如果 TTS 引擎认为已经达成了生成的条件，则会返回 `tts.response.sentence.start`
> 声明开始推理，并返回1个或多个 `tts.response.audio.delta`，返回音频内容。并在音频内容返回完成后，返回
> `tts.response.sentence.end` 事件声明完成此句完成生成。如 TTS 引擎认为未达成生成的条件，则不会返回任何事件。

* `type` `string` ***required***\
  &#x20;固定为 `tts.text.delta`

* `data` `object` ***required***\
  &#x20;事件内容
  * `session_id` `string` ***required***
    \
    &#x20;会话 ID，可用于判断具体沟通是哪个会话，由 `tts.connection.done` 事件返回。

  * `text` `string` ***required***
    \
    &#x20;要生成的文本内容，最大长度为 1000 个字符。使用 `stepaudio-2.5-tts`、`stepaudio-3-tts` 时，支持使用 `()` 传入不发音的内联指令；若文本本身需发音，请勿带括号。

**Example**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"type": "tts.text.delta",
	"data": {
		"session_id": "01956e7388477cfcbdc3aaabf364bc70",
		"text": "今天的天气真不错，我想去学习阶跃星辰的大模型技术"
	}
}
```

**Example（`stepaudio-2.5-tts`）**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "type": "tts.text.delta",
    "data": {
        "session_id": "01956e7388477cfcbdc3aaabf364bc70",
        "text": "（激动）今天的天气真不错，我想去学习阶跃星辰的大模型技术！"
    }
}
```

### 清空缓冲区 `tts.text.flush`

清空缓冲区，强制返回模型生成的音频。

* `type` `string` ***required*** \
  &#x20;固定为 `tts.text.flush`

* `data` `object` ***required***\
  &#x20;事件内容
  * `session_id` `string` ***required***
    \
    &#x20;会话 ID，可用于判断具体沟通是哪个会话，由 `tts.connection.done` 事件返回。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"type": "tts.text.flush",
	"data": {
		"session_id": "01956e8dc1d77bb98f9da8d1b642fcf0"
	}
}
```

### 完成音频生成 `tts.text.done`

完成音频生成

* `type` `string` ***required***\
  &#x20;固定为 `tts.text.done`

* `data` `object` ***required***\
  &#x20;事件内容

  * `session_id` `string` ***required***
    \
    &#x20;会话 ID，可用于判断具体沟通是哪个会话，由 `tts.connection.done` 事件返回。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"type": "tts.text.done",
	"data": {
		"session_id": "01956e8dc1d77bb98f9da8d1b642fcf0"
	}
}
```

## Server Event 详细说明

### 连接成功 `tts.connection.done`

连接成功

* `event_id` `string` ***required***\
  &#x20;事件 ID，每条事件唯一，联系客服排查问题时可提供。

* `type` `string` ***required***\
  &#x20;固定为 `tts.connection.done`

* `data` `object` ***required***\
  &#x20;事件内容
  * `session_id` `string` ***required***\
    &#x20;会话 ID，后续请求时需要带上使用

**Example**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"event_id": "01956e73888c7953896a6e176bf3d760",
	"type": "tts.connection.done",
	"data": {
		"session_id": "01956e7388477cfcbdc3aaabf364bc70"
	}
}
```

### 会话创建成功 `tts.response.created`

会话创建成功

* `event_id` `string` ***required***\
  &#x20;事件 ID，每条事件唯一，联系客服排查问题时可提供。

* `type` `string` ***required***\
  &#x20;固定为 `tts.response.created`

* `data` `object` ***required***\
  &#x20;事件内容
  * `session_id` `string` ***required***\
    &#x20;会话 ID，后续请求时需要带上使用

**Example**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"event_id": "01956e73888c7953896a6e176bf3d760",
	"type": "tts.response.created",
	"data": {
		"session_id": "01956e7388477cfcbdc3aaabf364bc70"
	}
}
```

### 开始生成单句 `tts.response.sentence.start`

开始生成单句

* `event_id` `string` ***required***\
  &#x20;事件 ID，每条事件唯一，联系客服排查问题时可提供。
* `type` `string` ***required***\
  &#x20;固定为 `tts.response.sentence.start`
* `data` `object` ***required***\
  &#x20;事件内容
  * `session_id` `string` ***required***\
    &#x20;会话 ID
  * `text` `string` ***required***\
    &#x20;本次生成的文本内容
  * `request_id` `string` ***required***\
    &#x20;单轮生成的请求标识，格式为 `<session_id>-tts.<id>`
  * `timestamp` `integer` ***required***\
    &#x20;事件时间戳，单位毫秒

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
        "event_id": "019f1c67e1667691ac65d76c85364615",
        "type": "tts.response.sentence.start",
        "data": {
                "session_id": "019f1c67e14b73cf81f83896595c4cab",
                "text": "今天天气很好。",
                "request_id": "019f1c67e14b73cf81f83896595c4cab-tts.019f1c67e166767981ff91c94fb63697",
                "timestamp": 1782887997798
        }
}
```

### 接收生成好的音频 `tts.response.audio.delta`

接收生成好的音频

* `event_id` `string` ***required***\
  &#x20;事件 ID，每条事件唯一，联系客服排查问题时可提供。

* `type` `string` ***required***\
  &#x20;固定为 `tts.response.audio.delta`

* `data` `object` ***required***\
  &#x20;事件内容
  * `session_id` `string` ***required***\
    &#x20;会话 ID，后续请求时需要带上使用
  * `status` `string` ***required***\
    &#x20;生成状态，可选项为 `unfinished` 和 `finished`。`unfinished` 表示生成未完成，`finished` 表示生成完成。
  * `audio` `string` ***required***\
    &#x20;音频内容，BASE64 编码的音频内容

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"event_id": "42bd707a-ba16-4ddb-a751-54d84301b474",
	"type": "tts.response.audio.delta",
	"data": {
		"session_id": "01956e8dc1d77bb98f9da8d1b642fcf0",
		"status": "unfinished",
		"audio": "BASE64 的音频内容",
	}
}
```

### 结束生成单句 `tts.response.sentence.end`

结束生成单句

* `event_id` `string` ***required***
  \
  &#x20;事件 ID，每条事件唯一，联系客服排查问题时可提供。
* `type` `string` ***required***
  \
  &#x20;固定为 `tts.response.sentence.end`
* `data` `object` ***required***\
  &#x20;事件内容
  * `session_id` `string` ***required***\
    &#x20;会话 ID
  * `text` `string` ***required***
    \
    &#x20;本次生成的文本内容
  * `request_id` `string` ***required***
    \
    &#x20;单轮生成的请求标识，格式为 `<session_id>-tts.<id>`
  * `timestamp` `integer` ***required***
    \
    &#x20;事件时间戳，单位毫秒

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
        "event_id": "019f1c67e16677c48e2610b503e22411",
        "type": "tts.response.sentence.end",
        "data": {
                "session_id": "019f1c67e14b73cf81f83896595c4cab",
                "text": "今天天气很好。",
                "request_id": "019f1c67e14b73cf81f83896595c4cab-tts.019f1c67e166767981ff91c94fb63697",
                "timestamp": 1782887997798
        }
}
```

### 词级时间戳 `tts.response.subtitle`

开启 `timestamp` 后，每个切句对齐完成后下发一条 `tts.response.subtitle` 事件，携带该切句的逐词时间戳。`items[].start_time` / `end_time` 已累加前序切句时长，可直接用于整段音频定位。

* `event_id` `string` ***required***\
  &#x20;事件 ID，每条事件唯一，联系客服排查问题时可提供。
* `type` `string` ***required***\
  &#x20;固定为 `tts.response.subtitle`
* `timestamp` `integer` ***required***\
  &#x20;事件下发时间，单位毫秒。
* `data` `object` ***required***\
  &#x20;事件内容
  * `session_id` `string` ***required***\
    &#x20;会话 ID
  * `request_id` `string` ***required***\
    &#x20;切句 ID，与对应的 `tts.response.sentence.start` 的 `request_id` 一致，用于关联切句。
  * `text` `string` ***required***\
    &#x20;切句文本
  * `items` `array` ***required***\
    &#x20;词级时间戳列表（对齐失败时可能为空）。
    * `text` `string` ***required***\
      &#x20;分词文本
    * `start_time` `integer` ***required***\
      &#x20;词起始时间，单位毫秒，已累加前序切句时长。
    * `end_time` `integer` ***required***\
      &#x20;词结束时间，单位毫秒，已累加前序切句时长。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
        "event_id": "019f21e6a8587b629b2dfe7efe2a6f37",
        "type": "tts.response.subtitle",
        "timestamp": 1782980192345,
        "data": {
                "session_id": "019f21e6a3ce7147b97a4f67ec66801a",
                "text": "今天天气真好，我们出去玩吧！",
                "request_id": "019f21e6a3ce7147b97a4f67ec66801a-tts.019f21e6a4047cb1aee49ed93734b287",
                "items": [
                        { "text": "今", "start_time": 0, "end_time": 160 },
                        { "text": "天", "start_time": 160, "end_time": 320 },
                        { "text": "天", "start_time": 320, "end_time": 480 },
                        { "text": "气", "start_time": 480, "end_time": 640 },
                        { "text": "真", "start_time": 640, "end_time": 880 },
                        { "text": "好，", "start_time": 880, "end_time": 1280 },
                        { "text": "我", "start_time": 1680, "end_time": 1760 },
                        { "text": "们", "start_time": 1760, "end_time": 1840 },
                        { "text": "出", "start_time": 1840, "end_time": 2000 },
                        { "text": "去", "start_time": 2000, "end_time": 2160 },
                        { "text": "玩", "start_time": 2160, "end_time": 2400 },
                        { "text": "吧！", "start_time": 2400, "end_time": 2640 }
                ]
        }
}
```

> [!NOTE]
>
> 时间戳由对齐模型在切句音频生成后异步计算，不阻塞音频流的下行。由于对齐是异步的，某切句的 `tts.response.subtitle` 可能在后续切句的音频事件之后才到达；请以 `request_id` 关联字幕与对应切句，不要假设它紧跟在 `tts.response.sentence.end` 之后。所有切句的 `tts.response.subtitle` 事件都会在 `tts.response.audio.done` 之前下发完毕。

### 开始清空缓存 `tts.text.flushed`

系统收到指令，开始清空缓存。

* `event_id` `string` ***required***\
  &#x20;事件 ID，每条事件唯一，联系客服排查问题时可提供。
* `type` `string` ***required***\
  &#x20;固定为 `tts.text.flushed`
* `data` `object` ***required***\
  &#x20;事件内容
  * `session_id` `string` ***required***
    \
    &#x20;会话 ID，后续请求时需要带上使用

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"event_id": "01956e8ee1b9788c95d5981b1cfdbf12",
	"type": "tts.text.flushed",
	"data": {
		"session_id": "01956e8dc1d77bb98f9da8d1b642fcf0"
	}
}
```

### 完成本次生成 `tts.response.audio.done`

完成本次生成。接收此事件后，将会自动断开链接。此外当 IDLE 时长超过 60 秒，也会自动完成生成。

* `event_id` `string` ***required***\
  &#x20;事件 ID，每条事件唯一，联系客服排查问题时可提供。
* `type` `string` ***required***\
  &#x20;固定为 `tts.response.audio.done`
* `data` `object` ***required***\
  &#x20;事件内容
  * `session_id` `string` ***required***\
    &#x20;会话 ID，后续请求时需要带上使用
  * `audio` `string` ***required***\
    &#x20;音频内容，BASE64 编码的音频内容，包含所有音频的内容。

**Example**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"event_id": "019f1c67e8187e5e8b12b36483b98444",
	"type": "tts.response.audio.done",
	"data": {
		"session_id": "019f1c67e14b73cf81f83896595c4cab",
		"audio": "<BASE64 完整音频>"
	}
}
```

### 故障报错 `tts.response.error`

当生成过程中出现问题后，将会返回此事件。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"event_id": "01956e8fdb157619a852bdf38028db45",
	"type": "tts.response.error",
	"data": {
		"session_id": "01956e8dc1d77bb98f9da8d1b642fcf0",
		"code": "503",
		"message": "The engine is currently overloaded, please try again later",
		"details": {
			"error": "The engine is currently overloaded, please try again later"
		}
	}
}
```

## 调用代码参考

**python**

先执行 `pip install websocket-client rel` 后执行如下代码。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import os
import websocket
import rel
import json

headers = {
    "Authorization": "Bearer " + os.environ["STEPFUN_API_KEY"]
}

def get_start_event(sid):
    return json.dumps(
        {
            "type": "tts.create",
            "data": {
                "session_id": sid,
                "voice_id": "cixingnansheng",
                "response_format": "wav",
                "volume_ratio": 1.0,
                # 文本归一化：standard / enhanced，默认 standard
                "text_normalization": "standard",
                "speed_ratio": 1.0,
                "sample_rate": 16000
            },
        }
    )

def on_message(ws, message):
    data = json.loads(message)
    session_id = data["data"]["session_id"]
    event_type = data["type"]

    if event_type == "tts.connection.done":
        start_event = get_start_event(session_id)
        ws.send(start_event)

    # 继续添加其他事件处理逻辑
    print(message)

def on_error(ws, error):
    print(error)

if __name__ == "__main__":
    websocket.enableTrace(True)
    ws = websocket.WebSocketApp(
        "wss://api.stepfun.com/v1/realtime/audio?model=step-tts-mini",
        header=headers,
        on_message=on_message,
        on_error=on_error,
    )

    ws.run_forever(
        dispatcher=rel,
        reconnect=5
    )
    rel.signal(2, rel.abort)
    rel.dispatch()
```

**node**

```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const WebSocket = require('ws');

const url = 'wss://api.stepfun.com/v1/realtime/audio?model=step-tts-mini'; // 替换为您的 WebSocket URL
const headers = {
  'Authorization': 'Bearer ' + process.env.STEPFUN_API_KEY, // 替换为您的 API 令牌
  'Content-Type': 'application/json',
};

const ws = new WebSocket(url, {
  headers: headers
});

ws.on('open', () => {
  console.log('连接已建立');
});

ws.on('message', (message) => {
  console.log(`收到消息: ${message}`);
  event = JSON.parse(message)
  session_id = event["data"]["session_id"]
  event_type = event["type"]

  if (event_type == "tts.connection.done"){
      ws.send(JSON.stringify({
          "type": "tts.create",
        "data": {
          "session_id": session_id,
          "voice_id": "cixingnansheng",
          "response_format": "wav",
          "volume_ratio": 1.0,
          "text_normalization": "standard",
          "speed_ratio": 1.0,
          "sample_rate": 16000
        }
      }))
  }
  // 添加其他处理逻辑
});

ws.on('error', (error) => {
  console.error(`发生错误: ${error}`);
});

ws.on('close', (code, reason) => {
  console.log(`连接关闭, 状态码: ${code}, 原因: ${reason}`);
});
```

**StepAudio 2.5 TTS (python)**

先执行 `pip install websocket-client rel` 后执行如下代码。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import os
import websocket
import rel
import json

headers = {
    "Authorization": "Bearer " + os.environ["STEPFUN_API_KEY"]
}

def get_start_event(sid):
    return json.dumps(
        {
            "type": "tts.create",
            "data": {
                "session_id": sid,
                "voice_id": "cixingnansheng",
                "response_format": "wav",
                "volume_ratio": 1.0,
                # 文本归一化策略：standard / enhanced，默认 standard；enhanced 适合播报等更看重合成效果的场景
                "text_normalization": "enhanced",
                "speed_ratio": 1.0,
                "sample_rate": 16000,
                # 全局情绪指令，最长 200 字符
                "instruction": "语气极其愤怒，压迫感极强，语速偏快"
            },
        }
    )

def on_message(ws, message):
    data = json.loads(message)
    session_id = data["data"]["session_id"]
    event_type = data["type"]

    if event_type == "tts.connection.done":
        # 发送建联与全局指令
        start_event = get_start_event(session_id)
        ws.send(start_event)

        # 发送文本：支持 () 内联指令（不发音），文本需 <= 1000 字符
        text_event = json.dumps({
            "type": "tts.text.delta",
            "data": {
                "session_id": session_id,
                "text": "（拍桌子）你以为我们阶跃星辰北京公司的技术是开玩笑的吗！"
            }
        })
        ws.send(text_event)

        # 发送 flush 强制返回当前音频
        flush_event = json.dumps({
            "type": "tts.text.flush",
            "data": {"session_id": session_id}
        })
        ws.send(flush_event)

    # 打印服务端返回的事件（包含生成的音频数据等）
    print(message)

def on_error(ws, error):
    print(error)

if __name__ == "__main__":
    websocket.enableTrace(True)
    ws = websocket.WebSocketApp(
        "wss://api.stepfun.com/v1/realtime/audio?model=stepaudio-2.5-tts",
        header=headers,
        on_message=on_message,
        on_error=on_error,
    )

    ws.run_forever(
        dispatcher=rel,
        reconnect=5
    )
    rel.signal(2, rel.abort)
    rel.dispatch()
```

**字幕 (python)**

先执行 `pip install websocket-client rel` 后执行如下代码。

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import os
import websocket
import rel
import json

headers = {
    "Authorization": "Bearer " + os.environ["STEPFUN_API_KEY"]
}

def get_start_event(sid):
    return json.dumps(
        {
            "type": "tts.create",
            "data": {
                "session_id": sid,
                "voice_id": "cixingnansheng",
                "response_format": "mp3",
                "sample_rate": 24000,
                # 按句生成，配合字幕效果更佳
                "mode": "sentence",
                # 开启词级时间戳（字幕）
                "timestamp": True
            },
        }
    )

subtitles = {}  # request_id -> 字幕条目

def on_message(ws, message):
    data = json.loads(message)
    session_id = data["data"]["session_id"]
    event_type = data["type"]

    if event_type == "tts.connection.done":
        ws.send(get_start_event(session_id))

        # 发送文本并结束生成
        ws.send(json.dumps({
            "type": "tts.text.delta",
            "data": {"session_id": session_id, "text": "今天天气真好。我们出去玩吧。"}
        }))
        ws.send(json.dumps({
            "type": "tts.text.done",
            "data": {"session_id": session_id}
        }))

    elif event_type == "tts.response.subtitle":
        # 收到该切句的逐词时间戳；以 request_id 关联切句
        d = data["data"]
        subtitles[d["request_id"]] = d
        print(f"字幕: {d['text']}")
        for item in d["items"]:
            print(f"  {item['text']}: {item['start_time']}ms - {item['end_time']}ms")

    elif event_type == "tts.response.audio.done":
        # 此时所有字幕事件均已下发完毕
        print("生成完成，共收到字幕:", len(subtitles))

def on_error(ws, error):
    print(error)

if __name__ == "__main__":
    websocket.enableTrace(True)
    ws = websocket.WebSocketApp(
        "wss://api.stepfun.com/v1/realtime/audio?model=step-tts-mini",
        header=headers,
        on_message=on_message,
        on_error=on_error,
    )

    ws.run_forever(
        dispatcher=rel,
        reconnect=5
    )
    rel.signal(2, rel.abort)
    rel.dispatch()
```


# Chat Completions API
Source: https://platform.stepfun.com/docs/zh/api-reference/chat/chat-completion-create



调用 Chat Completions API，获取模型生成的对话响应数据。

## 请求地址

`POST https://api.stepfun.com/v1/chat/completions`

> [!NOTE]
>
> Step Plan 场景请使用 `POST https://api.stepfun.com/step_plan/v1/chat/completions`

## 请求参数

* `model` `string` ***required***\
  需要使用的模型名称，例如 `step-5-preview`、`step-3.7-flash`、`step-3.5-flash`、`step-3.5-flash-2603`、`stepaudio-3-chat-preview` 或 `stepaudio-2.5-chat`。`step-router-v1` 仅可通过 [Step Plan](/docs/zh/step-plan/overview) 通道调用，详见本文「Step Plan 通道：DeepSeek 引擎字段差异」。

* `messages` `object array` ***required***\
  迄今为止用户输入或模型生成的不同类别消息列表

  * 系统消息 `object`
    * `role` `string`\
      系统类别名称，总是为 `system`
    * `content` `string`\
      系统消息的文本内容
  * 用户消息 `object`
    * `role` `string`\
      用户类别名称，总是 `user`
    * `content` `string or object array`\
      用户消息内容，类型为 `multipart` 消息列表或者普通文本消息字符串
      * 普通文本消息 `string`
      * `multipart` 消息列表 `object array`\
        结构化的图、视频、音频、文字混合消息
        * 文本消息 `object`
          * `type` `string`\
            总为 `text`
          * `text` `string`\
            消息文本内容
        * 图片消息 `object`
          * `type` `string`\
            总为 `image_url`
          * `image_url` `object`
            * `url` `string`\
              图片地址或 base64 编码的图片，图片格式：jpg/jpeg、png、webp、静态 gif，仅支持 http 和 https 协议。base64 格式举例：`data:image/jpeg;base64,${base64_string}`。
            * `detail` `string` ***optional***\
              图片细节级别：`low` / `high` 可选。`high` 按原图分辨率理解，在大图、OCR、极端长宽比等场景表现更好，token 随图片大小变化；`low` 将图片缩放到固定尺寸、更省 token，适合不要求高清细节、想省 token 或提速的场景。
        * 视频消息 `object`
          * `type` `string`\
            总为 `video_url`
          * `video_url` `object`
            * `url` `string`\
              视频的 URL 地址，视频格式：video/mp4，仅支持 http 和 https 协议，视频内容要小于 128M，时长建议小于 5 分钟。
        * 音频消息 `object`
          * `type` `string`\
            总为 `input_audio`
          * `input_audio` `object`
            * `data` `string`\
              音频内容，为音频的 base64 编码。base64 格式举例：`data:audio/mpeg;base64,${base64_string}`，请更换音频格式（当前仅支持 mp3 和 wav）及对应的 base64 编码后字符串。
  * 工具函数消息 `object`
    * `role` `string`\
      工具类别名称，总是为 `tool`
    * `content` `string`\
      函数执行得到的内容
    * `tool_call_id` `string`\
      执行函数的 ID，由 assistant 在上一轮对话中返回。
  * 聊天助手消息 `object`
    * `role` `string`\
      聊天助手类别名称，总是为 `assistant`
    * `content` `string | null`\
      聊天助手消息的文本内容

* `tools` `object array` ***optional***\
  Toolcall 支持的函数列表。`step-5-preview` 不支持其中的 `type: "web_search"`，请改用 [网页搜索 API](/docs/zh/api-reference/search/search)。

  * `type` `string`\
    工具类型，总是为 `function`
  * `function` `object`\
    函数内容的描述
    * `name` `string`\
      函数名称，要求纯英文、数字和 \_- 符号，建议不要超过 64 个字符长度。
    * `description` `string`\
      函数描述，支持中英文，它用于告诉模型函数实现何种功能和目的，方便模型来判断和选择。
    * `parameters` `object`\
      函数的参数
      * `type` `object`\
        参数描述，一般为 object
      * `properties` `object`\
        函数参数内容，以 key 为参数的名称，然后通过 `type` 和 `description` 描述参数的类型和介绍。
        * `type` `string|number|integer|object|array|boolean`\
          参数类型，可以参考 [json-schema](https://json-schema.org/understanding-json-schema/reference/type) 介绍。
        * `description` `string`\
          函数参数描述，支持中英文，它用于告诉模型函数参数的含义。

* `audio` `object` ***optional***\
  用于控制音频输出的参数，只在支持端到端模型场景的模型下生效（`step-1o-audio`/`step-audio-2`/`step-audio-2-mini`/`step-audio-r1.5`）
  * `voice` `string` ***required***\
    指定生成音频的声音 ID，对于 `step-1o-audio` 可通过[获取声音列表接口](/docs/zh/api-reference/audio/list-voice)查询可用的声音 ID，对于 `step-audio-2` 系列模型，可用 `wenrounansheng`（温柔男声）、`qingchunshaonv`（青春少女）、`livelybreezy-female`（活力少女）、`elegantgentle-female`（高雅女声）四种声音 ID。
  * `format` `string` ***required***\
    指定生成音频的格式，支持 `pcm` 和 `wav` 两种格式，在非流式场景下（stream=false）支持 wav 输出；在流式场景下（stream=true）时，只支持 pcm 输出（24khz, 单声道, 16bit）。

* `modalities` `string array` ***optional***\
  指定输出的模态类型，支持 `text`、`audio` 两种模态类型，只在端到端模型场景下必填。如果需要模型输出音频，则需要将 `audio` 添加到该参数中，建议设置为 `["text", "audio"]`。`stepaudio-2.5-chat` 仅支持 `text`，若选择 `audio` 会报错。

* `max_tokens` `int` ***optional***\
  聊天需要生成的 token 最大数量，默认值为 INF（不作限制，由模型自动决定）。输入 token 和生成 token 的总数量受限于指定模型的最大上下文长度。

* `temperature` `float` ***optional***\
  采样温度，介于0.0和2.0之间的数字。较高值（如0.8）会使生成更随机，较低值（如0.2）会使其生成结果更集中且确定。

* `top_p` `float` ***optional***\
  核心采样，该值会使模型生成具有 top\_p 概率质量的 token 并输出到结果。

* `n` `int` ***optional***\
  控制模型为每个输入消息生成的响应消息结果条数，默认值为1，最大不限，建议不超过5。

* `stream` `bool` ***optional***\
  是否流式生成响应消息，默认值为 false

* `stop` `string | string array` ***optional***\
  停止生成的字符串或字符串数组。生成过程中一旦命中其中任意内容，模型立即停止输出。默认为空。

* `frequency_penalty` `float` ***optional***\
  默认为 0，取值范围 -2.0 到 2.0。值越高，会根据 token 在已生成文本中出现的频率施加降频惩罚，从而降低模型重复生成相同内容的可能性。

* `response_format` `object` ***optional***\
  用于指导模型输出特定格式的内容。默认为 `{"type":"text"}`，表示输出文本。
  * `type` `string`\
    输出格式类型，可选值为 `text`、`json_object`、`json_schema`。设置为 `json_object` 可以[开启 JSON Mode](/docs/zh/guides/developer/json-mode)，输出可解析的 JSON 结构。设置为 `json_schema` 可以指定 JSON Schema 约束输出结构。
  * `json_schema` `object`\
    当 `type` 为 `json_schema` 时必填，定义输出的 JSON Schema。
    * `name` `string` ***required***\
      Schema 名称，用于标识该 schema。
    * `strict` `boolean` ***optional***\
      是否开启严格模式，开启后模型输出将严格遵循所定义的 schema。默认为 `false`。
    * `schema` `object` ***required***\
      JSON Schema 定义对象，描述期望的输出结构。遵循 [JSON Schema](https://json-schema.org/) 规范。

* `reasoning_format` `string` ***optional***\
  用于指导模型输出时使用的 reasoning 字段；默认为 `general`，表示通用推理，使用 `reasoning` 字段返回结果；可选项为
  \[`general`,`deepseek-style`]。当设置为 `deepseek-style` 时，可使用 DeepSeek 兼容的 `reasoning_content` 字段获取到
  reasoning 内容。

* `reasoning_effort` `string` ***optional***\
  控制模型的推理深度。支持三档推理强度的模型可选值为 `low`、`medium`、`high`；`step-3.5-flash-2603` 兼容 `low`、`high` 两档。值越高，模型会进行更深入的思考，但响应时间可能更长。

## Step Plan 通道：DeepSeek 引擎字段差异

`step-router-v1` 仅可通过 [Step Plan](/docs/zh/step-plan/overview) 通道（`https://api.stepfun.com/step_plan/v1`）调用，系统会自动在 `deepseek-v4-pro` 与 `step-3.7-flash` 之间路由。该模型的字段约束与本文「请求参数」一致，下表列出的字段除外。

| 字段 | Step Plan 通道下的行为 |
| - | - |
| `model` | 仅接受 `step-router-v1`，其他名称返回 HTTP 400 `request_params_invalid` |
| `max_tokens` | 上限为 250K |
| `messages` 中的图像 / 文档输入 | 不支持，使用会返回 `unsupported_content_type` |
| `tools` 中的 `web_search` | 不支持，使用会返回 `unsupported_content_type` |

## 响应格式

### 非流式响应

当 `stream=false`（默认）时，返回单个 Chat Completion 响应对象。

#### 属性

* `id` `string`

  生成的聊天响应 ID
* `object` `string`

  模型生成聊天响应的模式，此模式下总为 `chat.completion`
* `model` `string`

  模型名称
* `created` `timestamp`

  生成聊天响应时的 Unix 时间戳，单位为秒
* `choices` `object array`

  模型生成的聊天响应结果的可选路径列表。

  * `finish_reason` `string`\
    模型停止继续生成的原因，可选值包括 `stop`（正常结束）、`length`（达到 `max_tokens` 上限）与 `tool_calls`（模型发起工具调用）
  * `index` `int` \
    &#x20;当前可选路径序列号
  * `message` `object` \
    &#x20;模型生成的聊天响应实际消息内容

  - `role` `string`\
    消息所属角色，这里总为 `assistant`
  - `content` `string`\
    消息文本内容
  - `reasoning` `string`\
    推理思考过程内容，仅在 step 推理模型下返回。
  - `reasoning_content` `string`\
    推理思考过程内容，与 `reasoning` 字段一同返回且内容一致（DeepSeek 兼容字段名），仅在 step 推理模型下返回。
  - `audio` `object` ***optional***\
    端到端语音模型生成的音频内容，仅当请求参数 `modalities` 包含 `audio` 时返回。

  * `data` `string`\
    生成音频的 base64 编码
  * `transcript` `string`\
    生成音频对应的文本转写

  - `tool_calls` `object array` ***optional***\
    toolcall 内容返回

  * `id` `string`\
    函数执行 ID，由模型生成，在 context 保持唯一。
  * `type` `string`\
    toolcall 的类型，默认为 `function`
  * `function` `object`\
    函数的消息体

  - `name` `string` \
    &#x20;函数名称，通常纯英文、数字和\_-符号，一般是在上一轮对话提交的 tools 列表中
  - `arguments` `string` \
    &#x20;函数执行的参数，一般为 json 结构化对象。
* `usage` `object`

  模型聊天响应生成的 token 统计信息

  * `prompt_tokens` `int` \
    &#x20;生成过程中使用的提示信息总 token 数量
  * `completion_tokens` `int` \
    &#x20;生成的响应消息内容总 token 数量
  * `total_tokens` `int`\
    生成结束后统计的总的 token 数量
  * `prompt_tokens_details` `object` ***optional*** \
    &#x20;提示 token 的细分统计

  - `cached_tokens` `int`\
    提示信息中命中缓存的 token 数量

  * `completion_tokens_details` `object` ***optional*** \
    &#x20;生成 token 的细分统计

  - `reasoning_tokens` `int`\
    推理思考过程消耗的 token 数量

#### 示例

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "b7b56af0-52a6-483f-a589-948182676a1b",
  "object": "chat.completion",
  "created": 1709893411,
  "model": "step-5-preview",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！阶跃星辰是一家专注于人工智能技术的公司，致力于开发和提供各种AI解决方案。我们的人工智能技术涵盖了自然语言处理、计算机视觉、机器学习等领域，旨在帮助用户在各个行业和领域中提高效率和创造价值。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 83, "completion_tokens": 176, "total_tokens": 259 }
}
```

### 流式响应

当 `stream=true` 时，返回 Server-Sent Events (SSE) 格式的流式数据。每个事件包含一个 Chat Completion 响应对象块。

#### 属性

* `id` `string`

  生成的聊天响应 ID
* `object` `string`

  模型生成聊天响应的模式，此模式下总为 `chat.completion.chunk`
* `created` `timestamp`

  聊天响应时的 Unix 时间戳，单位为秒
* `model` `string`

  模型名称
* `choices` `object array`

  模型流式生成的聊天响应结果的可选路径列表。单个 `choice` object 属性：

  * `finish_reason` `string`\
    模型停止继续生成的原因，可选值包括 `stop`（正常结束）、`length`（达到 `max_tokens` 上限）与 `tool_calls`（模型发起工具调用）
  * `index` `int`\
    当前可选路径序列号
  * `delta` object\
    模型渐进生成的聊天响应块

  - `role` `string`\
    消息所属角色，此处总为 `assistant`
  - `content` `string`\
    消息文本内容
  - `reasoning` `string`\
    推理思考过程内容，仅在 step 推理模型下返回。
  - `reasoning_content` `string`\
    推理思考过程内容，与 `reasoning` 字段一同返回且内容一致（DeepSeek 兼容字段名），仅在 step 推理模型下返回。
  - `tool_calls` `object array` ***optional***\
    toolcall 内容返回

  * `id` `string`\
    函数执行 ID，由模型生成，在 context 保持唯一。
  * `type` `string`\
    toolcall 的类型，默认为 `function`
  * `function` `object`\
    函数的消息体

  - `name` `string`\
    函数名称，通常纯英文、数字和\_-符号，一般是在上一轮对话提交的 tools 列表中
  - `arguments` `string`\
    函数执行的参数，一般为 json 结构化对象。
* `usage` `object`

  模型聊天响应生成的 token 统计信息

  * `prompt_tokens` `int`\
    &#x20;生成过程中使用的提示信息总 token 数量
  * `completion_tokens` `int`\
    &#x20;生成的响应消息内容总 token 数量
  * `total_tokens` `int`\
    生成结束后统计的总的 token 数量
  * `prompt_tokens_details` `object` ***optional***\
    &#x20;提示 token 的细分统计

  - `cached_tokens` `int`\
    提示信息中命中缓存的 token 数量

  * `completion_tokens_details` `object` ***optional***\
    &#x20;生成 token 的细分统计

  - `reasoning_tokens` `int`\
    推理思考过程消耗的 token 数量

#### 示例

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
data: {"id":"d7ae7c4a-1524-4fe5-9d58-e4d59b89d8f0","object":"chat.completion.chunk","created":1709899323,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"您"},"finish_reason":""}],"usage":{"prompt_tokens":83,"completion_tokens":1,"total_tokens":84}}

data: {"id":"d7ae7c4a-1524-4fe5-9d58-e4d59b89d8f0","object":"chat.completion.chunk","created":1709899323,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"好"},"finish_reason":""}],"usage":{"prompt_tokens":83,"completion_tokens":2,"total_tokens":85}}

data: {"id":"d7ae7c4a-1524-4fe5-9d58-e4d59b89d8f0","object":"chat.completion.chunk","created":1709899323,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"！"},"finish_reason":""}],"usage":{"prompt_tokens":83,"completion_tokens":3,"total_tokens":86}}

...

data: {"id":"d7ae7c4a-1524-4fe5-9d58-e4d59b89d8f0","object":"chat.completion.chunk","created":1709899323,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":""},"finish_reason":"stop"}],"usage":{"prompt_tokens":83,"completion_tokens":150,"total_tokens":233}}

data: [DONE]
```

## 示例

> 说明：以下基础示例默认使用 `step-5-preview`。如需控制模型的推理深度，可参考「推理强度」示例中的 `reasoning_effort` 用法。

**推理强度**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEPFUN_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "messages": [
      {
        "role": "user",
        "content": "请用三句话解释什么是强化学习。"
      }
    ],
    "reasoning_effort": "medium",
    "max_tokens": 1024
  }'
```

**文字聊天**

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

completion = client.chat.completions.create(
    model="step-5-preview",
    messages=[
        {
            "role": "system",
            "content": "你是由阶跃星辰提供的AI聊天助手，你擅长中文，英文，以及多种其他语言的对话。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容",
        },
        {
            "role": "user",
            "content": "你好，请介绍一下阶跃星辰的人工智能!"
        }
    ],
)

print(completion)
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

async function main() {
    const completion = await openai.chat.completions.create({
        model: "step-5-preview",
        messages: [
            {
                role: "system",
                content: "你是由阶跃星辰提供的AI聊天助手，你擅长中文，英文，以及多种其他语言的对话。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容"
            },
            {
                role: "user",
                content: "你好，请介绍一下阶跃星辰的人工智能!"
            }
        ]
    });

    console.log(JSON.stringify(completion));
}

main();
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "messages": [
      {
        "role": "system",
        "content": "你是由阶跃星辰提供的AI聊天助手，你擅长中文，英文，以及多种其他语言的对话。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容。"
      },
      {
        "role": "user",
        "content": "你好，请介绍一下阶跃星辰的人工智能！"
      }
    ]
  }'
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "e2eb4b00d2c226517de3882f17d9664b.ffead889783a0bcd8d2bd17ea4d4c2af",
  "object": "chat.completion",
  "created": 1772624997,
  "model": "step-5-preview",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "阶跃星辰（StepFun）是一家专注于**多模态人工智能技术研发与应用**的科技公司，致力于推动大模型（LLM）在文本、图像、逻辑推理等多领域的融合创新。其核心产品 **Step AI**（又称Step模型）具备以下特点：\n\n---\n\n### 🔍 **核心能力**\n1. **多模态融合**  \n   - 不仅能处理文本，还可理解图片、图表等视觉信息，实现跨模态推理（例如根据图片描述内容、解答视觉逻辑题）。\n2. **强大的逻辑与知识能力**  \n   - 在数理逻辑、代码生成、专业知识问答等场景表现突出，支持复杂任务拆解与精准分析。\n3. **多语言支持**  \n   - 覆盖中、英及多语种交流，适应全球化场景。\n4. **安全与合规**  \n   - 严格遵循内容安全规范，拒绝生成暴力、仇恨、虚假信息等有害内容，注重用户隐私保护。\n\n---\n\n### 🌟 **技术亮点**\n- **自主研发大模型架构**：针对多模态任务优化，提升视觉-语言对齐能力。\n- **高效推理与低能耗设计**：在保证性能的同时，兼顾部署效率。\n- **持续迭代能力**：通过数据与算法优化，动态提升模型的理解与生成质量。\n\n---\n\n### 🚀 **应用场景**\n- **教育科研**：辅助解题、文献分析、多学科知识问答。\n- **办公创作**：文档总结、代码辅助、创意文案生成。\n- **工业与商业**：数据分析报告生成、多模态信息检索、智能客服升级。\n- **日常生活**：跨语言交流、图像内容解读、个性化知识助手。\n\n---\n\n### 🌍 **价值观与愿景**\n阶跃星辰强调 **“技术向善”**，推动AI在安全、可靠、有益的方向发展，致力于成为多模态智能时代的引领者，让技术服务于社会创新与人类福祉。\n\n---\n\n如需了解具体技术细节或应用案例，可进一步探讨！ 🌟"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 85,
    "completion_tokens": 701,
    "total_tokens": 786
  }
}
```

**图片理解**

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

completion = client.chat.completions.create(
    model="step-5-preview",
    messages=[
        {
            "role": "system",
            "content": "你是由阶跃星辰提供的AI聊天助手，你除了擅长中文，英文，以及多种其他语言的对话以外，还能够根据用户提供的图片，对内容进行精准的内容文本描述。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容",
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "用优雅的语言描述这张图片",
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://www.stepfun.com/assets/section-1-CTe4nZiO.webp",
                        "detail": "high"
                    },
                },
            ],
        },
    ],
)

print(completion)
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

async function main() {
    const completion = await openai.chat.completions.create({
        model: "step-5-preview",
        messages: [
            {
                role: "system",
                content: "你是由阶跃星辰提供的AI聊天助手，你除了擅长中文，英文，以及多种其他语言的对话以外，还能够根据用户提供的图片，对内容进行精准的内容文本描述。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容"
            },
            {
                role: "user",
                content: [
                    {
                        type: "text",
                        text: "用优雅的语言描述这张图片"
                    },
                    {
                        type: "image_url",
                        image_url: {
                            url: "https://www.stepfun.com/assets/section-1-CTe4nZiO.webp",
                            detail: "high"
                        }
                    }
                ]
            }
        ]
    });

    console.log(JSON.stringify(completion));
}

main();
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "messages": [
      {
        "role": "system",
        "content": "你是由阶跃星辰提供的AI聊天助手，你除了擅长中文，英文，以及多种其他语言的对话以外，还能够根据用户提供的图片，对内容进行精准的内容文本描述。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容"
      },
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "用优雅的语言描述这张图片"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://www.stepfun.com/assets/section-1-CTe4nZiO.webp",
              "detail": "high"
            }
          }
        ]
      }
    ]
  }'
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "id": "298ad5e6-033a-41f8-9801-43be6e106f22",
    "object": "chat.completion",
    "created": 1710145618,
    "model": "step-5-preview",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "在黄昏的柔和光线下，一座现代化的建筑映入眼帘，它拥有鲜明的红色外观，与周围环境形成鲜明对比。这座建筑的底层设有宽敞的玻璃窗，为室内提供了充足的自然光。建筑的一侧有醒目的标识，顶部的窗户排列整齐，展现了现代设计的风格。\n\n在建筑前的空地上，有一棵光秃的树，其枝条在微风中轻轻摇曳。树下是一片铺着碎石的土地，为这个空间增添了一丝自然的气息。在空地的一侧，还可以看到几个小巧的灯具，它们发出的温暖光线在傍晚显得格外温馨。\n\n建筑周围环境整洁，道路上没有车辆，显得非常宁静。远处可以看到其他建筑的轮廓，以及天空中即将落下的太阳，为这幅画面增添了丰富的层次感。整个场景透露出一种宁静而有序的都市生活氛围。"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 497,
        "completion_tokens": 169,
        "total_tokens": 666
    }
}
```

**语音输入输出**

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import base64
from openai import OpenAI

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

completion = client.chat.completions.create(
    model="step-audio-2",
    modalities=["text", "audio"],
    messages=[
        {
            "role": "system",
            "content": "你是一个老北京大爷，喜欢用京片子和用户聊天。",
        },
        {
            "role": "user",
            "content": "今儿个北京的天气咋样啊？",
        },
    ],
    audio={
        "voice": "wenrounansheng",
        "format": "wav",
    },
    stream=False,
)

# response transcript
print(completion.choices[0].message.audio.transcript)
# save response audio
with open("response.wav", "wb") as f:
    f.write(base64.b64decode(completion.choices[0].message.audio.data))
# 打开 response.wav 即可收听音频回复
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";
import fs from "fs";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

const downloadAudioAsBase64 = async (url) => {
    const response = await fetch(url);
    const arrayBuffer = await response.arrayBuffer();
    const buffer = Buffer.from(arrayBuffer);
    return "data:audio/wav;base64," + buffer.toString("base64");
};

async function main() {
    const completion = await openai.chat.completions.create({
        model: "step-audio-2",
        modalities: ["text", "audio"],
        messages: [
            {
                role: "system",
                content: "你是一个动物声音识别专家，请根据用户提供的动物声音进行识别。"
            },
            {
                role: "user",
                content: [
                    {
                        type: "text",
                        text: "听听这是什么声音"
                    },
                    {
                        type: "input_audio",
                        input_audio: {
                            data: await downloadAudioAsBase64("https://stepchat-static.tos-cn-shanghai.volces.com/resource_tmp/cat-meow.wav")
                        }
                    }
                ]
            }
        ],
        audio: {
            voice: "wenrounansheng",
            format: "wav"
        },
        stream: false
    });
    // response transcript
    console.log(completion.choices[0].message.audio.transcript);
    // save response audio
    fs.writeFileSync("response.wav", Buffer.from(completion.choices[0].message.audio.data, "base64"));
    // 打开 response.wav 即可收听音频回复
}

main();
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-audio-2",
    "modalities": ["text", "audio"],
    "messages": [
      {
        "role": "system",
        "content": "你是一个老北京大爷，喜欢用京片子和用户聊天。"
      },
      {
        "role": "user",
        "content": "今儿个北京的天气咋样啊？"
      }
    ],
    "audio": {
      "voice": "wenrounansheng",
      "format": "wav"
    },
    "stream": false
  }'
```

语音示例返回（text+audio 模态，带 toolcall 字段），由于带有 audio，所以返回内容较大，audio 字段内容被截断显示：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "019b55f32eb27db7a0cc933be0216686",
  "choices": [
    {
      "finish_reason": null,
      "index": 0,
      "logprobs": null,
      "message": {
        "role": "assistant",
        "audio": {
          "data": "[base64 wav, length=193940]",
          "transcript": "哎呀，现在是下午三点啦。"
        },
        "tool_calls": [
          {
            "id": "call-1766673564415832077",
            "function": {
              "arguments": "{\"city\": \"北京\"}",
              "name": "get_weather"
            },
            "type": "function",
            "index": 0
          }
        ]
      }
    }
  ],
  "created": 1766673565,
  "model": "step-audio-2",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 106,
    "prompt_tokens": 410,
    "total_tokens": 516,
    "completion_tokens_details": null,
    "prompt_tokens_details": null
  }
}
```

**Base64编码图片**

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# -*- coding: utf8 -*-

import base64
import requests
from openai import OpenAI

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

# 加载图片到内存，仅演示。按需改成读文件等
r = requests.get("https://www.stepfun.com/assets/section-1-CTe4nZiO.webp")
r.raise_for_status()
image_str = base64.b64encode(r.content).decode("ascii")

completion = client.chat.completions.create(
    model="step-5-preview",
    messages=[
        {
            "role": "system",
            "content": "你是由阶跃星辰提供的AI聊天助手，你除了擅长中文，英文，以及多种其他语言的对话以外，还能够根据用户提供的图片，对内容进行精准的内容文本描述。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容",
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "用优雅的语言描述这张图片",
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "data:image/webp;base64,%s" % (image_str),
                    },
                },
            ],
        },
    ],
)

print(completion)
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

// 加载图片到内存，仅演示。按需改成读文件等
async function load_image(url) {
    let response = await fetch(url);
    let blob = await response.blob();
    let buffer = Buffer.from(await blob.arrayBuffer());
    return "data:" + blob.type + ";base64," + buffer.toString("base64");
}

async function main() {
    const completion = await openai.chat.completions.create({
        model: "step-5-preview",
        messages: [
            {
                role: "system",
                content: "你是由阶跃星辰提供的AI聊天助手，你除了擅长中文，英文，以及多种其他语言的对话以外，还能够根据用户提供的图片，对内容进行精准的内容文本描述。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容"
            },
            {
                role: "user",
                content: [
                    {
                        type: "text",
                        text: "用优雅的语言描述这张图片"
                    },
                    {
                        type: "image_url",
                        image_url: {
                            url: await load_image("https://www.stepfun.com/assets/section-1-CTe4nZiO.webp")
                        }
                    }
                ]
            }
        ]
    });

    console.log(JSON.stringify(completion));
}

main();
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# 加载图片到内存，仅演示。按需改成读文件等
image_base64="data:image/webp;base64,"$(curl -s "https://www.stepfun.com/assets/section-1-CTe4nZiO.webp" | base64)

curl https://api.stepfun.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d "{
    \"model\": \"step-5-preview\",
    \"messages\": [
      {
        \"role\": \"system\",
        \"content\": \"你是由阶跃星辰提供的AI聊天助手，你除了擅长中文，英文，以及多种其他语言的对话以外，还能够根据用户提供的图片，对内容进行精准的内容文本描述。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容\"
      },
      {
        \"role\": \"user\",
        \"content\": [
          {
            \"type\": \"text\",
            \"text\": \"用优雅的语言描述这张图片\"
          },
          {
            \"type\": \"image_url\",
            \"image_url\": {
              \"url\": \"${image_base64}\"
            }
          }
        ]
      }
    ]
  }"
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "id": "018ec23da38c7e2cbbe2f669c7b62483",
    "object": "chat.completion",
    "created": 1710145618,
    "model": "step-5-preview",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "在黄昏的柔和光线下，一座现代化的建筑映入眼帘，它拥有鲜明的红色外观，与周围环境形成鲜明对比。这座建筑的底层设有宽敞的玻璃窗，为室内提供了充足的自然光。建筑的一侧有醒目的标识，顶部的窗户排列整齐，展现了现代设计的风格。\n\n在建筑前的空地上，有一棵光秃的树，其枝条在微风中轻轻摇曳。树下是一片铺着碎石的土地，为这个空间增添了一丝自然的气息。在空地的一侧，还可以看到几个小巧的灯具，它们发出的温暖光线在傍晚显得格外温馨。\n\n建筑周围环境整洁，道路上没有车辆，显得非常宁静。远处可以看到其他建筑的轮廓，以及天空中即将落下的太阳，为这幅画面增添了丰富的层次感。整个场景透露出一种宁静而有序的都市生活氛围。"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 497,
        "completion_tokens": 169,
        "total_tokens": 666
    }
}
```

**流式响应**

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

completion = client.chat.completions.create(
    model="step-5-preview",
    stream=True,
    messages=[
        {
            "role": "system",
            "content": "你是由阶跃星辰提供的AI聊天助手，你擅长中文，英文，以及多种其他语言的对话。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容",
        },
        {"role": "user", "content": "你好，请在64字数以内介绍一下阶跃星辰的人工智能!"},
    ],
)

for chunk in completion:
    print(chunk)
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

async function main() {
    const completion = await openai.chat.completions.create({
        model: "step-5-preview",
        stream: true,
        messages: [
            {
                role: "system",
                content: "你是由阶跃星辰提供的AI聊天助手，你擅长中文，英文，以及多种其他语言的对话。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容"
            },
            {
                role: "user",
                content: "你好，请在64字数以内介绍一下阶跃星辰的人工智能!"
            }
        ]
    });

    for await (const chunk of completion) {
        console.log(JSON.stringify(chunk));
    }
}

main();
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "stream": true,
    "messages": [
      {
        "role": "system",
        "content": "你是由阶跃星辰提供的AI聊天助手，你擅长中文，英文，以及多种其他语言的对话。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容"
      },
      {
        "role": "user",
        "content": "你好，请在64字数以内介绍一下阶跃星辰的人工智能!"
      }
    ]
  }'
```

```text filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":0,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":""}],"usage":{"prompt_tokens":0,"completion_tokens":0,"total_tokens":0}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"阶"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":1,"total_tokens":91}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"跃"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":2,"total_tokens":92}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"星辰"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":3,"total_tokens":93}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"AI"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":4,"total_tokens":94}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"，"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":5,"total_tokens":95}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"智能"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":6,"total_tokens":96}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"安全"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":7,"total_tokens":97}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"，"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":8,"total_tokens":98}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"多"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":9,"total_tokens":99}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"语言"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":10,"total_tokens":100}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"，"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":11,"total_tokens":101}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"快速"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":12,"total_tokens":102}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"精准"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":13,"total_tokens":103}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"，"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":14,"total_tokens":104}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"拒绝"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":15,"total_tokens":105}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"不良"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":16,"total_tokens":106}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"，"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":17,"total_tokens":107}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"用"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":18,"total_tokens":108}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"科技"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":19,"total_tokens":109}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"创造"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":20,"total_tokens":110}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"美好"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":21,"total_tokens":111}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"未来"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":22,"total_tokens":112}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":"。"},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":23,"total_tokens":113}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":""},"finish_reason":""}],"usage":{"prompt_tokens":90,"completion_tokens":24,"total_tokens":114}}

data: {"id":"d4ca43cd-83a7-4012-9ee7-b8f143eb1f8f","object":"chat.completion.chunk","created":1710146871,"model":"step-5-preview","choices":[{"index":0,"delta":{"role":"","content":""},"finish_reason":"stop"}],"usage":{"prompt_tokens":90,"completion_tokens":24,"total_tokens":114}}

data: [DONE]

```


# Messages API
Source: https://platform.stepfun.com/docs/zh/api-reference/chat/messages-create



以 Anthropic Messages API 兼容的格式调用 Step 模型，支持流式输出、工具调用、图片输入与思考深度配置。

## 请求地址

Claude Code 与 Anthropic SDK 使用配置 Base URL，并自动追加 `/v1/messages`；curl 使用完整请求地址。工具配置见 [Claude Code 接入指南](/docs/zh/guides/developer/integrations/claude-code)。

| 通道 | 配置 Base URL | 完整请求地址 |
| - | - | - |
| 普通 API | `https://api.stepfun.com` | `POST https://api.stepfun.com/v1/messages` |
| Step Plan | `https://api.stepfun.com/step_plan` | `POST https://api.stepfun.com/step_plan/v1/messages` |

## 请求参数

请求支持以下顶层字段：

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | 模型 ID，例如 `step-5-preview`、`step-3.7-flash` 或 `step-3.5-flash`。`step-router-v1` 仅可通过 [Step Plan](/docs/zh/step-plan/overview) 通道调用，字段差异见下文。 |
| `messages` | object array | 是 | 对话消息列表，至少一条。每条消息包含 `role`（`user` / `assistant`）和 `content`（纯文本或内容块数组）。 |
| `max_tokens` | int | 是 | 最大生成 token 数，必须大于 0。 |
| `system` | string or array | 否 | 系统提示词，可传字符串或文本块数组。 |
| `tools` | object array | 否 | 工具定义列表，每项包含 `name`、`description` 和 `input_schema`（JSON Schema）。 |
| `output_config` | object | 否 | 输出配置。`effort` 控制思考深度：支持三档的模型可选 `low` / `medium` / `high`；`step-3.5-flash-2603` 兼容 `low`、`high` 两档。 |
| `stream` | boolean | 否 | 是否启用流式返回，默认非流式。 |
| `temperature` | float | 否 | 采样温度，范围为 0 到 2。 |
| `top_p` | float | 否 | Nucleus sampling 参数，大于 0 且小于等于 1。 |
| `top_k` | int | 否 | Top-k 参数，范围为 0 到 500。 |
| `stop_sequences` | string array | 否 | 停止序列列表，生成内容中遇到任意一个停止序列时停止生成。 |

### 消息内容格式

`messages` 中每条消息的 `content` 可为纯文本（string），或由以下对象组成的内容块数组：

| 块 | type | 字段 |
| - | - | - |
| 文本块 | `text` | `text`：文本内容。 |
| 图片块 | `image` | `source` 支持 URL 写法 `{"type":"url","url":"https://..."}`，或 Base64 写法 `{"type":"base64","media_type":"image/png","data":"..."}`。 |
| 工具调用块（模型发起） | `tool_use` | `id`：唯一标识；`name`：工具名；`input`：参数对象。 |
| 工具结果块（用户回传） | `tool_result` | `tool_use_id`：对应调用 ID；`content`：执行结果；`is_error`：是否出错。 |

## step-router-v1 字段限制

`step-router-v1` 仅支持 Step Plan 通道，在 `deepseek-v4-pro` 与 `step-3.7-flash` 之间自动路由。以下限制仅适用于该模型，其余字段遵循上述请求参数。

| 字段 | 调用 step-router-v1 时的行为 |
| - | - |
| `model` | 路由模型 ID 为 `step-router-v1`；无效的路由模型名称返回 HTTP 400 `request_params_invalid`。 |
| `max_tokens` | 上限为 250K |
| `messages.content` 中的图像块 / 文档块 | 不支持，使用会返回 `unsupported_content_type` |
| `tools` 中的 `web_search` | 不支持，使用会返回 `unsupported_content_type` |
| `output_config.effort` | 字段会被忽略 |

## 请求响应

### 非流式响应

`Content-Type: application/json`

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "id": "msg_xxx",
    "type": "message",
    "role": "assistant",
    "model": "step-5-preview",
    "stop_reason": "end_turn",
    "usage": {
        "input_tokens": 20,
        "output_tokens": 12
    },
    "content": [
        {
            "type": "text",
            "text": "我是一个 AI 助手。"
        }
    ]
}
```

#### 响应字段说明

| 字段 | 类型 | 说明 |
| - | - | - |
| `id` | string | 消息的唯一标识。 |
| `type` | string | 对象类型，总是为 `message`。 |
| `role` | string | 角色名称，总是为 `assistant`。 |
| `model` | string | 本次响应使用的模型 ID。 |
| `content` | object array | 返回内容块列表，可能包含 `text`、`thinking` 或 `tool_use`。 |
| `stop_reason` | string | 生成停止原因，可选值为 `end_turn`、`tool_use`、`max_tokens`。 |
| `usage` | object | Token 用量统计，包含 `input_tokens` 与 `output_tokens`；缓存命中时可能包含缓存用量字段。 |

### 流式响应

`Content-Type: text/event-stream`

流式返回采用标准 SSE 格式，每个事件包含 `event:` 和 `data:` 两部分，`data:` 的内容为 JSON。

常见事件类型：`message_start`、`content_block_start`、`content_block_delta`、`content_block_stop`、`message_delta`、`message_stop`、`ping`

当返回工具调用参数时，`content_block_delta.delta.type` 可能为 `input_json_delta`。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event: message_start
data: {"type":"message_start","message":{"id":"msg_xxx","type":"message","role":"assistant","model":"step-5-preview","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":20,"output_tokens":1}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"你"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":12}}

event: message_stop
data: {"type":"message_stop"}
```

## 示例

将 `YOUR_STEP_API_KEY` 替换为实际密钥；使用环境变量的示例需先设置 `STEP_API_KEY`。按所用通道选择普通 API 或 Step Plan。

**基础对话**

**普通 API**

```python Python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from anthropic import Anthropic

client = Anthropic(api_key="YOUR_STEP_API_KEY", base_url="https://api.stepfun.com")

message = client.messages.create(
    model="step-5-preview",
    max_tokens=1024,
    system="你是由阶跃星辰提供的AI聊天助手，你擅长中文、英文及多种语言。在保证用户数据安全的前提下，快速精准地回答用户问题。",
    messages=[
        {
            "role": "user",
            "content": "请用一句话介绍你自己。"
        }
    ],
)

print(message)
```

```js JavaScript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com"
});

async function main() {
    const message = await client.messages.create({
        model: "step-5-preview",
        max_tokens: 1024,
        system: "你是由阶跃星辰提供的AI聊天助手，你擅长中文、英文及多种语言。在保证用户数据安全的前提下，快速精准地回答用户问题。",
        messages: [
            {
                role: "user",
                content: "请用一句话介绍你自己。"
            }
        ]
    });

    console.log(JSON.stringify(message));
}

main();
```

```bash cURL theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "max_tokens": 1024,
    "system": "你是由阶跃星辰提供的AI聊天助手，你擅长中文、英文及多种语言。在保证用户数据安全的前提下，快速精准地回答用户问题。",
    "messages": [
        {
            "role": "user",
            "content": "请用一句话介绍你自己。"
        }
    ]
}'
```

```json filename="响应示例" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
    "type": "message",
    "role": "assistant",
    "model": "step-5-preview",
    "stop_reason": "end_turn",
    "usage": {
        "input_tokens": 35,
        "output_tokens": 20
    },
    "content": [
        {
            "type": "text",
            "text": "我是阶跃星辰提供的AI聊天助手，能够用中文、英文等多种语言快速精准地回答您的问题。"
        }
    ]
}
```

**Step Plan**

```python Python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["STEP_API_KEY"],
    base_url="https://api.stepfun.com/step_plan",
)

message = client.messages.create(
    model="step-5-preview",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Reply with OK."
        }
    ],
)

print(message.content)
```

```js JavaScript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
    apiKey: process.env.STEP_API_KEY,
    baseURL: "https://api.stepfun.com/step_plan"
});

async function main() {
    const message = await client.messages.create({
        model: "step-5-preview",
        max_tokens: 1024,
        messages: [
            {
                role: "user",
                content: "Reply with OK."
            }
        ]
    });

    console.log(message.content);
}

main();
```

```bash cURL theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export STEP_API_KEY="YOUR_STEP_API_KEY"

curl https://api.stepfun.com/step_plan/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${STEP_API_KEY}" \
  -d '{
    "model": "step-5-preview",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": "Reply with OK."
        }
    ]
}'
```

```json filename="响应示例" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "id": "msg_xxx",
    "type": "message",
    "role": "assistant",
    "model": "step-5-preview",
    "stop_reason": "end_turn",
    "usage": {
        "input_tokens": 20,
        "output_tokens": 1
    },
    "content": [
        {
            "type": "text",
            "text": "OK"
        }
    ]
}
```

**流式响应**

**普通 API**

```python Python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from anthropic import Anthropic

client = Anthropic(api_key="YOUR_STEP_API_KEY", base_url="https://api.stepfun.com")

with client.messages.stream(
    model="step-5-preview",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "请用一句话介绍你自己。"
        }
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

print()
```

```js JavaScript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com"
});

async function main() {
    const stream = client.messages.stream({
        model: "step-5-preview",
        max_tokens: 1024,
        messages: [
            {
                role: "user",
                content: "请用一句话介绍你自己。"
            }
        ]
    });

    for await (const event of stream) {
        if (
            event.type === "content_block_delta" &&
            event.delta.type === "text_delta"
        ) {
            process.stdout.write(event.delta.text);
        }
    }

    console.log();
}

main();
```

```bash cURL theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
        {
            "role": "user",
            "content": "请用一句话介绍你自己。"
        }
    ]
}'
```

**Step Plan**

```python Python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["STEP_API_KEY"],
    base_url="https://api.stepfun.com/step_plan",
)

with client.messages.stream(
    model="step-5-preview",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Reply with OK."
        }
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

print()
```

```js JavaScript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
    apiKey: process.env.STEP_API_KEY,
    baseURL: "https://api.stepfun.com/step_plan"
});

async function main() {
    const stream = client.messages.stream({
        model: "step-5-preview",
        max_tokens: 1024,
        messages: [
            {
                role: "user",
                content: "Reply with OK."
            }
        ]
    });

    for await (const event of stream) {
        if (
            event.type === "content_block_delta" &&
            event.delta.type === "text_delta"
        ) {
            process.stdout.write(event.delta.text);
        }
    }

    console.log();
}

main();
```

```bash cURL theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export STEP_API_KEY="YOUR_STEP_API_KEY"

curl https://api.stepfun.com/step_plan/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${STEP_API_KEY}" \
  -d '{
    "model": "step-5-preview",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
        {
            "role": "user",
            "content": "Reply with OK."
        }
    ]
}'
```

**使用 output\_config.effort**

**普通 API**

```python Python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from anthropic import Anthropic

client = Anthropic(api_key="YOUR_STEP_API_KEY", base_url="https://api.stepfun.com")

message = client.messages.create(
    model="step-5-preview",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "请用三句话解释什么是强化学习。"
        }
    ],
    extra_body={
        "output_config": {
            "effort": "medium"
        }
    }
)

print(message)
```

```bash cURL theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": "请用三句话解释什么是强化学习。"
        }
    ],
    "output_config": {
        "effort": "medium"
    }
}'
```

**Step Plan**

```python Python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["STEP_API_KEY"],
    base_url="https://api.stepfun.com/step_plan",
)

message = client.messages.create(
    model="step-5-preview",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "请用三句话解释什么是强化学习。"
        }
    ],
    extra_body={
        "output_config": {
            "effort": "medium"
        }
    }
)

print(message)
```

```bash cURL theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export STEP_API_KEY="YOUR_STEP_API_KEY"

curl https://api.stepfun.com/step_plan/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${STEP_API_KEY}" \
  -d '{
    "model": "step-5-preview",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": "请用三句话解释什么是强化学习。"
        }
    ],
    "output_config": {
        "effort": "medium"
    }
}'
```


# 错误码
Source: https://platform.stepfun.com/docs/zh/api-reference/error-codes



本指南包括您可能从 API 中看到的错误码以及描述信息，描述信息中包含了每个错误码的原因以及进一步的解决方案。

## 常见错误码

| 错误码 | 原因 | 解决方案 |
| :-: | - | - |
| 400 | 请求参数格式不正确，可能原因如下：    1.图片无法下载   2.图片数量超过限制   3.该模型不支持视频输入    4.模型不存在或无权限   5.参数值不合法 | 请参照文档正确传递参数信息 |
| 401 | 认证无效 | 确保使用正确的 API 密钥 |
| 402 | 余额不足 | 确保账户里面有足够余额 |
| 404 | 请求路径不正确 | 请参照文档修复请求路径信息 |
| 429 | 请求的资源超限，可能原因是您发送请求太快，超过了速率限 | 请稍候重试您的请求 |
| 451 | 请求内容或者响应内容未审核通过 | 修改请求信息后再重试 |
| 500 | 我们服务器上的问题 | 稍等片刻后重试请求，如果问题仍然存在，请联系我们 |
| 503 | 目前服务器负载过高 | 请稍候重试您的请求 |

## 组织额度相关错误码

使用[企业套餐](/docs/zh/guides/organization/overview)的项目密钥调用时，组织 Credit 不足或达到额度上限会返回以下错误。其中两种情况的错误码与速率限制相同，请以错误标识区分。

| 错误码 | 错误标识 | 原因 | 解决方案 |
| :-: | - | - | - |
| 402 | `insufficient_credit` | 组织的 Credit 账户余额不足 | 由主账号联系销售补充 Credit |
| 429 | `project_credit_limit_exceeded` | 项目达到当期 Credit 上限 | 由主账号调高项目上限，或等待下月 1 号重置 |
| 429 | `member_project_credit_limit_exceeded` | 成员在该项目内达到当期 Credit 上限 | 由主账号调高该成员的上限，或等待下月 1 号重置 |

额度规则的完整说明见 [组织 Credit 额度规则](/docs/zh/guides/organization/credits)。


# 上传文件
Source: https://platform.stepfun.com/docs/zh/api-reference/files/create



上传一个文件到文件服务

## 请求地址

`POST https://api.stepfun.com/v1/files`

## 请求体

* `purpose` `string` ***required***\
  文件上传的意图，支持 `file-extract` 、 `retrieval-text` 、`retrieval-image` 和 `storage` 等四种类型；
  * `file-extract`: 用于提取文件内容
  * `retrieval-text` 用于文本知识库
  * `retrieval-image` 用于图片知识库
  * `storage` 用于图片理解、视频理解、音色复刻等功能。

* `url` `string` ***optional***\
  &#x20;远程文件的 URL ，支持 文件格式等同于 file 字段支持的文件格式；同时传 file 和 url 字段，取 file 字段内容。

* `file` `File` ***optional***\
  用于上传的文件。限制单个用户上传文件 1000 个；当传入 url 时，可不传入此字段。\

  `file-extract` 和 `retrieval-text` 支持的文件格式,文件大小限制为 64M；

  * 纯文本（.txt,.md）
  * PDF(.pdf)
  * Word（doc,docx）
  * Excel（xls,xlsx）
  * PPT(ppt,pptx)
  * CSV(.csv)
  * HTML/XML(.html,.htm,.xml)

  `storage` 支持的文件格式,文件大小限制为 128M；

  * 视频（mp4）
  * 图片（jpg/jpeg、png、webp、静态 gif）
  * 音频文件（mp3、wav），用于音色复刻时，音频时长为 5\~10 秒。

  `retrieval-image` 支持的文件格式,文件大小限制为 64M；

  * 图片（jpg、png）

## 请求响应

返回单个[File 对象](/docs/zh/api-reference/files/object)

## 示例

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

client.files.create(
    file=open("salesOverview.pdf", "rb"),
    purpose="file-extract"
)
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";
import fs from "fs";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

async function main() {
    const file = await openai.files.create({
        file: fs.createReadStream("salesOverview.pdf"),
        purpose: "file-extract"
    });

    console.log(file);
}

main();
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/files \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -F purpose="file-extract" \
  -F file="@salesOverview.pdf"
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "file-abc123",
  "object": "file",
  "bytes": 140,
  "created_at": 1613779121,
  "filename": "salesOverview.pdf",
  "purpose": "file-extract",
  "status": "processed"
}
```

## 备注

* 原 `purpose` 为 `retrieval`，现已废弃，建议使用 `retrieval-text` 替代。`retrieval` 将于 2025 年 5 月 15 日下线。


# 删除单个文件
Source: https://platform.stepfun.com/docs/zh/api-reference/files/delete



删除单个已经上传的文件

## 请求地址

`DELETE https://api.stepfun.com/v1/files/{file_id}`

## 路径参数

* `file_id` `string` ***required***

  文件的唯一标识 id

## 请求响应

返回单个[文件对象](/docs/zh/api-reference/files/object)

## 示例

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

print(client.files.delete("file-stepabc"))
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

async function main() {
    const file = await openai.files.del("file-stepabc");
    console.log(file);
}

main();
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/files/file-abc123 \
  -X DELETE \
  -H "Authorization: Bearer $STEP_API_KEY"
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "file-stepabc",
  "object": "file",
  "deleted": true
}
```


# 获取文件列表
Source: https://platform.stepfun.com/docs/zh/api-reference/files/list



获取当前用户下所有可用的文件列表

## 请求地址

`GET https://api.stepfun.com/v1/files`

## 请求参数

无

## 请求响应

返回[File 对象](/docs/zh/api-reference/files/object)列表

## 示例

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

client.files.list()
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

async function main() {
    const list = await openai.files.list();

    for await (const file of list) {
        console.log(file);
    }
}

main();
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/files \
  -H "Authorization: Bearer $STEP_API_KEY"
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "data": [
    {
      "id": "file-abc123",
      "object": "file",
      "bytes": 175,
      "created_at": 1613677385,
      "filename": "salesOverview.pdf",
      "purpose": "file-extract",
      "status": "success"
    },
    {
      "id": "file-abc123",
      "object": "file",
      "bytes": 140,
      "created_at": 1613779121,
      "filename": "puppy.pdf",
      "purpose": "retrieval",
      "status": "success"
    }
  ],
  "object": "list"
}
```


# File 对象
Source: https://platform.stepfun.com/docs/zh/api-reference/files/object



单个 File 对象的描述信息

## 属性

* `id` `string`\
  File 的唯一 ID
* `object` `string`\
  对象类型，此处总为 `file`
* `bytes` `int`\
  文件大小
* `created_at` `int`\
  File 的创建时间，类型为 Unix 时间戳，单位 s
* `filename` `string`\
  文件名
* `purpose` `string`\
  上传意图，可选项为  `file-extract` 、 `retrieval-text`  、`retrieval-image`  和 `storage`。
* `status` `string`\
  处理状态，可选项为 `success` 和 `processed`

## 示例

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "id": "file-abc123",
    "object": "file",
    "bytes": 140,
    "created_at": 1613779121,
    "filename": "salesOverview.pdf",
    "purpose": "file-extract",
}
```


# 查询单个文件的信息
Source: https://platform.stepfun.com/docs/zh/api-reference/files/retrieve



查询单个 File 的信息，包括创建时间，所属组织等。

## 请求地址

`GET https://api.stepfun.com/v1/files/{file_id}`

## 路径参数

* `file_id` `string` ***required***

  文件唯一标识 ID

## 请求响应

返回单个[File 对象](/docs/zh/api-reference/files/object)

## 示例

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

print(client.files.retrieve("file-stepab"))
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

async function main() {
    const file = await openai.files.retrieve("file-stepab");

    console.log(file);
}

main();
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/files/file-abc \
  -H "Authorization: Bearer $STEP_API_KEY"
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "file-abc123",
  "object": "file",
  "bytes": 140,
  "created_at": 1613779121,
  "filename": "salesOverview.pdf",
  "purpose": "file-extract",
  "status": "success"
}
```


# 获取文件内容
Source: https://platform.stepfun.com/docs/zh/api-reference/files/retrieve-content



获取指定文件的内容（仅支持 purpose 为 file-extract 的文件获取内容）

## 请求地址

`GET https://api.stepfun.com/v1/files/{file_id}/content`

## 路径参数

* `file_id` `string` ***required***

  文件的唯一标识 id

## 请求响应

返回文件解析后的纯文本内容。

## 示例

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

content = client.files.content("file-abc123")
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

async function main() {
    const file = await openai.files.content("file-abc123");

    console.log(file);
}

main();
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/files/file-abc123/content \
  -H "Authorization: Bearer $STEP_API_KEY"
```

```text filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
文件内容
```


# 查询 Model 列表
Source: https://platform.stepfun.com/docs/zh/api-reference/models/list



显示当前所有可用的模型，模型信息包括创建时间，所属组织等。

## 请求地址

`GET https://api.stepfun.com/v1/models`

## 请求参数

无

## 请求响应

返回[Model 对象](/docs/zh/api-reference/models/object)列表

## 示例

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

print(client.models.list())
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

async function main() {
    const list = await openai.models.list();

    for await (const model of list) {
        console.log(model);
    }
}

main();
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/models \
  -H "Authorization: Bearer $STEP_API_KEY"
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "object": "list",
  "data": [
    {
      "id": "step-5-preview",
      "object": "model",
      "created": 1789747200,
      "owned_by": "stepai"
    },
    {
      "id": "step-3.7-flash",
      "object": "model",
      "created": 1713196800,
      "owned_by": "stepai"
    },
    {
      "id": "step-3.5-flash",
      "object": "model",
      "created": 1713974400,
      "owned_by": "stepai"
    },
    {
      "id": "step-3.5-flash-2603",
      "object": "model",
      "created": 1711015200,
      "owned_by": "stepai"
    },
    {
      "id": "step-1o-turbo-vision",
      "object": "model",
      "created": 1711015200,
      "owned_by": "stepai"
    }
  ]
}
```


# model 对象
Source: https://platform.stepfun.com/docs/zh/api-reference/models/object



单个 Model 对象的描述信息数据

## 属性

* `id` `string`\
  模型的唯一标识 ID
* `created` `int`\
  模型的创建时间，类型为 Unix 时间戳，单位 s
* `object` `string`\
  对象类型，此处总为 `model`
* `owned_by` `string`\
  模型所属的组织名称

## 示例

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "step-5-preview",
  "object": "model",
  "created": 1789747200,
  "owned_by": "stepai"
}
```


# 查询单个 Model 信息
Source: https://platform.stepfun.com/docs/zh/api-reference/models/retrieve



查询单个 Model 的信息，包括创建时间，所属组织等。

## 请求地址

`GET https://api.stepfun.com/v1/models/{model}`

## 路径参数

* `model` `string` ***required***

  模型唯一标识 ID

## 请求响应

返回单个[Model 对象](/docs/zh/api-reference/models/object)

## 示例

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

print(client.models.retrieve("step-5-preview"))
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

async function main() {
    const model = await openai.models.retrieve("step-5-preview");

    console.log(model);
}

main();
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/models/step-5-preview \
  -H "Authorization: Bearer $STEP_API_KEY"
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "step-5-preview",
  "object": "model",
  "created": 1789747200,
  "owned_by": "stepai"
}
```


# 双向实时语音
Source: https://platform.stepfun.com/docs/zh/api-reference/realtime/chat



开启实时语音通话能力，支持语音和文本输入，并支持输出音频。

## 快速体验

我们提供了模型体验中心，您可以点击下方链接快速体验阶跃星辰语音模型的能力。

* [语音克隆](https://www.stepfun.com/studio/audio?tab=clone) - 上传 5-10 秒音频即可复刻您的专属音色，支持多种情感方案，适用于个性化语音生成场景。
* [实时对话](https://www.stepfun.com/studio/audio?tab=voice-chat) - 提供极低延迟的双向语音流式交互，支持服务端 VAD 和 联网搜索，适用于智能助手和客服场景。
* [语音推理](https://www.stepfun.com/studio/audio?tab=conversation) - 具备深度声音理解能力，能听懂语气背后的深意，通过边想边说的推理模式，大幅提高对话质量。

同时也提供了开源的 Realtime API Demo 供您参考：[Step-Realtime-Console](https://github.com/stepfun-ai/Step-Realtime-Console)。

## 请求方式

WebSocket

## 请求地址

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
wss://api.stepfun.com/v1/realtime
```

## 请求头

* `Authorization` `string` ***required*** \
  &#x20;鉴权使用的 KEY，其值为 `Bearer YOUR_STEP_API_KEY`

## 请求参数

* `model` `string` ***required***\
  需要使用的模型名称，当前支持 `stepaudio-3-realtime-preview`、`stepaudio-2.5-realtime`、`step-1o-audio`、`step-audio-2`、`step-audio-2-mini`、`step-audio-r1.5`。

> [!NOTE]
>
> Artificial Analysis 榜单数据基于内部参数配置，实际 API 服务表现可能与榜单结果存在差异，相关配置将在后续 API 版本中逐步开放。

## 调用说明

Realtime API 需要在服务链接成功后，发送对应的 Client Event ，获取对应的 Server Event ，来完成交互。

### 公共参数

以下为 Client Event 和 Server Event 的公共参数

| **字段名** | **类型** | **描述** |
| - | - | - |
| event\_id | string | 事件 ID |
| type | string | Event 类型，可选项见下方说明 |

## Client Event 列表

### 创建/更新 session

type: `session.update`

发送此事件以创建或更新会话的默认配置。客户端可以随时发送此事件来更新 session 配置，任何字段都可能随时更新，除了 "voice" 之外。服务器将使用 `session.updated` 事件进行响应。

* `modalities` `array<string>`\
  模型可以使用的模态集。 固定为 `["text", "audio"]`

* `instructions` `string`\
  默认系统指令（即 system message）附加到 model 调用之前。此字段允许客户端指导模型获得所需的响应。该模型可以被指导回答内容和格式（例如，"要非常简洁"、"行为友好"、"这里有好回应的示例"）和音频行为（例如，"快声说"、"在你的声音中注入情感"、"经常大笑"）。不能保证模型会遵循这些说明，但它们会为模型提供有关所需行为的指导。

* `voice` `string`\
  生成时使用的音色信息，支持[官方音色](/docs/zh/guides/developer/tts#官方音色清单)，和自定义音色。自定义音色传入对应的音色 ID 即可，可以通过[查询音色列表](/docs/zh/api-reference/audio/list-voice)查看当前可用的音色 ID。

  如果需要使用复刻音色，则需要使用[音色复刻](/docs/zh/api-reference/audio/create-voice)获取的 voiceid。

  * `stepaudio-2.5-realtime` 模型的对应音色复刻生成效果和 StepAudio 2.5 TTS 相当，可以使用 StepAudio 2.5 TTS 试听复刻效果。实际复刻时，使用 StepAudio 2.5 TTS 作为复刻的模型。

  如果使用 `step-audio-2-mini`，支持 `qingchunshaonv`（青春少女）和 `wenrounansheng`（温柔男声），且需要在 instructions 结尾处对应添加"请使用默认男声与用户交流"或"请使用默认女声与用户交流"。

  如果使用 `step-audio-2`，支持 `qingchunshaonv`（青春少女），`wenrounansheng`（温柔男声），`elegantgentle-female`（高雅女声），`livelybreezy-female`（活力女声）。之外，模型支持音色克隆，您可以上传音色片段获取自定义 voice，参考[音色复刻](/docs/zh/api-reference/audio/create-voice)。

* `turn_detection` `object` optional\
  ServerVAD 参数，默认关闭
  * `type` `string` ***required***\
    当前仅支持 `server_vad`， 配置后开启服务端 VAD。
  * `prefix_padding_ms` `integer` ***optional***\
    只在 type 为 `server_vad` 时有效，当检测到用户语音开始时，回溯添加的前置音频时长，单位为毫秒，默认值为 500 毫秒。
  * `silence_duration_ms` `integer` ***optional***\
    只在 type 为 `server_vad` 时有效，静音检测时长，单位为毫秒，默认值为 100 毫秒，当检测到用户语音结束后，静音达到该时长则认为用户语音输入结束。
  * `energy_awakeness_threshold` `integer` ***optional***\
    只在 type 为 `server_vad` 时有效，能量唤醒阈值，范围为0-5000，默认值为 2500，当音频能量超过该阈值时认为用户开始说话。

* `input_audio_format` `string`\
  输入音频的格式。 当前仅支持 `pcm16`

* `output_audio_format` `string`\
  输出音频的格式。 当前仅支持 `pcm16`

* `tools` `object array` ***optional***\
  Toolcall 支持的函数列表
  * `type` `string`\
    工具类型，总是为 `function`、`retrieval`
  * `function` `object`\
    函数内容的描述

    * `name` `string`\
      函数名称，要求纯英文、数字和\_-符号，建议不要超过64个字符长度。
    * `description` `string`\
      函数描述，支持中英文，它用于告诉模型函数实现何种功能和目的，方便模型来判断和选择。
    * `parameters` `object`\
      函数的参数
      * `type` `object`\
        参数描述，一般为 object
      * `properties` `object`\
        函数参数内容，以 key 为参数的名称，然后通过 `type` 和 `description` 描述参数的类型和介绍。
        * `type` `string|number|integer|object|array|boolean`\
          参数类型，可以参考[json-schema](https://json-schema.org/understanding-json-schema/reference/type)介绍
        * `description` `string`\
          函数参数描述，支持中英文，它用于告诉模型函数参数的含义。

    当 type 为 `retrieval` 时

    * `description` `string`\
      函数描述，支持中英文，它用于告诉模型函数实现何种功能和目的，方便模型来判断和选择。
    * `options` `object`\
      函数的参数
      * `vector_store_id` `string`\
        知识库的 ID
      * `prompt_template` `string`\
        知识库召回内容插入文档的模板。默认为 `从文档{{knowledge}}中找到问题{{query}}的答案。根据文档内容中的语句找到答案, 如果文档中没用答案则告诉用户找不到`，其中 `{{knowledge}}` 为召回的内容、 `{{query}}` 为用户的查询内容。可以根据实际情况修改。

**Sample**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_abc",
    "type": "session.update",
    "session": {
        "modalities": ["text", "audio"],
        "instructions": "你是由阶跃星辰提供的AI聊天助手，你擅长中文，英文，以及多种其他语言的对话。",
        "voice": "linjiajiejie",
        "input_audio_format": "pcm16",
        "output_audio_format": "pcm16",
        "tools": [
            {
                "type": "retrieval",
                "function": {
                    "description": "本知识库可以回答用户十万个为什么相关问题",
                    "options": {
                        "vector_store_id": "164643690285936640",
                        "prompt_template": "从文档{{knowledge}}中找到问题{{query}}的答案。根据文档内容中的语句找到答案, 如果文档中没用答案则告诉用户找不到"
                    }
                }
            },
            {
                "type": "retrieval",
                "function": {
                    "description": "本知识库可以回答用户redis安装等相关问题",
                    "options": {
                        "vector_store_id": "164643837904470016",
                        "prompt_template": "从文档{{knowledge}}中找到问题{{query}}的答案。根据文档内容中的语句找到答案, 如果文档中没用答案则告诉用户找不到"
                    }
                }
            }
        ],
        "turn_detection": {
            "type": "server_vad",
            "prefix_padding_ms": 500
        }
    }
}
```

### 音频内容追加

type: `input_audio_buffer.append`

发送此事件以将音频字节追加到输入音频缓冲区，服务器不会向此事件发送确认响应，在 ServerVAD 模式下会触发大模型推理。

* `audio` `string`\
  编码的音频 Base64编码字节。必须采用会话配置中 input\_audio\_format 字段指定的格式。

**Sample**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_abc",
    "type": "input_audio_buffer.append",
    "audio": "Base64EncodedAudioData"
}
```

### 音频内容提交

type: `input_audio_buffer.commit`

发送此事件以提交用户输入音频缓冲区进行推理，将在对话中创建新的用户消息项，服务器将使用 `input_audio_buffer.committed` 事件进行响应。如果输入音频缓冲区为空，则此事件将产生错误。

**Sample**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_abc",
    "type": "input_audio_buffer.commit"
}
```

### 音频内容清理

type:  `input_audio_buffer.clear`

发送此事件以提交用户输入音频缓冲区进行清理，服务器将使用 input\_audio\_buffer.cleared 事件进行响应。

**Sample**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_abc",
    "type": "input_audio_buffer.clear"
}
```

### 会话消息添加

type:  `conversation.item.create`

将新会话添加到会话上下文中，包括消息、函数调用和函数调用响应。此事件既可用于填充对话的 "历史记录" ，也可用于在途中添加新消息项，但当前限制是它无法填充 Assistant 音频消息。如果成功，服务器将使用 `conversation.item.created` 事件进行响应，否则将发送错误事件。

* `previous_item_id` `string`\
  前一项消息的 ID

* `content` `string`\
  消息的内容，适用于消息项，见消息参数

**Sample**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_abc",
    "type": "conversation.item.create",
    "item": {
        "id": "msg_001",
        "type": "message",
        "role": "user",
        "content": [
            {
                "type": "input_text",
                "text": "你好"
            }
        ]
    }
}
```

### 会话消息删除

type:  `conversation.item.delete`

当您想从对话历史记录中删除任何 item 时，发送此事件。服务器将使用 conversation.item.deleted 事件进行响应，当该 item 在对话历史记录中不存在，服务器将响应错误。

* `item_id` `string`\
  想删除的消息 ID

**Sample**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_abc",
    "type": "conversation.item.delete",
    "item_id": "msg_003"
}
```

### 推理提交

type:  `response.create`

此事件指示服务器创建 Response，这意味着触发模型推理，服务端会返回

**Sample**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_abc",
    "type": "response.create"
}
```

### 推理取消

type:  `response.cancel`

将此事件发送以取消正在进行的响应。服务器将返回一个 response.cancelled 事件或在没有可取消的响应时返回一个错误。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_abc",
    "type": "response.cancel"
}
```

## Server Event 列表

### 错误事件

type:  `error`

服务器执行过程中发生错误时返回，这可能是客户端问题或服务器问题，会话会继续保留。

* `type` `string`\
  错误类型（例如: "invalid\_request\_error"、"server\_error"）。

* `code` `string`\
  错误代码（如果有）。

* `message` `string`\
  可解释的错误消息。

* `event_id` `string`\
  导致错误的 client 事件的 event\_id（如果适用）。

**Sample**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_bcd",
    "type": "error",
    "error": {
        "type": "invalid_request_error",
        "code": "invalid_param",
        "message": "音频内容不完整",
        "event_id": "event_567"
    }
}
```

### 创建 session 响应

type:  `session.created`

创建 Session 时返回。当新连接建立为第一个服务器事件时自动发出。此事件将包含默认的 Session 配置。

* `modalities` `array<string>`\
  模型可以使用的模态集。 固定为 `["text", "audio"]`

* `instructions` `string`\
  默认系统指令（即 system message）附加到 model 调用之前。此字段允许客户端指导模型获得所需的响应。该模型可以被指导回答内容和格式（例如，"要非常简洁"、"行为友好"、"这里有好回应的示例"）和音频行为（例如，"快声说"、"在你的声音中注入情感"、"经常大笑"）。不能保证模型会遵循这些说明，但它们会为模型提供有关所需行为的指导。

* `voice` `string`\
  生成时使用的音色信息，支持官方音色，未来会支持自定义音色。

* `input_audio_format` `string`\
  输入音频的格式。 当前仅支持 `pcm16`

* `output_audio_format` `string`\
  输入音频的格式。 当前仅支持 `pcm16`

**sample**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_def",
    "type": "session.created",
    "session": {
        "id": "sess_001",
        "object": "realtime.session",
        "model": "step-1o-audio",
        "modalities": ["text", "audio"],
        "instructions": "你是由阶跃星辰提供的AI聊天助手，你擅长中文，英文，以及多种其他语言的对话。",
        "voice": "linjiajiejie",
        "input_audio_format": "pcm16",
        "output_audio_format": "pcm16",
        "max_response_output_tokens": "4096"
    }
}
```

### 更新 session 响应

type:  `session.updated`

更新 Session 时返回。当新连接建立为第一个服务器事件时自动发出。此事件将包含默认的 Session 配置。

**Sample**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_def",
    "type": "session.created",
    "session": {
        "modalities": ["text", "audio"],
        "instructions": "你是由阶跃星辰提供的AI聊天助手，你擅长中文，英文，以及多种其他语言的对话。",
        "voice": "wenrounansheng",
        "input_audio_format": "pcm16",
        "output_audio_format": "pcm16",
        "max_response_output_tokens": 4096
    }
}
```

### 音频输入激活开始 （VAD）

type:  `input_audio_buffer.speech_started`

输入音频的人声有效输入开始事件通知，一般用于打断场景。

* `audio_start_ms` `string`\
  音频的开始时间

* `item_id` `string`\
  项目的 ID。

**Sample**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_bcd",
    "type": "input_audio_buffer.speech_started",
    "audio_start_ms": 1000,
    "item_id": "msg_003"
}
```

### 音频输入激活结束 （VAD）

type:  `input_audio_buffer.speech_stopped`

输入音频的人声有效输入结束事件通知。

* `response_id` `string`\
  回复 id。

* `item_id` `string`\
  项目的 ID。

**Sample**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_1718",
    "type": "input_audio_buffer.speech_stopped",
    "audio_end_ms": 2000,
    "item_id": "msg_003"
}
```

### 音频内容流式返回

type:  `response.audio.delta`

更新模型生成的音频时返回。

* `response_id` `string`\
  回复 id。

* `item_id` `string`\
  项目的 ID。

* `output_index` `int`\
  响应中输出项的索引。

* `delta` `string`\
  Base64 编码的音频数据增量，音频格式同 session 创建的 output\_audio\_format

**Sample**

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_bcd",
    "type": "response.audio.delta",
    "item_id": "msg_008",
    "delta": "Base64EncodedAudioDelta"
}
```

### 音频内容流式结束

type:  `response.audio.done`

在模型生成的音频完成时返回。当 Response 中断、不完整或取消时也会发出.

* `response_id` `string`\
  回复 id。

* `item_id` `string`\
  项目的 ID。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_bcd",
    "type": "response.audio.done",
    "response_id": "traceid",
    "item_id": "msg_008"
}
```

### 音频内容文字流返回

type:  `response.audio_transcript.delta`

当客户端提交输入音频缓冲区时返回。

* `response_id` `string`\
  回复 id。

* `item_id` `string`\
  项目的 ID。

* `output_index` `int`\
  响应中输出项的索引。

* `delta` `string`\
  转录增量。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_bcd",
    "type": "response.audio_transcript.delta",
    "item_id": "msg_002",
    "output_index": 0,
    "delta": "Hello, how can I a"
}
```

### 音频内容文字流结束

type:  `response.audio_transcript.done`

当模型生成的音频输出转录完成流式处理时返回。当 Response 中断、不完整或取消时也会发出。

* `response_id` `string`\
  回复 id。

* `item_id` `string`\
  项目的 ID。

* `output_index` `int`\
  响应中输出项的索引。

* `transcript` `string`\
  音频的完整文字内容。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_4748",
    "type": "response.audio_transcript.done",
    "response_id": "resp_001",
    "item_id": "msg_008",
    "content_index": 0,
    "transcript": "Hello, how can I assist you today?"
}
```

### 推理思考流返回

type:  `response.thinking.delta`

当模型生成推理思考过程时流式返回。

* `response_id` `string`\
  回复 id。

* `item_id` `string`\
  项目的 ID。

* `output_index` `int`\
  响应中输出项的索引。

* `content_index` `int`\
  项目内容数组中内容部分的索引。

* `delta` `string`\
  思考过程的增量内容。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_thinking_delta",
    "type": "response.thinking.delta",
    "response_id": "resp_001",
    "item_id": "msg_008",
    "output_index": 0,
    "content_index": 0,
    "delta": "通过分析..."
}
```

### 推理思考流结束

type:  `response.thinking.done`

当模型推理思考过程结束时返回。

* `response_id` `string`\
  回复 id。

* `item_id` `string`\
  项目的 ID。

* `output_index` `int`\
  响应中输出项的索引。

* `content_index` `int`\
  项目内容数组中内容部分的索引。

* `thinking` `string`\
  思考过程的完整文字内容。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_thinking_done",
    "type": "response.thinking.done",
    "response_id": "resp_001",
    "item_id": "msg_008",
    "output_index": 0,
    "content_index": 0,
    "thinking": "完整思考过程..."
}
```

### 回复文字内容流式返回

type: `response.text.delta`

在模型生成的文本输出时返回。

* `response_id` `string`\
  回复 id。

* `item_id` `string`\
  响应项目的 ID。

* `output_index` `int`\
  响应中输出项的索引。

* `delta` `string`\
  生成的文本内容增量。

* `content_index` `int`\
  包含文本内容部分的索引。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_4950",
    "type": "response.text.delta",
    "response_id": "resp_001",
    "item_id": "msg_009",
    "output_index": 0,
    "content_index": 0,
    "delta": "Sure, "
}
```

### 回复文字内容流式结束

type: `response.text.done`

在模型生成的文本输出完成时返回。当 Response 中断、不完整或取消时也会发出。

* `response_id` `string`\
  回复 id。

* `item_id` `string`\
  响应项目的 ID。

* `output_index` `int`\
  响应中输出项的索引。

* `text` `string`\
  生成的完整文本内容。

* `content_index` `int`\
  包含文本内容部分的索引。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_5152",
    "type": "response.text.done",
    "response_id": "resp_001",
    "item_id": "msg_009",
    "output_index": 0,
    "content_index": 0,
    "text": "Sure, I can help with that."
}
```

### 会话消息创建响应

type: `conversation.item.created`

创建对话项时返回，服务器正在生成一个 Response，如果成功，将生成一个或两个 Item，其类型为 message；

* `id` `string`\
  消息的唯一 ID，非必需，如果客户端未提供，服务器将自动生成一个。

* `type` `string`\
  项目的类型，通常为 message

* `role` `string`\
  消息发送者的角色（用户、助手、系统），仅适用于消息项。

* `status` `string`\
  项目的状态 （completed， incomplete）。这些对会话没有影响。

* `content` `string`\
  消息的内容，适用于消息项。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"event_id": "event_bcd",
	"type": "conversation.item.created",
	"previous_item_id": "msg_001",
	"item": {
		"id": "msg_002",
		"object": "realtime.item",
		"type": "message",
		"status": "completed",
		"role": "user",
		"content": [{
			"type": "input_text",
			"transcript": "你好"
		}]
	}
}
```

### 会话消息删除响应

type: `conversation.item.deleted`

当客户端使用 `conversation.item.delete` 事件删除对话中的项目时返回。此事件用于将服务器对对话历史与客户端的进行同步。

* `item_id` `string`\
  会话消息 ID

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_bcd",
    "type": "conversation.item.deleted",
    "item_id": "msg_001"
}
```

### 用户提交音频的转录结果完成

type: `conversation.item.input_audio_transcription.completed`

此事件是写入用户音频缓冲区的用户音频的音频转录（ASR）的输出。当客户端 commit 缓存区的音频，或在 server\_vad 模式下缓冲区音频被提交时，转录开始。转录随响应创建异步运行，因此此事件可能发生在响应事件之前或之后。

* `item_id` `string`\
  会话消息 ID
* `content_index` `int`\
  包含音频内容部分的索引。
* `transcript` `string`\
  音频的完整文字内容。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_2122",
    "type": "conversation.item.input_audio_transcription.completed",
    "item_id": "msg_003",
    "content_index": 0,
    "transcript": "你好"
}
```

### 音频内容提交响应

type: `input_audio_buffer.committed`

当客户端提交输入音频缓冲区时返回。

* `previous_item_id` `string`\
  会话前一个消息 ID

* `item_id` `string`\
  会话消息 ID

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_bcd",
    "type": "input_audio_buffer.committed",
    "previous_item_id": "msg_001",
    "item_id": "msg_002"
}
```

### 音频内容删除响应

type: `input_audio_buffer.cleared`

当客户端使用 input\_audio\_buffer.clear 事件清除输入音频缓冲区时返回。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}

{
    "event_id": "event_1314",
    "type": "input_audio_buffer.cleared"
}
```

### 推理有输出项目产生

type: `response.output_item.added`

在响应生成期间创建新项目时返回。

* `output_index` `int`\
  响应中输出项的索引。

* `item` `object`\
  输出项的对象。

  * `id` `string`\
    项目的 ID。

  * object
    \
    &#x20;  始终为 `realtime.item`

  * type
    \
    &#x20; item 类型,目前仅支持 `message`

  * status
    \
    &#x20; 项目状态,可选值为 `completed`, `incomplete`,`in_progress`

  * role
    \
    &#x20;  该项目的 role， 仅适用于 message 项目，可选值为 `user`, `assistant`, `system`

  * content
    \
    &#x20;  消息的内容，适用于 message 项目。
    \
    &#x20;  role=system 的消息项仅支持 input\_text 内容
    \
    &#x20;  role=user 的消息项支持 input\_text 和 input\_audio 内容
    \
    &#x20;  role=assistant 角色支持文本内容的消息项。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_3334",
    "type": "response.output_item.added",
    "response_id": "resp_001",
    "output_index": 0,
    "item": {
        "id": "msg_007",
        "object": "realtime.item",
        "type": "message",
        "status": "in_progress",
        "role": "assistant",
        "content": []
    }
}
```

### 推理有输出项目完成

type: `response.output_item.done`

当一个项目完成时返回。当一个响应处于以下状态时 `interrupted`, `incomplete`,  `cancelled` 也会发出。

* `output_index` `int`\
  响应中输出项的索引。

* `item` `object`\
  输出项的对象。

  * `id` `string`\
    项目的 ID。

  * object
    \
    &#x20;  始终为 `realtime.item`

  * type
    \
    &#x20; item 类型,目前仅支持 `message`

  * status
    \
    &#x20; 项目状态,可选值为 `completed`, `incomplete`,`in_progress`

  * role
    \
    &#x20;  该项目的 role， 仅适用于 message 项目，可选值为 `user`, `assistant`, `system`

  * content
    \
    &#x20;  消息的内容，适用于 message 项目。
    \
    &#x20;  role=system 的消息项仅支持 input\_text 内容
    \
    &#x20;  role=user 的消息项支持 input\_text 和 input\_audio 内容
    \
    &#x20;  role=assistant 角色支持文本内容的消息项。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_3536",
    "type": "response.output_item.done",
    "response_id": "resp_001",
    "output_index": 0,
    "item": {
        "id": "msg_007",
        "object": "realtime.item",
        "type": "message",
        "status": "completed",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "Sure, I can help with that."
            }
        ]
    }
}
```

### 推理的输出项目中有新的内容生成

type: `response.content_part.added`

在响应生成期间，当向 assistant 消息项添加新的内容部分时返回。

* `response_id` `string`\
  响应 id
* `item_id` `string`\
  对应的项目 id
* `content_index` `int`\
  项目内容数组中内容部分的索引。
* `output_index` `int`\
  响应中输出项的索引。
* `part` `object`
  * `type` `string`\
    类型，支持 `text`, `audio` 或 `thinking`
  * `audio` `string`\
    audio: base64 encode 后的音频数据（当 type=audio 时有这个字段）
  * `text` `string`\
    生成的文本内容（当 type=text 时有这个字段）
  * `thinking` `string`\
    生成的推理思考内容（当 type=thinking 时有这个字段）
  * `transcript` `string`\
    音频的转录内容 （当 type=audio 时有这个字段）

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_3738",
    "type": "response.content_part.added",
    "response_id": "resp_001",
    "item_id": "msg_007",
    "output_index": 0,
    "content_index": 0,
    "part": {
        "type": "text",
        "text": ""
    }
}
```

### 推理的输出项目中有新的内容完成

type: `response.content_part.done`

当一个 `content_part` 完成时返回。当它对应的响应处于以下状态时 `interrupted`, `incomplete`, or `cancelled` 也会发出。

* `response_id` `string`\
  响应 id
* `item_id` `string`\
  对应的项目 id
* `content_index` `int`\
  项目内容数组中内容部分的索引。
* `output_index` `int`\
  响应中输出项的索引。
* `part` `object`
  * `type` `string`\
    类型，支持 `text`, `audio` 或 `thinking`
  * `audio` `string`\
    audio: base64 encode 后的音频数据（当 type=audio 时有这个字段）
  * `text` `string`\
    生成的文本内容（当 type=text 时有这个字段）
  * `thinking` `string`\
    生成的推理思考内容（当 type=thinking 时有这个字段）
  * `transcript` `string`\
    音频的转录内容 （当 type=audio 时有这个字段）

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_3940",
    "type": "response.content_part.done",
    "response_id": "resp_001",
    "item_id": "msg_007",
    "output_index": 0,
    "content_index": 0,
    "part": {
        "type": "text",
        "text": "Sure, I can help with that."
    }
}
```

### 推理创建响应

type: `response.created`

创建新 Response 时返回。响应创建的第一个事件，其中响应的初始状态为 in\_progress。

* `id` `string`\
  响应的唯一 ID。

* `object` `string`\
  对象类型必须为:realtime.response

* `status` `string`\
  响应的最终状态 （completed， cancelled， failed， incomplete）。

* `output` `list`\
  响应生成的输出项列表。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_3132",
    "type": "response.done",
    "response": {
        "id": "resp_001",
        "object": "realtime.response",
        "status": "completed",
        "status_details": null,
        "output": [
            {
                "id": "msg_006",
                "object": "realtime.item",
                "type": "message",
                "status": "completed",
                "role": "assistant",
                "content": [
                    {
                        "type": "text",
                        "text": "Sure, how can I assist you today?"
                    }
                ]
            }
        ]
    }
}
```

### 推理结束响应

type:  `response.done`

当 Response 完成流式处理时返回。始终发出，无论最终状态如何。response.done 事件中包含的 Response 对象将包括 Response 中的所有输出 Item，但会省略原始音频数据。

* `id` `string`\
  响应的唯一 ID。

* `object` `string`\
  对象类型必须为:realtime.response

* `status` `string`\
  响应的最终状态 （completed， cancelled， failed， incomplete）。

* `output` `list`\
  响应生成的输出项列表。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "event_id": "event_bcd",
    "type": "response.done",
    "response": {
        "id": "resp_001",
        "object": "realtime.response",
        "status": "completed",
        "status_details": null,
        "output": [
            {
                "id": "msg_006",
                "object": "realtime.item",
                "type": "message",
                "status": "completed",
                "role": "assistant",
                "content": [
                    {
                        "type": "text",
                        "text": "你好"
                    }
                ]
            }
        ]
    }
}
```


# Responses API
Source: https://platform.stepfun.com/docs/zh/api-reference/responses/responses-create



调用 Responses API，获取模型生成的响应数据。该接口兼容 OpenAI Responses API 的请求与响应格式。

## 请求地址

`POST https://api.stepfun.com/v1/responses`

## 请求参数

* `model` `string` ***required***\
  需要使用的模型名称。当前支持 `step-5-preview` 和 `step-3.7-flash`。
* `input` `string or object array` ***required***\
  输入内容，可以是纯文本字符串，也可以是按时序排列的消息/事件数组。

  * 纯文本输入 `string`\
    等价于一条 `role=user` 的纯文本消息。
  * 消息/事件数组 `object array`\
    数组元素可以是以下几种类型：
    * 文本消息 `object`
      * `role` `string`\
        消息角色，可选取值：`user`、`assistant`、`system`。
      * `content` `string or object array`\
        消息内容。可以是纯文本字符串，也可以是用于多模态输入的内容块数组。
        * 纯文本内容 `string`
        * 内容块数组 `object array`
          * 文本块 `object`
            * `type` `string`\
              总为 `input_text`
            * `text` `string`\
              文本内容
          * 图片块 `object`
            * `type` `string`\
              总为 `input_image`
            * `image_url` `string or object`\
              图片地址。可直接传入字符串，或传入对象 `{ "url": "...", "detail": "high" }`。推荐使用 base64 data URL（格式 `data:image/jpeg;base64,${base64_string}`），或保证外部 URL 可被服务端公网访问。
          * 视频块 `object`
            * `type` `string`\
              总为 `input_video`
            * `video_url` `string or object`\
              视频地址。可直接传入字符串，或传入对象 `{ "url": "...", "detail": "low" }`。视频 URL 需保证可被服务端公网访问。
    * 函数调用 `object`（由模型在上一轮返回，需在多轮对话中按原样回传）
      * `type` `string`\
        总为 `function_call`
      * `id` `string`\
        函数调用唯一 ID，由服务端生成
      * `call_id` `string`\
        调用关联 ID，用于配对后续的 `function_call_output`
      * `name` `string`\
        工具名称
      * `arguments` `string`\
        JSON 字符串格式的参数
    * 函数调用结果 `object`（由客户端在执行完工具后回传）
      * `type` `string`\
        总为 `function_call_output`
      * `call_id` `string`\
        对应 `function_call` 的 `call_id`
      * `output` `string`\
        工具执行结果（建议使用 JSON 字符串）

> [!NOTE]
>
> 图片和视频 URL 必须能被服务端公网访问；如果服务端无法抓取 URL，会返回参数错误。图片输入推荐使用 base64 data URL，以避免外部 URL 鉴权、防盗链或网络访问失败。

* `instructions` `string` ***optional***\
  顶层系统级指令。
* `stream` `bool` ***optional***\
  是否启用 SSE 流式输出，默认 `false`。
* `temperature` `float` ***optional***\
  采样温度，介于 0.0 和 2.0 之间。
* `top_p` `float` ***optional***\
  核采样参数。
* `max_output_tokens` `int` ***optional***\
  限制本次响应的最大输出 token 数。

> [!NOTE]
>
> `max_output_tokens` 会同时限制推理过程和最终输出。使用 `medium` / `high` 推理强度、JSON Schema、视频等复杂输入时，建议预留更大的输出预算；预算不足时响应可能返回 `status="incomplete"`，`output` 中可能只有 `reasoning` 项而没有最终 `message`。

* `reasoning` `object` ***optional***\
  推理配置。

  * `effort` `string` ***optional***\
    推理强度档位，可选值 `low` / `medium` / `high`。

* `tools` `object array` ***optional***\
  工具定义列表。当前仅支持 `function` 类型工具。

  * `type` `string`\
    总为 `function`
  * `name` `string`\
    函数名称，建议使用纯英文、数字和 `_-` 字符
  * `description` `string` ***optional***\
    函数功能描述，用于辅助模型判断是否调用
  * `parameters` `object`\
    JSON Schema，描述函数入参
  * `strict` `boolean` ***optional***\
    是否启用严格模式，开启后模型输出参数将严格匹配 `parameters` 中的 schema

* `tool_choice` `string or object` ***optional***\
  工具调用策略。当前仅支持字符串 `"auto"`（由模型自行决定是否调用工具）。

* `text` `object` ***optional***\
  文本输出格式配置。

  * `format` `object`
    * `type` `string`\
      取值为 `text`、`json_object` 或 `json_schema`。
    * `name` `string` ***optional***\
      当 `type=json_schema` 时必填，schema 的标识名称。
    * `strict` `boolean` ***optional***\
      当 `type=json_schema` 时可用，开启后模型输出将严格匹配 schema。
    * `schema` `object` ***optional***\
      当 `type=json_schema` 时必填，遵循 [JSON Schema](https://json-schema.org/) 规范的对象。

## 响应格式

### 非流式响应

当 `stream=false`（默认）时，返回单个 Response 对象。

#### 属性

* `id` `string`\
  响应唯一 ID，格式形如 `resp_xxx`。

* `object` `string`\
  固定为 `response`。

* `created_at` `int`\
  创建时间的 Unix 时间戳（秒）。

* `completed_at` `int or null`\
  完成时间的 Unix 时间戳（秒）。

* `status` `string`\
  响应状态，取值为 `completed`、`incomplete` 或 `failed`。

* `error` `object or null`\
  错误信息，仅在 `status=failed` 时非空。

* `incomplete_details` `object or null`\
  未完成详情，仅在 `status=incomplete` 时非空，常见为 `{ "reason": "max_output_tokens" }`。

* `model` `string`\
  实际使用的模型 ID。

* `output` `object array`\
  输出项数组。元素可能为以下类型：

  * 推理项 `object`
    * `type` `string`\
      总为 `reasoning`
    * `id` `string`\
      推理项 ID
    * `status` `string or null`\
      推理项状态，流式完成时可为 `completed`
    * `summary` `object array`\
      推理摘要列表，通常为空数组
    * `content` `object or null`\
      推理内容，通常为 `null`
    * `encrypted_content` `string or null`\
      加密推理内容，通常为 `null`
  * 文本消息 `object`
    * `type` `string`\
      总为 `message`
    * `id` `string`\
      消息 ID
    * `role` `string`\
      总为 `assistant`
    * `status` `string`\
      总为 `completed`
    * `content` `object array`
      * `type` `string`\
        总为 `output_text`
      * `text` `string`\
        模型生成的文本内容
      * `annotations` `object array`\
        注释列表，无注释时为空数组
  * 函数调用 `object`
    * `type` `string`\
      总为 `function_call`
    * `id` `string`\
      函数调用唯一 ID
    * `call_id` `string`\
      调用关联 ID，回传 `function_call_output` 时需带上
    * `name` `string`\
      被调用的工具名称
    * `arguments` `string`\
      JSON 字符串格式的参数
    * `status` `string`\
      总为 `completed`

* `usage` `object`\
  token 使用统计。

  * `input_tokens` `int`\
    输入 token 数
  * `input_tokens_details` `object`
    * `cached_tokens` `int`\
      命中缓存的输入 token 数
  * `output_tokens` `int`\
    输出 token 数
  * `output_tokens_details` `object`
    * `reasoning_tokens` `int`\
      其中用于推理的 token 数
    * `tool_output_tokens` `int`\
      其中用于工具输出的 token 数
  * `total_tokens` `int`\
    总 token 数

* `instructions` `string or null`\
  回显请求中的顶层指令。

* `max_output_tokens` `int or null`\
  回显请求参数。

* `reasoning` `object or null`\
  回显推理配置。

* `temperature` `float or null`\
  回显采样温度。

* `top_p` `float or null`\
  回显核采样参数。

* `text` `object`\
  回显文本输出格式配置。

  * `format` `object`
    * `type` `string`\
      取值为 `text`、`json_object` 或 `json_schema`。
    * `name` `string`\
      当 `type=json_schema` 时存在，schema 的标识名称。
    * `strict` `boolean`\
      当 `type=json_schema` 时存在。
    * `schema` `object`\
      当 `type=json_schema` 时存在，遵循 [JSON Schema](https://json-schema.org/) 规范的对象。

* `tool_choice` `string or object`\
  回显工具调用策略。

* `tools` `object array`\
  回显工具定义列表。

#### 示例

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "resp_xxxxxxxxxxxxxxxx",
  "object": "response",
  "created_at": 1772624997,
  "completed_at": 1772624998,
  "model": "step-5-preview",
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "output": [
    {
      "type": "reasoning",
      "id": "rs_xxxxxxxxxxxxxxxx",
      "summary": [],
      "content": null,
      "encrypted_content": null,
      "status": null
    },
    {
      "type": "message",
      "id": "msg_xxxxxxxxxxxxxxxx",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "量子计算是一种利用量子力学原理（如叠加和纠缠）来处理信息的新型计算范式。",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 14,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 52,
    "output_tokens_details": { "reasoning_tokens": 0, "tool_output_tokens": 0 },
    "total_tokens": 66
  },
  "instructions": null,
  "max_output_tokens": null,
  "reasoning": { "effort": "medium", "summary": null },
  "temperature": 1.0,
  "top_p": 1.0,
  "text": { "format": { "type": "text" } },
  "tool_choice": "auto",
  "tools": []
}
```

### 流式响应

当 `stream=true` 时，返回 Server-Sent Events (SSE) 流式数据。每条事件由 `event:` 行和 `data:` 行组成。

每个事件的 `data` 对象都包含 `type` 和 `sequence_number`。`type` 与 `event` 名称保持一致；`sequence_number` 从 0 开始递增，可用于客户端按顺序处理事件。

#### 事件类型

| 事件名 | 触发时机 |
| - | - |
| `response.created` | 响应创建 |
| `response.in_progress` | 开始生成 |
| `response.output_item.added` | 新输出项创建 |
| `response.reasoning_part.added` | 推理内容块开始 |
| `response.reasoning_text.delta` | 推理文本增量 |
| `response.reasoning_text.done` | 推理文本完成 |
| `response.reasoning_part.done` | 推理内容块完成 |
| `response.content_part.added` | 文本内容块开始 |
| `response.output_text.delta` | 文本增量 |
| `response.output_text.done` | 文本完成 |
| `response.content_part.done` | 内容块完成 |
| `response.function_call_arguments.delta` | 工具参数增量 |
| `response.function_call_arguments.done` | 工具参数完成 |
| `response.output_item.done` | 输出项完成 |
| `response.completed` | 响应完成 |
| `response.incomplete` | 因输出截断结束 |
| `response.failed` | 生成失败 |
| `error` | 传输层错误 |

#### 示例

文本流式输出：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event: response.created
data: {"type":"response.created","sequence_number":0,"response":{"id":"resp_xxx","object":"response","created_at":1772624997,"model":"step-5-preview","status":"in_progress","output":[]}}

event: response.in_progress
data: {"type":"response.in_progress","sequence_number":1,"response":{"id":"resp_xxx","status":"in_progress"}}

event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":2,"output_index":0,"item":{"id":"rs_xxx","type":"reasoning","summary":[],"content":null,"encrypted_content":null,"status":"in_progress"}}

event: response.reasoning_part.added
data: {"type":"response.reasoning_part.added","sequence_number":3,"output_index":0,"item_id":"rs_xxx","content_index":0,"part":{"type":"reasoning_text","text":""}}

event: response.reasoning_text.delta
data: {"type":"response.reasoning_text.delta","sequence_number":4,"output_index":0,"item_id":"rs_xxx","content_index":0,"delta":"用户要求问候。"}

event: response.reasoning_text.done
data: {"type":"response.reasoning_text.done","sequence_number":5,"output_index":0,"item_id":"rs_xxx","content_index":0,"text":"用户要求问候。"}

event: response.reasoning_part.done
data: {"type":"response.reasoning_part.done","sequence_number":6,"output_index":0,"item_id":"rs_xxx","content_index":0,"part":{"type":"reasoning_text","text":"用户要求问候。"}}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":7,"output_index":0,"item":{"id":"rs_xxx","type":"reasoning","summary":[],"content":null,"encrypted_content":null,"status":"completed"}}

event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":8,"output_index":1,"item":{"id":"msg_xxx","type":"message","role":"assistant","status":"in_progress","content":[]}}

event: response.content_part.added
data: {"type":"response.content_part.added","sequence_number":9,"item_id":"msg_xxx","output_index":1,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","sequence_number":10,"item_id":"msg_xxx","output_index":1,"content_index":0,"delta":"你好"}

event: response.output_text.done
data: {"type":"response.output_text.done","sequence_number":11,"item_id":"msg_xxx","output_index":1,"content_index":0,"text":"你好"}

event: response.content_part.done
data: {"type":"response.content_part.done","sequence_number":12,"item_id":"msg_xxx","output_index":1,"content_index":0,"part":{"type":"output_text","text":"你好","annotations":[]}}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":13,"output_index":1,"item":{"id":"msg_xxx","type":"message","role":"assistant","status":"completed","content":[{"type":"output_text","text":"你好","annotations":[]}]}}

event: response.completed
data: {"type":"response.completed","sequence_number":14,"response":{"id":"resp_xxx","object":"response","status":"completed","output":[{"id":"rs_xxx","type":"reasoning","summary":[],"content":null,"encrypted_content":null,"status":"completed"},{"id":"msg_xxx","type":"message","role":"assistant","status":"completed","content":[{"type":"output_text","text":"你好","annotations":[]}]}],"usage":{"input_tokens":10,"output_tokens":2,"total_tokens":12}}}
```

工具调用流式输出（节选）：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":0,"output_index":0,"item":{"id":"fc_xxx","type":"function_call","call_id":"call_xxx","name":"get_weather","arguments":"","status":"in_progress"}}

event: response.function_call_arguments.delta
data: {"type":"response.function_call_arguments.delta","sequence_number":1,"item_id":"fc_xxx","output_index":0,"delta":"{\"city\":\"北京\"}"}

event: response.function_call_arguments.done
data: {"type":"response.function_call_arguments.done","sequence_number":2,"item_id":"fc_xxx","output_index":0,"arguments":"{\"city\":\"北京\"}","name":"get_weather"}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":3,"output_index":0,"item":{"id":"fc_xxx","type":"function_call","call_id":"call_xxx","name":"get_weather","arguments":"{\"city\":\"北京\"}","status":"completed"}}

event: response.completed
data: {"type":"response.completed","sequence_number":4,"response":{"id":"resp_xxx","object":"response","status":"completed","output":[{"id":"fc_xxx","type":"function_call","call_id":"call_xxx","name":"get_weather","arguments":"{\"city\":\"北京\"}","status":"completed"}]}}
```

## 示例

**基础文字**

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

response = client.responses.create(
    model="step-5-preview",
    input="用一句话介绍量子计算",
)

print(response.output_text)
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

const response = await openai.responses.create({
    model: "step-5-preview",
    input: "用一句话介绍量子计算",
});

console.log(response.output_text);
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "input": "用一句话介绍量子计算"
  }'
```

**多轮对话 + 函数调用**

第一轮：模型根据工具定义发起 `function_call`；第二轮：客户端将上一轮的 `function_call` 与本地执行得到的 `function_call_output` 一并回传，模型基于工具结果综合回复。

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

tools = [{
    "type": "function",
    "name": "get_weather",
    "description": "获取指定城市的当前天气",
    "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string", "description": "城市名称"}},
        "required": ["city"],
    },
    "strict": True,
}]

# 第一轮：模型发起 function_call
r1 = client.responses.create(
    model="step-5-preview",
    input=[{"role": "user", "content": "北京今天天气怎么样？"}],
    tools=tools,
    tool_choice="auto",
)
fc = next(o for o in r1.output if o.type == "function_call")

# 客户端执行工具（此处用 mock 数据演示）
tool_result = '{"temperature":22,"weather":"晴","humidity":45}'

# 第二轮：回传 function_call 与 function_call_output
r2 = client.responses.create(
    model="step-5-preview",
    input=[
        {"role": "user", "content": "北京今天天气怎么样？"},
        {
            "type": "function_call",
            "id": fc.id,
            "call_id": fc.call_id,
            "name": fc.name,
            "arguments": fc.arguments,
        },
        {
            "type": "function_call_output",
            "call_id": fc.call_id,
            "output": tool_result,
        },
    ],
    tools=tools,
)
print(r2.output_text)
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

const tools = [{
    type: "function",
    name: "get_weather",
    description: "获取指定城市的当前天气",
    parameters: {
        type: "object",
        properties: { city: { type: "string", description: "城市名称" } },
        required: ["city"]
    },
    strict: true
}];

// 第一轮：模型发起 function_call
const r1 = await openai.responses.create({
    model: "step-5-preview",
    input: [{ role: "user", content: "北京今天天气怎么样？" }],
    tools,
    tool_choice: "auto"
});
const fc = r1.output.find(o => o.type === "function_call");

// 客户端执行工具（此处用 mock 数据演示）
const toolResult = '{"temperature":22,"weather":"晴","humidity":45}';

// 第二轮：回传 function_call 与 function_call_output
const r2 = await openai.responses.create({
    model: "step-5-preview",
    input: [
        { role: "user", content: "北京今天天气怎么样？" },
        {
            type: "function_call",
            id: fc.id,
            call_id: fc.call_id,
            name: fc.name,
            arguments: fc.arguments
        },
        {
            type: "function_call_output",
            call_id: fc.call_id,
            output: toolResult
        }
    ],
    tools
});
console.log(r2.output_text);
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# 第一轮：模型发起 function_call
curl https://api.stepfun.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "input": [{ "role": "user", "content": "北京今天天气怎么样？" }],
    "tools": [{
      "type": "function",
      "name": "get_weather",
      "description": "获取指定城市的当前天气",
      "parameters": {
        "type": "object",
        "properties": { "city": { "type": "string", "description": "城市名称" } },
        "required": ["city"]
      },
      "strict": true
    }],
    "tool_choice": "auto"
  }'

# 第二轮：回传 function_call 与 function_call_output（call_id 用上一轮返回的值）
curl https://api.stepfun.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "input": [
      { "role": "user", "content": "北京今天天气怎么样？" },
      {
        "type": "function_call",
        "id": "fc_xxxxxxxxxxxxxxxx",
        "call_id": "call_xxxxxxxxxxxxxxxx",
        "name": "get_weather",
        "arguments": "{\"city\":\"北京\"}"
      },
      {
        "type": "function_call_output",
        "call_id": "call_xxxxxxxxxxxxxxxx",
        "output": "{\"temperature\":22,\"weather\":\"晴\",\"humidity\":45}"
      }
    ],
    "tools": [{
      "type": "function",
      "name": "get_weather",
      "parameters": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      },
      "strict": true
    }]
  }'
```

**多模态图片**

推荐使用 base64 data URL：

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import base64, requests
from openai import OpenAI

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

# 加载图片到内存，仅演示。按需改成读文件等
r = requests.get("https://www.stepfun.com/assets/section-1-CTe4nZiO.webp")
r.raise_for_status()
image_data_url = "data:image/webp;base64," + base64.b64encode(r.content).decode("ascii")

response = client.responses.create(
    model="step-5-preview",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "描述这张图片的内容"},
            {"type": "input_image", "image_url": image_data_url},
        ],
    }],
)
print(response.output_text)
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

// 加载图片到内存，仅演示。按需改成读文件等
async function loadImage(url) {
    const res = await fetch(url);
    const blob = await res.blob();
    const buffer = Buffer.from(await blob.arrayBuffer());
    return "data:" + blob.type + ";base64," + buffer.toString("base64");
}

const imageDataUrl = await loadImage("https://www.stepfun.com/assets/section-1-CTe4nZiO.webp");

const response = await openai.responses.create({
    model: "step-5-preview",
    input: [{
        role: "user",
        content: [
            { type: "input_text", text: "描述这张图片的内容" },
            { type: "input_image", image_url: imageDataUrl }
        ]
    }]
});
console.log(response.output_text);
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# 加载图片到内存，仅演示。按需改成读文件等
image_base64="data:image/webp;base64,"$(curl -s "https://www.stepfun.com/assets/section-1-CTe4nZiO.webp" | base64)

curl https://api.stepfun.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d "{
    \"model\": \"step-5-preview\",
    \"input\": [
      {
        \"role\": \"user\",
        \"content\": [
          { \"type\": \"input_text\", \"text\": \"描述这张图片的内容\" },
          { \"type\": \"input_image\", \"image_url\": \"${image_base64}\" }
        ]
      }
    ]
  }"
```

也可使用对象形态指定 `detail`：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "type": "input_image",
  "image_url": { "url": "data:image/jpeg;base64,...", "detail": "high" }
}
```

**多模态视频**

视频通过 URL 传入，URL 需可被服务端公网访问：

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

response = client.responses.create(
    model="step-5-preview",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "请概括这个视频里的主要内容"},
            {"type": "input_video", "video_url": {"url": "https://example.com/demo.mp4", "detail": "low"}},
        ],
    }],
)
print(response.output_text)
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

const response = await openai.responses.create({
    model: "step-5-preview",
    input: [{
        role: "user",
        content: [
            { type: "input_text", text: "请概括这个视频里的主要内容" },
            { type: "input_video", video_url: { url: "https://example.com/demo.mp4", detail: "low" } }
        ]
    }]
});
console.log(response.output_text);
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "请概括这个视频里的主要内容" },
          { "type": "input_video", "video_url": {"url": "https://example.com/demo.mp4", "detail": "low"} }
        ]
      }
    ]
  }'
```

**结构化输出**

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

response = client.responses.create(
    model="step-5-preview",
    input="分析句子情感：这部电影太精彩了，强烈推荐！",
    text={
        "format": {
            "type": "json_schema",
            "name": "sentiment_analysis",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "sentiment": {"type": "string", "enum": ["positive", "negative", "neutral"]},
                    "confidence": {"type": "number"},
                    "keywords": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["sentiment", "confidence", "keywords"],
                "additionalProperties": False,
            },
        }
    },
)
print(response.output_text)
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

const response = await openai.responses.create({
    model: "step-5-preview",
    input: "分析句子情感：这部电影太精彩了，强烈推荐！",
    text: {
        format: {
            type: "json_schema",
            name: "sentiment_analysis",
            strict: true,
            schema: {
                type: "object",
                properties: {
                    sentiment: { type: "string", enum: ["positive", "negative", "neutral"] },
                    confidence: { type: "number" },
                    keywords: { type: "array", items: { type: "string" } }
                },
                required: ["sentiment", "confidence", "keywords"],
                additionalProperties: false
            }
        }
    }
});
console.log(response.output_text);
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "input": "分析句子情感：这部电影太精彩了，强烈推荐！",
    "text": {
      "format": {
        "type": "json_schema",
        "name": "sentiment_analysis",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
            "confidence": { "type": "number" },
            "keywords": { "type": "array", "items": { "type": "string" } }
          },
          "required": ["sentiment", "confidence", "keywords"],
          "additionalProperties": false
        }
      }
    }
  }'
```

**流式输出**

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

stream = client.responses.create(
    model="step-5-preview",
    input="写一首关于春天的五言绝句",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
print()
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

const stream = await openai.responses.create({
    model: "step-5-preview",
    input: "写一首关于春天的五言绝句",
    stream: true
});

for await (const event of stream) {
    if (event.type === "response.output_text.delta") {
        process.stdout.write(event.delta);
    }
}
process.stdout.write("\n");
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "input": "写一首关于春天的五言绝句",
    "stream": true
  }'
```

流式响应格式参见上文「流式响应」章节。

**推理强度**

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

response = client.responses.create(
    model="step-5-preview",
    input="证明：任何完全平方数模 4 的余数只能是 0 或 1",
    reasoning={"effort": "high"},
)
print(response.output_text)
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

const response = await openai.responses.create({
    model: "step-5-preview",
    input: "证明：任何完全平方数模 4 的余数只能是 0 或 1",
    reasoning: { effort: "high" }
});
console.log(response.output_text);
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "input": "证明：任何完全平方数模 4 的余数只能是 0 或 1",
    "reasoning": { "effort": "high" }
  }'
```


# 网页搜索
Source: https://platform.stepfun.com/docs/zh/api-reference/search/search



网页搜索接口检索互联网公开信息，并针对重点领域优化了信源的权威性，适合深入研究等对信源质量要求较高的场景。`step-5-preview` 等不支持 Chat Completions 内置 `web_search` 工具的模型，请使用本接口；把结果交给模型的写法见 [网络搜索](/docs/zh/guides/developer/web-search)。

## 请求地址

`POST https://api.stepfun.com/v1/search`

## 请求参数

* `query` `string` ***required***\
  检索关键词。
* `n` `int` ***optional***\
  返回结果条数，默认为 `10`，取值范围 1\~20。
* `category` `string` ***optional***\
  检索场景，默认为空，表示检索全部场景。

  * `programming`\
    代码编程。
  * `research`\
    学术研究。
  * `gov`\
    政务信息。
  * `business`\
    商业财经。

## 请求响应

* `query` `string`\
  检索关键词，回显请求参数。
* `category` `string`\
  检索场景，回显请求参数，未指定时为空字符串。
* `results` `object array`\
  检索结果列表。

  * `url` `string`\
    结果网页地址。
  * `position` `int`\
    结果排序位置，从 `1` 开始。
  * `title` `string`\
    结果网页标题。
  * `time` `string`\
    结果网页的索引时间。
  * `snippet` `string`\
    结果网页的摘要内容。
  * `content` `string`\
    结果网页的完整内容。

## 示例

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -X POST "https://api.stepfun.com/v1/search" \
    -H 'Content-Type: application/json; charset=utf-8' \
    -H 'Authorization: Bearer $STEPFUN_API_KEY' \
    -d '{
        "query": "Python 新手入门教程",
        "n": 1,
        "category": "programming"
    }'
```

返回示例（`snippet`、`content` 内容较长，此处省略）：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "query": "Python 新手入门教程",
  "category": "programming",
  "results": [
    {
      "url": "https://developer.aliyun.com/article/1718189",
      "position": 1,
      "title": "Python入门教程（新手必看）（一）",
      "time": "2026-03-20T00:00:00",
      "snippet": "Python 以简洁语法和强大生态成为编程入门首选，广泛应用于 Web 开发、数据分析、AI、自动化等领域...",
      "content": "Python 以简洁语法和强大生态成为编程入门首选...本文详解 Python 安装配置、基础语法（缩进、变量、输入输出、运算符）及首个程序实践，助新手快速上手..."
    }
  ]
}
```


# 文搜图
Source: https://platform.stepfun.com/docs/zh/api-reference/search/search-image



文搜图接口根据文字描述检索相关图片，可用于内容自动配图等场景，图片数据来自百度搜图。该接口仅在 [Step Plan](/docs/zh/step-plan/overview) 通道提供，按调用次数计费，具体价格见[计费详情](/docs/zh/guides/pricing/details)。

> [!WARNING]
>
> 返回图片的版权归原站点所有，接口不进行版权检测或商用授权判断，请在使用前自行评估合规性。

## 请求地址

`POST https://api.stepfun.com/step_plan/v1/search-image`

## 请求参数

* `query` `string` ***required***\
  搜索词，建议使用中文，也支持英文。
* `topk` `int` ***optional***\
  返回图片张数的上限。

## 请求响应

* `code` `int`\
  状态码，`0` 表示成功。
* `msg` `string`\
  提示信息，成功时为空字符串。
* `data` `object`\
  返回数据。

  * `result` `object`\
    搜索结果。

    * `block` `bool`\
      是否命中审核拦截。`true` 表示命中拦截，此时 `search_results` 为空；`false` 表示未拦截。
    * `search_results` `object array`\
      图片结果列表，可能为空。

      * `contentUrl` `string`\
        原图地址。
      * `snippet` `string`\
        图片描述，可用作 alt 文本。
      * `width` `int`\
        原图宽度，单位为像素。
      * `height` `int`\
        原图高度，单位为像素。
      * `hostPageUrl` `string`\
        图片所在网页地址。
      * `hostname` `string`\
        图片来源域名。

## 示例

**cURL**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl --location 'https://api.stepfun.com/step_plan/v1/search-image' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer $STEPFUN_API_KEY' \
    -d '{
        "query": "故宫",
        "topk": 2
    }'
```

**Python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import os
import requests

resp = requests.post(
    "https://api.stepfun.com/step_plan/v1/search-image",
    headers={
        "Authorization": f"Bearer {os.environ['STEPFUN_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"query": "故宫", "topk": 2},
)

result = resp.json()["data"]["result"]
for item in result["search_results"]:
    print(item["contentUrl"], item["snippet"])
```

返回示例：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "code": 0,
  "msg": "",
  "data": {
    "result": {
      "block": false,
      "search_results": [
        {
          "contentUrl": "http://q1.itc.cn/images01/20250921/4aefdeaeff0f4f2999ce3e959a902265.jpeg",
          "snippet": "故宫博物院,中国最大的古代文化艺术博物馆",
          "width": 5650,
          "height": 3687,
          "hostPageUrl": "http://travel.sohu.com/a/937199080_122365627",
          "hostname": "travel.sohu.com"
        },
        {
          "contentUrl": "http://q2.itc.cn/images01/20251010/bf333868e5e243a6808ad887067a7766.jpeg",
          "snippet": "北京故宫博物院今天过100岁生日",
          "width": 1920,
          "height": 1080,
          "hostPageUrl": "http://gov.sohu.com/a/942413642_120479584",
          "hostname": "gov.sohu.com"
        }
      ]
    }
  }
}
```


# Token Count
Source: https://platform.stepfun.com/docs/zh/api-reference/token-count



计算 token 数，支持 Chat Completion 接口与 Messages 接口两种格式。

## 计算 Chat Completion Token 数

### 请求地址

`POST https://api.stepfun.com/v1/token/count`

### 请求参数

* `model` `string` ***required***\
  需要使用的模型名称
* `messages` `object array` ***required***\
  迄今为止用户输入或模型生成的不同类别消息列表

  * 系统消息 `object`
    * `role` `string`\
      系统类别名称，总是为 `system`
    * `content` `string`\
      系统消息的文本内容
  * 用户消息 `object`
    * `role` `string`\
      用户类别名称，总是 `user`
    * `content` `string or object array`\
      用户消息内容，类型为 `multipart` 消息列表或者普通文本消息字符串
      * `普通文本消息` `string`\
        直接传入字符串作为消息内容
      * `multipart` 消息列表 `object array`\
        结构化的图文混合消息
        * 文本消息 `object`
          * `type` `string`\
            总为 `text`
          * `text` `string`\
            消息文本内容
        * 图片消息 `object`
          * `type` `string`\
            总为 `image_url`
          * `image_url` `object`
            * `url` `string`\
              图片地址或 base64编码的图片
              图片地址仅支持 http 和 https 协议
              base64格式举例：`data:image/jpeg;base64,${base64_string}`，请更换图片格式(jpeg)及对应的 base64编码后字符串
              本接口支持的图片格式：jpg/jpeg、png、webp、静态 gif
  * 聊天助手消息 `object`
    * `role` `string`\
      聊天助手类别名称，总是为 `assistant`
    * `content` `string | null`\
      聊天助手消息的文本内容

### 请求响应

* `data` `object`\
  计算 token 返回数据
  * `total_tokens` `int`\
    输入 token 数

### 示例

**文字聊天**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/token/count \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "messages": [
      {
        "role": "system",
        "content": "你是由阶跃星辰提供的AI聊天助手，你擅长中文，英文，以及多种其他语言的对话。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容。"
      },
      {
        "role": "user",
        "content": "你好，请介绍一下阶跃星辰的人工智能！"
      }
    ]
  }'
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "data": {
    "total_tokens": 85
  }
}
```

**图文混合**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/token/count \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "messages": [
      {
        "role": "system",
        "content": "你是由阶跃星辰提供的AI聊天助手，你除了擅长中文，英文，以及多种其他语言的对话以外，还能够根据用户提供的图片，对内容进行精准的内容文本描述。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容"
      },
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "用优雅的语言描述这张图片"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://www.stepfun.com/assets/section-1-CTe4nZiO.webp"
            }
          }
        ]
      }
    ]
  }'
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "data": {
    "total_tokens": 497
  }
}
```

**Base64编码图片**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# 加载图片到内存，仅演示。按需改成读文件等
image_base64="data:image/webp;base64,"$(curl -s "https://www.stepfun.com/assets/section-1-CTe4nZiO.webp" | base64)

curl https://api.stepfun.com/v1/token/count \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d "{
    \"model\": \"step-5-preview\",
    \"messages\": [
      {
        \"role\": \"system\",
        \"content\": \"你是由阶跃星辰提供的AI聊天助手，你除了擅长中文，英文，以及多种其他语言的对话以外，还能够根据用户提供的图片，对内容进行精准的内容文本描述。在保证用户数据安全的前提下，你能对用户的问题和请求，作出快速和精准的回答。同时，你的回答和建议应该拒绝黄赌毒，暴力恐怖主义的内容\"
      },
      {
        \"role\": \"user\",
        \"content\": [
          {
            \"type\": \"text\",
            \"text\": \"用优雅的语言描述这张图片\"
          },
          {
            \"type\": \"image_url\",
            \"image_url\": {
              \"url\": \"${image_base64}\"
            }
          }
        ]
      }
    ]
  }"
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "data": {
    "total_tokens": 497
  }
}
```

***

## 估算 Message Token 数

估算 Messages API 输入 token 数量，不生成模型回复。

### 请求地址

`POST https://api.stepfun.com/v1/messages/count_tokens`

> [!NOTE]
>
> 使用 Anthropic SDK 时，base\_url 应设为 `https://api.stepfun.com`，SDK 会自动拼接 `/v1/messages/count_tokens`，无需手动带 `/v1`。

> [!NOTE]
>
> Step Plan 场景请求地址为 `POST https://api.stepfun.com/step_plan/v1/messages/count_tokens`，对应 SDK base\_url 为 `https://api.stepfun.com/step_plan`。

### 请求参数

请求体结构与[创建 Message](/docs/zh/api-reference/chat/messages-create) 相同，通常至少需要提供：

* `model` `string` ***required***\
  模型名称
* `messages` `object array` ***required***\
  对话消息列表

也可按需携带 `system`、`tools` 等上下文字段。`max_tokens` 在该接口中可不传。

### 请求响应

`Content-Type: application/json`

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "input_tokens": 12
}
```

* `input_tokens` `int`\
  估算的输入 token 数量

### 示例

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from anthropic import Anthropic

client = Anthropic(api_key="YOUR_STEP_API_KEY", base_url="https://api.stepfun.com")

response = client.messages.count_tokens(
    model="step-5-preview",
    messages=[
        {
            "role": "user",
            "content": "统计这句话需要多少输入 token？"
        }
    ],
)

print(response.input_tokens)
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/messages/count_tokens \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "messages": [
      {
        "role": "user",
        "content": "统计这句话需要多少输入 token？"
      }
    ]
  }'
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "input_tokens": 12
}
```


# 工具调用
Source: https://platform.stepfun.com/docs/zh/api-reference/tool-call



Toolcall（或叫 Function Calling）是阶跃星辰开放平台提供的一项高级功能，它使模型能够根据用户的需求，智能地选择并调用合适的外部工具或函数来完成特定的任务。通过 Toolcall API，开发者可以扩展模型的能力，使其能够处理更广泛的应用场景，并提供更丰富的功能和服务。下面是一个简单的工具调用的请求 JSON 例子, 在这个对象中，必须包含三个关键参数：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
	"model": "step-5-preview",
	"messages": [
		{
			"role": "user",
			"content": "小跃跃，你能为我计算 (80 + 20) / 5 吗？"
		}
	],
	"tools": [
		{
			"type": "function",
			"function": {
				"name": "Calculator",
				"description": "这个阶跃星辰开放平台 API 提供基本的算术运算：加法、减法、乘法和除法。",
				"parameters": {
					"type": "object",
					"properties": {
						"formula": {
							"type": "string",
							"description": "需要计算的公式。仅支持整数。有效的运算符包括 +、-、*、/ 和括号。例如，(1 + 2) * 3。"
						}
					}
				}
			}
		}
	]
}
```

## model，模型名称

以下模型支持工具调用，推荐优先使用第一档：

**推荐**

* `step-5-preview`、`step-3.7-flash`、`step-3.5-flash`、`step-3.5-flash-2603`

**仅 Step Plan 通道**

* `step-router-v1`（详见 [Step Plan 推理模型接入](/docs/zh/step-plan/integrations/reasoning-api)）

**其他兼容**

* `step-1o-turbo-vision`

## 官方工具列表

以下是由阶跃星辰支持的官方工具，仅需配置即可实现相关能力：

* [互联网搜索](/docs/zh/guides/developer/web-search)：推荐使用网页搜索 API（`POST /v1/search`）。Chat Completions 内置 `web_search` 工具在 `step-5-preview` 上不可用。
* [知识库搜索](/docs/zh/guides/developer/retrieval)：上传文本到知识库中，并完成对知识库内容的搜索，帮助大模型消除幻觉

## tools，工具函数列表

通过 `tools` 参数告知模型本地支持的函数列表。每个成员对象包含 `type` 和 `function` 两个字段：`type` 当前仅支持 `function`，`function` 对象包含 `name`、`description` 和 `parameters`。函数数量建议控制在合理规模，过多的函数定义会消耗较多 prompt token，并可能降低模型的命中准确率。

* **name**（函数名称）：建议使用英文字母、数字、下划线与连字符，遵循正则 `^[a-zA-Z_][a-zA-Z0-9_-]{0,63}$`，长度不超过 64 字符。使用语义化的英文名更易被模型识别。
* **description**（功能介绍）：支持中英文，用于告诉模型此函数的用途与适用场景，便于模型判断何时调用。描述越清晰，模型命中越准确。
* **parameters**（参数定义）：根节点 `type` 必须为 `object`；`properties` 内每个字段按 [JSON Schema](https://json-schema.org/understanding-json-schema/reference/type) 规范描述其 `type` 和 `description`。若参数必填，请在 `required` 数组中列出。

## messages，上下文消息体

请求消息体结构参考 [Chat Completion 请求参数](/docs/zh/api-reference/chat/chat-completion-create#请求参数)。当模型返回 `tool_calls` 后，开发者在本地执行对应函数，再通过 `role: "tool"` 的消息（携带 `tool_call_id`）将结果回传至下一轮请求，模型据此生成最终回答。

## 示例

**python**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

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

completion = client.chat.completions.create(
    model="step-5-preview",
    messages=[
        {
            "role": "user",
            "content": "你能为我计算(80 + 20) / 5 吗？"
        }
    ],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "Calculator",
                "description": "这个阶跃星辰开放平台API提供基本的算术运算：加法、减法、乘法和除法。",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "formula": {
                            "type": "string",
                            "description": "需要计算的公式。仅支持整数。有效的运算符包括+、-、*、/和括号。例如，'(1 + 2) * 3'。"
                        }
                    }
                }
            }
        }
    ]
)

print(completion)
```

**js**

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: "YOUR_STEP_API_KEY",
    baseURL: "https://api.stepfun.com/v1"
});

async function main() {
    const completion = await openai.chat.completions.create({
        model: "step-5-preview",
        messages: [
            {
                "role": "user",
                "content": "你能为我计算(80 + 20) / 5 吗？"
            }
        ],
        tools: [
            {
                "type": "function",
                "function": {
                    "name": "Calculator",
                    "description": "这个阶跃星辰开放平台API提供基本的算术运算：加法、减法、乘法和除法。",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "formula": {
                                "type": "string",
                                "description": "需要计算的公式。仅支持整数。有效的运算符包括+、-、*、/和括号。例如，'(1 + 2) * 3'。"
                            }
                        }
                    }
                }
            }
        ]
    });

    console.log(JSON.stringify(completion));
}

main();
```

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl https://api.stepfun.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "model": "step-5-preview",
    "messages": [
      {
        "role": "user",
        "content": "你能为我计算(80 + 20) / 5 吗？"
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "Calculator",
          "description": "这个阶跃星辰开放平台API提供基本的算术运算：加法、减法、乘法和除法。",
          "parameters": {
            "type": "object",
            "properties": {
              "formula": {
                "type": "string",
                "description": "需要计算的公式。仅支持整数。有效的运算符包括+、-、*、/和括号。例如: (1 + 2) * 3。"
              }
            }
          }
        }
      }
    ]
  }'
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "b7b56af0-52a6-483f-a589-948182676a1b",
  "object": "chat.completion",
  "created": 1717744611,
  "model": "step-5-preview",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_ybVBO_JASgipgJH8xWbhKg",
            "type": "function",
            "function": {
              "name": "Calculator",
              "arguments": "{\"formula\": \"(80 + 20) / 5\"}"
            }
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 151,
    "completion_tokens": 25,
    "total_tokens": 176
  }
}
```


# 创建知识库
Source: https://platform.stepfun.com/docs/zh/api-reference/vector-stores/create



创建一个新的知识库，用于存储文本内容。

## 请求地址

`POST https://api.stepfun.com/v1/vector_stores`

## 请求体

* `name` `string` ***required***\
  知识库的名字，用于区分多个不同的知识库。目前仅支持英文、数字和下划线，且不支持以下划线开头。

* `type` `string` **optional**\
  知识库的类型，支持 text (文本类型知识库）和 image (图片知识库）。

## 请求响应

返回单个 [Vector Store 对象](/docs/zh/api-reference/vector-stores/object)

## 示例

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -L "https://api.stepfun.com/v1/vector_stores" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "name": "food_calorie2",
    "type": "text"
  }'
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "167907758199320576",
  "name": "food_calorie"
}
```


# 将文件添加到知识库
Source: https://platform.stepfun.com/docs/zh/api-reference/vector-stores/create-file



将一个已经上传的 purpose 为 `retrieval` 文件添加到知识库中。

## 请求地址

`POST https://api.stepfun.com/v1/vector_stores/{vector_store_id}/files`

## 路径参数

* `vector_store_id` `string` ***required***

  知识库的唯一 ID

## 请求体

* `files` `array` ***required***\
  要添加到知识库中的文件列表。
  * `file_id` `string` ***required***\
    要添加到知识库中的文件的 File ID，可以通过[文件上传 API](/docs/zh/api-reference/files/create) 获取。上传时，purpose 必须为 retrieval-text 或 retrieval-image。
  * `description` `string` ***optional***\
    图片文件的描述信息。支持中文、英文、空格字符等常见内容。最大长度为 255 字；在使用图片知识库的时候，此字段必填。

## 请求响应

* `files` `array`\
  &#x20;上传的文件的数组
  * `file_id` `string`\
    &#x20;文件的 File ID
  * `metadata` `object`\
    &#x20;文件对应的元信息
    * `description` `string`\
      &#x20;文件的描述信息

## 示例

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
  curl -X "POST" "https://api.stepfun.com/v1/vector_stores/160042962909147136/files" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "files": [
      {
        "file_id": "abc",
        "description": "这是一个测试文档"
      }
    ]
  }'
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "files":[
      {
          "file_id":"123",
           "metadata":{
              "description":"这是一个测试文档"
          }
      }
  ]
}
```

## 备注

* 原 form 方式提交方式已标记为 `deprecated`，将于 2025 年 5 月 15 日下线 ，新用户可使用 JSON 方式上传。


# 删除知识库
Source: https://platform.stepfun.com/docs/zh/api-reference/vector-stores/delete



删除已经创建的知识库

## 请求地址

`DELETE https://api.stepfun.com/v1/vector_stores/{vector_store_id}`

## 路径参数

* `vector_store_id` `string` ***required***

  知识库的唯一 ID

## 请求响应

* `id` `string`
  \
  知识库的唯一 ID

* `deleted` `boolean`
  \
  &#x20;删除是否成功

* `object` `string`
  \
  固定为 `vector_store.deleted`

## 示例

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -L -X DELETE 'https://api.stepfun.com/v1/vector_stores/160051919799205888' \
  -H "Authorization: Bearer $STEP_API_KEY"
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "160051919799205888",
  "deleted": true,
  "object": "vector_store.deleted"
}
```


# 将文件从知识库中移除
Source: https://platform.stepfun.com/docs/zh/api-reference/vector-stores/delete-file



从知识库中移除某个文件

## 请求地址

`DELETE https://api.stepfun.com/v1/vector_stores/{vector_store_id}/files/{file_id}`

## 路径参数

* `vector_store_id` `string` ***required***\
  知识库的唯一 ID

* `file_ids` `string` ***required***
  \
  &#x20;要添加到知识库中的文件的 File ID，可以通过[查看知识库中的文件](/docs/zh/api-reference/vector-stores/list-file)获取。

## 请求响应

* `id` `string`\
  知识库的唯一 ID

* `deleted` `boolean`\
  &#x20;删除是否成功

* `object` `string` \
  固定为 `vector_store.file.deleted`

## 示例

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -L -X DELETE 'https://api.stepfun.com/v1/vector_stores/160042962909147136/files/160050946536124416' \
  -H "Authorization: Bearer $STEP_API_KEY"
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "160050946536124416",
  "deleted": true,
  "object": "vector_store.file.deleted"
}
```


# 查看知识库列表
Source: https://platform.stepfun.com/docs/zh/api-reference/vector-stores/list



查看当前用户创建的所有知识库。

## 请求地址

`GET https://api.stepfun.com/v1/vector_stores`

## Query 参数

* `limit` `string` ***optional***\
  分页的数量，默认 20，最大 100 ，最小 1。默认值为 20。

* `order` `string` ***optional***\
  基于创建时间的返回顺序，支持参数 `asc` 和 `desc`，默认为 `desc`。

  \
  &#x20;`asc`：升序，创建早的知识库先出现
  \
  &#x20;`desc` :降序，创建晚的知识库先出现

* `before` `string` ***optional***\
  &#x20;指针 ID（知识库 ID），可与 limit / order 联合使用

* `after` `string` ***optional***\
  &#x20;指针 ID（知识库 ID），可与 limit / order 联合使用。

## 请求响应

返回 [Vector Store 对象](/docs/zh/api-reference/vector-stores/object) 列表

## 示例

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -L 'https://api.stepfun.com/v1/vector_stores?limit=1&order=desc&before=137723691273302016' \
-H "Authorization: Bearer $STEP_API_KEY"
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "object": "list",
    "data": [
        {
            "id": "167907758199320576",
            "object": "vector_store",
            "created_at": 1731485617,
            "name": "food_calorie2",
            "type": "text",
            "file_counts": {
                "in_progress": 0,
                "completed": 0,
                "failed": 0,
                "cancelled": 0,
                "total": 0
            }
        }
    ],
    "first_id": "167907758199320576",
    "last_id": "167907758199320576",
    "has_more": true
}
```


# 查看知识库中文件列表
Source: https://platform.stepfun.com/docs/zh/api-reference/vector-stores/list-file



查看对应知识库中的文件列表

## 请求地址

`GET https://api.stepfun.com/v1/vector_stores/{vector_store_id}/files`

## 路径参数

* `vector_store_id` `string` ***required***

  知识库的唯一 ID

## Query 参数

* `limit` `string` ***optional***\
  分页的数量，默认 20，最大 100 ，最小 1。默认值为 20。

* `order` `string` ***optional*** \
  基于创建时间的返回顺序，支持参数 `asc` 和 `desc`，默认为 `desc`。

  \
  &#x20;`asc`：升序，创建早的知识库先出现
  \
  &#x20;`desc` :降序，创建晚的知识库先出现

* `before` `string` ***optional***\
  &#x20;指针 ID（知识库 ID），可与 limit / order 联合使用

* `after` `string` ***optional***\
  &#x20;指针 ID（知识库 ID），可与 limit / order 联合使用。

## 请求响应

返回 [Vector Store File 对象](/docs/zh/api-reference/vector-stores/vector-store-file-object) 列表

## 示例

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -L 'https://api.stepfun.com/v1/vector_stores/160042962909147136/files' \
-H "Authorization: Bearer $STEP_API_KEY"
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "object": "list",
    "first_id": "file-CP7v8OT46a",
    "last_id": "160045144211468288",
    "has_more": false,
    "data": [
        {
            "id": "file-CP7v8OT46a",
            "object": "vector_store.file",
            "created_at": 1731491268,
            "vector_store_id": "160042962909147136"
        },
        {
            "id": "file-CP4GQjASki",
            "object": "vector_store.file",
            "created_at": 1731488576,
            "vector_store_id": "160042962909147136"
        }
    ]
}
```


# Vector Store 对象
Source: https://platform.stepfun.com/docs/zh/api-reference/vector-stores/object



单个 Vector Store 对象的描述信息

## 属性

* `id` `string`\
  Vector Store 的唯一 ID
* `object` `string`\
  对象类型，此处总为 `vector_store`
* `created_at` `int`\
  Vector Store 的创建时间，类型为 Unix 时间戳，单位 s
* `name` `string`\
  知识库名称
* `type` `string`\
  知识库类型，可选项为 `text` 和 `image`，对应文本知识库 & 多模态知识库（图片）
* `file_counts` `object`\
  知识库的各项统计信息
  * `in_progress` `int` 仍在处理中的文件数量
  * `completed` `int` 已处理完成的文件数量
  * `failed` `int` 处理失败的文件数量
  * `cancelled` `int` 已取消的文件数量
  * `total` `int` 总文件数量

## 示例

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "id": "167907758199320576",
    "object": "vector_store",
    "created_at": 1731485617,
    "name": "food_calorie2",
    "type": "text",
    "file_counts": {
        "in_progress": 0,
        "completed": 0,
        "failed": 0,
        "cancelled": 0,
        "total": 0
    }
}
```


# 获取知识库详情
Source: https://platform.stepfun.com/docs/zh/api-reference/vector-stores/retrieve



获取已经创建的知识库详情，可查看知识库中文件数量等详细信息。

## 请求地址

`GET https://api.stepfun.com/v1/vector_stores/{vector_store_id}`

## 路径参数

* `vector_store_id` `string` ***required***

  知识库的唯一 ID

## 请求响应

返回单个 [Vector Store 对象](/docs/zh/api-reference/vector-stores/object)

## 示例

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -L 'https://api.stepfun.com/v1/vector_stores/167907758199320576' \
  -H "Authorization: Bearer $STEP_API_KEY"
```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "167907758199320576",
  "object": "vector_store",
  "created_at": 1731485617,
  "name": "food_calorie2",
  "type": "text",
  "file_counts": {
    "in_progress": 0,
    "completed": 0,
    "failed": 0,
    "cancelled": 0,
    "total": 0
  }
}
```


# Vector Store File 对象
Source: https://platform.stepfun.com/docs/zh/api-reference/vector-stores/vector-store-file-object



单个 Vector Store File 对象的描述信息

## 属性

* `id` `string`\
  Vector Store 的唯一 ID

* `object` `string`\
  对象类型，此处总为 `vector_store.file`

* `created_at` `int`\
  Vector Store 的创建时间，类型为 Unix 时间戳，单位 s

* `vector_store_id` `string`\
  知识库 ID

* `metadata` `object`\
  文件的元信息
  * `description` `string`\
    文件的描述信息。

## 示例

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
 {
    "id": "file-CP7v8OT46a",
    "object": "vector_store.file",
    "created_at": 1731491268,
    "vector_store_id": "160042962909147136",
    "metadata":{
         "description":"这是图片描述"
    }
}
```


# 语音模型接入
Source: https://platform.stepfun.com/docs/zh/step-plan/integrations/audio-api



Step Plan 除推理大模型外，还支持 **语音合成 (TTS)** 与 **语音识别 (ASR)** 两类语音模型通过专属路径接入。所有请求统一使用 `/step_plan/v1/...` 路径前缀，域名固定为 `https://api.stepfun.com`。

## 前置条件

1. 已订阅 [Step Plan](https://platform.stepfun.com/step-plan) 套餐
2. 已获取 [API Key](https://platform.stepfun.com/interface-key)

***

## 支持的模型

| 类别 | 模型 | 说明 |
| - | - | - |
| 实时语音对话 | `stepaudio-2.5-realtime` | 端到端实时语音对话模型，承接 StepAudio 2.5 TTS 表现力，支持音色复刻、人设定制与极低延迟交互 |
| 语音对话 | `stepaudio-2.5-chat` | 端到端对话大模型，文本输入、文本返回，支持千万人设完全自定义与高情商副语言感知 |
| 语音合成 | `stepaudio-2.5-tts` | 基于语境理解的新一代 Contextual TTS，支持全局语境 + 文中语境双档控制，生成具有呼吸感、轻重主次、情绪弧线的真人级表达 |
| 语音识别 | `stepaudio-2.5-asr` | 新一代流式 ASR 模型，4B MTP 架构，面向准实时转写场景，在低延迟下保持高识别准确率 |

> **[实时语音对话](#实时语音对话)**
>
> WebSocket 双向实时语音

> **[语音对话](#语音对话)**
>
> 端到端对话补全（文本返回）

> **[语音合成 (TTS)](#语音合成)**
>
> 非流式 / WebSocket 流式 / 音色试听 / 音色复刻

> **[语音识别 (ASR)](#语音识别)**
>
> HTTP + SSE 流式返回识别文本

***

## 实时语音对话

### 接口路径

| 能力 | 请求方式 | Step Plan 路径 |
| - | - | - |
| 双向实时语音 | WebSocket | `wss://api.stepfun.com/step_plan/v1/realtime` |

> [!NOTE]
>
> 接口参数与开放平台完全一致，详见 [双向实时语音](/docs/zh/api-reference/realtime/chat) 接口文档。

### 计费说明

计费逻辑与开放平台一致，最终按开放平台实际计费金额折算为 Step Plan 总额度消耗。具体单价请参考 [API 定价](/docs/zh/guides/pricing/details)。

### 示例

**Python (WebSocket)**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import json
import websocket

headers = {
    "Authorization": "Bearer YOUR_STEP_API_KEY"
}

def on_open(ws):
    ws.send(json.dumps({
        "event_id": "event_001",
        "type": "session.update",
        "session": {
            "modalities": ["text", "audio"],
            "instructions": "你是有耐心的陪伴搭子，回答自然、温暖、有人情味",
            "voice": "linjiajiejie",
            "input_audio_format": "pcm16",
            "output_audio_format": "pcm16"
        }
    }))

def on_message(ws, message):
    print(message)

if __name__ == "__main__":
    ws = websocket.WebSocketApp(
        # Step Plan 使用 /step_plan/v1 路径
        "wss://api.stepfun.com/step_plan/v1/realtime?model=stepaudio-2.5-realtime",
        header=headers,
        on_open=on_open,
        on_message=on_message,
    )
    ws.run_forever()
```

***

## 语音对话

### 接口路径

| 能力 | 请求方式 | Step Plan 路径 |
| - | - | - |
| 文本对话补全 | POST | `https://api.stepfun.com/step_plan/v1/chat/completions` |

> [!NOTE]
>
> 接口参数与开放平台完全一致，详见 [对话补全（Chat Completion）](/docs/zh/api-reference/chat/chat-completion-create) 接口文档。`stepaudio-2.5-chat` 仅支持 `text` 模态，`modalities` 不应包含 `audio`。

### 计费说明

计费逻辑与开放平台一致，最终按开放平台实际计费金额折算为 Step Plan 总额度消耗。具体单价请参考 [API 定价](/docs/zh/guides/pricing/details)。

### 示例

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -X POST 'https://api.stepfun.com/step_plan/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $STEP_API_KEY" \
-d '{
    "model": "stepaudio-2.5-chat",
    "modalities": ["text"],
    "messages": [
      {"role": "user", "content": "今天心情有点闷，陪我聊聊"}
    ]
}'
```

**Python (OpenAI SDK)**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_STEP_API_KEY",
    base_url="https://api.stepfun.com/step_plan/v1",
)

response = client.chat.completions.create(
    model="stepaudio-2.5-chat",
    modalities=["text"],
    messages=[
        {"role": "user", "content": "今天心情有点闷，陪我聊聊"}
    ],
)

print(response.choices[0].message.content)
```

***

## 语音合成

### 接口路径

| 能力 | 请求方式 | Step Plan 路径 |
| - | - | - |
| 非流式语音合成 | POST | `https://api.stepfun.com/step_plan/v1/audio/speech` |
| 流式语音合成 | WebSocket | `wss://api.stepfun.com/step_plan/v1/realtime/audio` |
| 音色试听 | POST | `https://api.stepfun.com/step_plan/v1/audio/voices/preview` |
| 音色复刻 | POST | `https://api.stepfun.com/step_plan/v1/audio/voices` |

> [!NOTE]
>
> 接口参数与开放平台完全一致，详见各接口的 API 文档：[语音合成](/docs/zh/api-reference/audio/create-audio)、[流式语音合成](/docs/zh/api-reference/audio/ws-audio)、[复刻试听](/docs/zh/api-reference/audio/voices-preview)、[复刻音色](/docs/zh/api-reference/audio/create-voice)。

### 计费说明

计费逻辑与开放平台一致，最终按开放平台实际计费金额折算为 Step Plan 总额度消耗。具体单价请参考 [API 定价](/docs/zh/guides/pricing/details)。

### 示例

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -X POST 'https://api.stepfun.com/step_plan/v1/audio/speech' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $STEP_API_KEY" \
-d '{
    "model": "stepaudio-2.5-tts",
    "input": "今天天气不错，适合出去走走。",
    "voice": "cixingnansheng",
    "instruction": "语气温柔，语速偏慢",
    "response_format": "mp3"
}' \
--output speech.mp3
```

**Python (OpenAI SDK)**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_STEP_API_KEY",
    base_url="https://api.stepfun.com/step_plan/v1",
)

response = client.audio.speech.create(
    model="stepaudio-2.5-tts",
    input="今天天气不错，适合出去走走。",
    voice="cixingnansheng",
    extra_body={
        "instruction": "语气温柔，语速偏慢",
    },
)

response.stream_to_file("speech.mp3")
```

**Python (WebSocket 流式)**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import websocket
import rel
import json

headers = {
    "Authorization": "Bearer YOUR_STEP_API_KEY"
}

def get_start_event(sid):
    return json.dumps({
        "type": "tts.create",
        "data": {
            "session_id": sid,
            "voice_id": "cixingnansheng",
            "response_format": "wav",
            "volume_ratio": 1.0,
            "speed_ratio": 1.0,
            "sample_rate": 16000,
            "instruction": "语气温柔，语速偏慢"
        },
    })

def on_message(ws, message):
    data = json.loads(message)
    session_id = data["data"]["session_id"]
    event_type = data["type"]

    if event_type == "tts.connection.done":
        ws.send(get_start_event(session_id))

    print(message)

def on_error(ws, error):
    print(error)

if __name__ == "__main__":
    ws = websocket.WebSocketApp(
        # Step Plan 使用 /step_plan/v1 路径
        "wss://api.stepfun.com/step_plan/v1/realtime/audio?model=stepaudio-2.5-tts",
        header=headers,
        on_message=on_message,
        on_error=on_error,
    )

    ws.run_forever(dispatcher=rel, reconnect=5)
    rel.signal(2, rel.abort)
    rel.dispatch()
```

***

## 语音识别

### 接口路径

| 能力 | 请求方式 | Step Plan 路径 |
| - | - | - |
| 语音识别（流式返回文本） | POST | `https://api.stepfun.com/step_plan/v1/audio/asr/sse` |

> [!NOTE]
>
> 接口参数与开放平台完全一致，详见 [语音识别（流式返回文本）](/docs/zh/api-reference/audio/asr-sse) 接口文档。

### 能力限制

当前 Step Plan 下仅可通过 HTTP + SSE 方式调用 `stepaudio-2.5-asr`。

### 计费说明

计费逻辑与开放平台一致，最终按开放平台实际计费金额折算为 Step Plan 总额度消耗。具体单价请参考 [API 定价](/docs/zh/guides/pricing/details)。

### 示例

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -X POST 'https://api.stepfun.com/step_plan/v1/audio/asr/sse' \
-H 'Content-Type: application/json' \
-H 'Accept: text/event-stream' \
-H "Authorization: Bearer $STEP_API_KEY" \
-d '{
    "audio": {
        "data": "base64_encoded_audio",
        "input": {
            "transcription": {
                "model": "stepaudio-2.5-asr",
                "language": "zh",
                "enable_itn": true
            },
            "format": {
                "type": "pcm",
                "codec": "pcm_s16le",
                "rate": 16000,
                "bits": 16,
                "channel": 1
            }
        }
    }
}'
```


# 推理模型接入
Source: https://platform.stepfun.com/docs/zh/step-plan/integrations/reasoning-api



Step Plan 支持通过专属路径接入阶跃星辰推理大模型。所有请求统一使用 `/step_plan/v1/...` 路径前缀，域名固定为 `https://api.stepfun.com`。

## 前置条件

1. 已订阅 [Step Plan](https://platform.stepfun.com/step-plan) 套餐
2. 已获取 [API Key](https://platform.stepfun.com/interface-key)

***

## 支持的模型

| 模型 | 说明 |
| - | - |
| `step-5-preview` | 面向真实任务的新一代旗舰基模，支持文本、图片和视频输入，提供 1M tokens 上下文 |
| `step-3.7-flash` | 高速多模态推理模型，原生支持图片和视频理解，支持三档推理强度（low/medium/high），适合智能体、代码与多模态场景 |
| `step-3.5-flash-2603` | 基于 `step-3.5-flash` 针对高频 Agent 场景优化，Token 效率提升、推理速度更快，可切换至低推理模式大幅降低 Token 消耗 |
| `step-3.5-flash` | 196B 总参数 / 11B 激活参数的稀疏 MoE 架构，高速推理，专为智能体和代码任务优化 |
| `step-router-v1` | 智能路由模型，自动在 `deepseek-v4-pro` 与 `step-3.7-flash` 之间切换 |

> [!NOTE]
>
> `step-router-v1` 的字段约束（`max_tokens` 上限、不支持的内容类型等）详见 API 文档 [Messages API](/docs/zh/api-reference/chat/messages-create) 中「step-router-v1 字段限制（仅适用于该模型）」与 [Chat Completion API](/docs/zh/api-reference/chat/chat-completion-create) 中「Step Plan 通道：DeepSeek 引擎字段差异」。

## 接口路径

| 能力 | 请求方式 | Step Plan 路径 |
| - | - | - |
| Chat Completion（OpenAI 协议） | POST | `https://api.stepfun.com/step_plan/v1/chat/completions` |
| Messages（Anthropic 协议） | POST | `https://api.stepfun.com/step_plan/v1/messages` |

> [!NOTE]
>
> 接口参数详见 [Chat Completion API 文档](/docs/zh/api-reference/chat/chat-completion-create) 和 [Messages API 文档](/docs/zh/api-reference/chat/messages-create)。

> [!WARNING]
>
> Anthropic SDK 会自动在 base\_url 后拼接 `/v1/messages`，因此使用 Anthropic SDK 时 base\_url 应设为 `https://api.stepfun.com/step_plan`（不带 `/v1`）。OpenAI SDK 则使用 `https://api.stepfun.com/step_plan/v1`。

## 推理强度

支持三档推理强度的模型可在请求中指定 `low`、`medium`、`high`。Chat Completion（OpenAI 协议）使用 `reasoning_effort`；Messages（Anthropic 协议）使用 `output_config.effort`。

| 推理强度 | 适用场景 |
| - | - |
| `low` | 简单问答、摘要、改写、信息抽取 |
| `medium` | 默认推荐，适合一般推理和多步骤任务 |
| `high` | 复杂推理、数学、规划、代码分析 |

## 计费说明

调用产生的消耗从 Step Plan Credit 中扣减。套餐额度与分时段扣减规则见[套餐与计费](/docs/zh/step-plan/pricing)。`step-router-v1` 按实际命中模型计费：命中 `deepseek-v4-pro` 按 `deepseek-v4-pro` 计费，命中 `step-3.7-flash` 按 `step-3.7-flash` 计费。

## 接入方式

### 直接调用 API

**curl**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl -X POST 'https://api.stepfun.com/step_plan/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $STEP_API_KEY" \
-d '{
    "model": "step-5-preview",
    "messages": [
        {"role": "user", "content": "你好，请介绍一下你自己"}
    ]
}'
```

**Python (OpenAI SDK)**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_STEP_API_KEY",
    base_url="https://api.stepfun.com/step_plan/v1",
)

response = client.chat.completions.create(
    model="step-5-preview",
    messages=[
        {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
)

print(response.choices[0].message.content)
```

**Python (Anthropic SDK)**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from anthropic import Anthropic

# 注意：Anthropic SDK 会自动拼接 /v1/messages，base_url 不带 /v1
client = Anthropic(
    api_key="YOUR_STEP_API_KEY",
    base_url="https://api.stepfun.com/step_plan",
)

message = client.messages.create(
    model="step-5-preview",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
)

print(message.content[0].text)
```

### 切换到 Step Router V1

调用方式与上述完全一致，将 `model` 字段切换为 `step-router-v1` 即可：

**Python (OpenAI SDK)**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_STEP_API_KEY",
    base_url="https://api.stepfun.com/step_plan/v1",
)

response = client.chat.completions.create(
    model="step-router-v1",
    messages=[
        {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
)

print(response.choices[0].message.content)
```

**Python (Anthropic SDK)**

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
from anthropic import Anthropic

client = Anthropic(
    api_key="YOUR_STEP_API_KEY",
    base_url="https://api.stepfun.com/step_plan",
)

message = client.messages.create(
    model="step-router-v1",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
)

print(message.content[0].text)
```

### 通过工具接入

推理模型可通过各类 Agent 工具和编码助手接入，只需将 Base URL 设置为 `https://api.stepfun.com/step_plan/v1`，模型选择 `step-5-preview`、`step-3.7-flash`、`step-3.5-flash-2603`、`step-3.5-flash` 或 `step-router-v1`。

详见 [快速开始](/docs/zh/step-plan/quick-start) 以及各工具的接入指南：

> **[OpenClaw](/docs/zh/guides/developer/integrations/openclaw)**
>
> 指令驱动的 Agent 和初始化型工作流

> **[Claude Code](/docs/zh/guides/developer/integrations/claude-code)**
>
> 终端内完成编码、调试和工程协作

> **[Hermes Agent](/docs/zh/guides/developer/integrations/hermes-agent)**
>
> 终端或消息平台中运行的开源 AI Agent 框架

> **[Open Code](/docs/zh/guides/developer/integrations/open-code)**
>
> 终端内用自然语言驱动开发任务


# Step Plan 概述
Source: https://platform.stepfun.com/docs/zh/step-plan/overview



Step Plan 是阶跃星辰开放平台提供的模型订阅服务，可通过 Step API Key 在 Claude Code、OpenClaw 等工具中调用模型。

## 套餐与计费

Step Plan 套餐（Token Plan）按月提供 Credit 额度，模型调用从套餐额度中扣减。套餐档位、价格、加油包及分时段扣减规则见[套餐与计费](/docs/zh/step-plan/pricing)。

> [!NOTE]
>
> 历史套餐 Coding Plan 按请求次数计量，已停止新购。原套餐权益的保留条件及续订、升级规则见 [Step Plan 套餐调整公告](/docs/zh/announcements/step-plan-usage-adjustment#原套餐权益保留规则)。

## 支持的模型

Step Plan 当前支持以下模型，覆盖文本、推理、语音与智能路由等场景。各模型的能力说明与参数详见[模型列表](/docs/zh/guides/models/list)。

* [Step 5 Preview](/docs/zh/guides/models/step-5-preview)：面向真实任务的新一代旗舰基模
* [Step 3.7 Flash](/docs/zh/guides/models/step-3.7-flash)：高速多模态推理模型
* [Step 3.5 Flash](/docs/zh/guides/models/step-3.5-flash)：面向智能体与代码任务的高速模型
* Step 3.5 Flash 2603：针对高频 Agent 场景优化的版本
* [StepAudio 2.5 Realtime](/docs/zh/guides/models/stepaudio-2.5-realtime)：端到端实时语音对话模型
* [StepAudio 2.5 Chat](/docs/zh/guides/models/stepaudio-2.5-chat)：端到端语音对话大模型
* [StepAudio 2.5 TTS](/docs/zh/guides/models/stepaudio-2.5-tts)：新一代 Contextual TTS 模型
* [StepAudio 2.5 ASR](/docs/zh/guides/models/stepaudio-2.5-asr)：新一代自动语音识别模型
* [Step Router V1](/docs/zh/guides/models/step-router)：智能路由模型，按任务复杂度自动调度

## 接入与使用

订阅 [Step Plan](https://platform.stepfun.com/step-plan) 后，使用 Step API Key 配置对应的接入地址。通过 Step Plan 地址发起的调用消耗套餐额度，按量付费 API 调用使用独立的账户额度。

| API 协议 | Base URL |
| - | - |
| Chat Completions API（OpenAI 兼容） | `https://api.stepfun.com/step_plan/v1` |
| Messages API（Anthropic 兼容） | `https://api.stepfun.com/step_plan` |

具体工具的配置方式见[快速开始](/docs/zh/step-plan/quick-start)。直接通过 API 接入时，可参阅[推理模型接入](/docs/zh/step-plan/integrations/reasoning-api)或[语音模型接入](/docs/zh/step-plan/integrations/audio-api)。


# 套餐与计费
Source: https://platform.stepfun.com/docs/zh/step-plan/pricing



Step Plan 套餐（Token Plan）按月提供 Credit 额度，模型调用按实际用量扣减。

## 套餐档位

| 档位 | 月度 Credit | 月付 | 季付 | 年付 |
| - | - | - | - | - |
| Mini | 400M | ¥49 | ¥129 | ¥456 |
| Plus | 1,600M | ¥99 | ¥269 | ¥936 |
| Pro | 8,000M | ¥199 | ¥539 | ¥1,860 |
| Max | 40,000M | ¥699 | ¥1,889 | ¥6,666 |

表中 M 表示百万 Credit。季付和年付按所选周期一次性支付，Credit 仍按月发放，分别发放 3 次和 12 次。

## Credit 额度

Credit 与支付金额按 1 元 = 1,000,000 Credit 换算。订阅后，每月发放对应档位的 Credit；当期剩余额度到期后清零，不结转至下一周期。

Step Plan 不适用按量付费 API 按累计充值金额划分的[阶梯限速](/docs/zh/guides/pricing/rate-limits#阶梯限速)。

## 分时段扣减

通过 Step Plan 调用 Step 5 Preview 时，Credit 消耗与调用时段有关。同等用量下，高峰时段消耗的 Credit 为低谷时段的 2 倍。

| 时段 | 时间（北京时间） | Credit 扣减标准 |
| - | - | - |
| 高峰时段 | 周一至周五 09:00–12:00、14:00–18:00 | 低谷时段的 2 倍 |
| 低谷时段 | 上述高峰时段以外的全部时间 | 常规扣减 |

> [!NOTE]
>
> 部分历史订阅不受分时段扣减规则约束，详情参见 [Step Plan 套餐调整公告](/docs/zh/announcements/step-plan-usage-adjustment#原套餐权益保留规则)。

## 加油包

当月套餐 Credit 用尽后，可购买加油包补充额度。加油包仅向已订阅 Step Plan 的用户开放，有效期为 30 天，与套餐有效期分别计算。

| 加油包 | 价格 | Credit |
| - | - | - |
| 小油包 | ¥49 | 400M |
| 大油包 | ¥99 | 1600M |

## 额度扣减顺序

当账户中同时存在套餐 Credit 与加油包 Credit 时，优先扣减先到期的额度。

## 支付方式

Step Plan 支持微信、支付宝及开放平台充值余额支付。订阅及付费服务的相关约定见[Step Plan 付费服务协议](/docs/zh/agreement/step-plan)。


# 快速开始
Source: https://platform.stepfun.com/docs/zh/step-plan/quick-start



在您常用的 AI 编程工具里接入 Step 系列模型——挑一个工具，按对应页内说明完成配置即可。

> **平台入口**
>
> * [订阅 Step Plan](https://platform.stepfun.com/step-plan)
> * [创建 API Key](https://platform.stepfun.com/interface-key)

> **接入参数**
>
> * **Chat Completions API（OpenAI 兼容）Base URL**：`https://api.stepfun.com/step_plan/v1`
> * **Messages API（Anthropic 兼容）Base URL**：`https://api.stepfun.com/step_plan`
> * **推荐验证模型**：`step-5-preview`

## 选择接入工具

## 准备账号与 API Key

在开始配置前，请先确认账号已具备可用的 Step Plan，并准备好 Step API Key。它们分别决定您是否可以正常开通调用能力，以及后续请求的身份认证与授权。

> 建议顺序：先确认已订阅或开通 Step Plan，再创建 API Key，最后接入具体工具。

### 订阅 Step Plan

如果您是首次使用开放平台，建议先检查当前账号是否已经完成 Step Plan 订阅或开通。通常情况下，只有在具备可用套餐、计划或对应调用权限后，后续的模型调用、额度消耗和能力使用才会正常生效。

如果您的账号已经由团队统一开通，可直接进入下一步；如果尚未开通，请前往 [Step Plan 订阅](https://platform.stepfun.com/step-plan) 完成对应计划的订阅，再继续创建 API Key 和接入第三方工具。

### 获取 API Key

获取方式：

* [Step 开放平台](https://platform.stepfun.com/interface-key)

建议您在控制台创建一个新的 API Key，并妥善保存，不要直接写入代码仓库。

首次接入时，推荐优先使用以下模型完成验证：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step-5-preview
```

在不同工具中，您会频繁看到这些配置项：

* `API Provider`：选择接口提供方式，例如 `OpenAI Compatible`
* `Base URL`：按工具使用的协议选择模型服务地址。Chat Completions API（OpenAI 兼容）/ OpenAI Compatible 工具填写 `https://api.stepfun.com/step_plan/v1`；Messages API（Anthropic 兼容）工具填写 `https://api.stepfun.com/step_plan`
* `API Key`：在 Step 平台获取的密钥
* `Model` 或 `Model ID`：填写 `step-5-preview`

> 注意：Claude Code 手动编辑配置文件时，`ANTHROPIC_BASE_URL` 应填写 Messages API（Anthropic 兼容）对应的 `https://api.stepfun.com/step_plan`（不带 `/v1`）。Claude Code 会在调用时自动拼接 `/v1/messages`。

## 常见检查项

如果调用失败，优先检查以下几项：

* API Key 是否填写正确且属于正确环境
* `Base URL` 是否与工具协议匹配：Chat Completions API（OpenAI 兼容）/ OpenAI Compatible 使用 `https://api.stepfun.com/step_plan/v1`，Messages API（Anthropic 兼容）/ Claude Code 配置文件使用 `https://api.stepfun.com/step_plan`
* `Model` 或 `Model ID` 是否填写为 `step-5-preview`
* 工具是否已经保存配置并完成重启


# 工具接入概述
Source: https://platform.stepfun.com/docs/zh/step-plan/tool-integrations



Step Plan 订阅可用于接入 Step Code 与第三方工具。

## Step Code

* [Step Code](/docs/zh/step-code/configuration/models)：阶跃星辰出品的终端 AI Agent，通过订阅账号登录使用 Step Plan 额度调用 Step 模型。

## 其他终端工具（CLI / TUI）

* [Claude Code](/docs/zh/guides/developer/integrations/claude-code)：通过 Messages API 接入 Step 模型，可配置推理强度与 1M 上下文。
* [Codex CLI](/docs/zh/guides/developer/integrations/codex)：通过自定义 Provider 接入 Step 模型。
* [OpenClaw](/docs/zh/guides/developer/integrations/openclaw)：在自定义 Provider 中填写 Step Plan 端点与 API Key。
* [OpenCode](/docs/zh/guides/developer/integrations/open-code)：在 `opencode.json` 中将 Base URL 配置为 `https://api.stepfun.com/step_plan/v1`，通过 Step Plan 额度调用 Step 模型。
* [Pi](/docs/zh/guides/developer/integrations/pi)：通过 Anthropic Messages 协议接入 Step 模型；工作流扩展 [Oh My Pi](/docs/zh/guides/developer/integrations/oh-my-pi) 沿用同一模型配置，并增加任务分类与角色指令。
* [Goose](/docs/zh/guides/developer/integrations/goose)：通过 OpenAI 兼容接口接入 Step 模型。
* [Hermes Agent](/docs/zh/guides/developer/integrations/hermes-agent)：在配置中选择 StepFun Step Plan 并填入 API Key，可在终端 TUI 或 Telegram 等消息平台使用。

## 编辑器与 IDE

* [Cursor](/docs/zh/guides/developer/integrations/cursor)：开启 Override OpenAI Base URL 后，可在 Chat 与 Agent 中调用 Step 模型。
* [Cline](/docs/zh/guides/developer/integrations/cline)：在 API Provider 中选择 StepFun Step Plan，接入 Step 模型。
* [CodeGPT](/docs/zh/guides/developer/integrations/codegpt)：通过 Custom Provider 的 OpenAI 兼容接口接入 Step Plan。
* [Kilo Code](/docs/zh/guides/developer/integrations/kilo-code)：通过 Step Plan Provider 接入 Step 模型。
* [Roo Code](/docs/zh/guides/developer/integrations/roo-code)：通过 OpenAI Compatible Provider 接入 Step Plan。
* [Zed](/docs/zh/guides/developer/integrations/zed)：在自定义 API Endpoint 中配置 Step 模型。

## 桌面客户端

* [Cherry Studio](/docs/zh/guides/developer/integrations/cherry-studio)：配置 Step API Key 与 Provider 后，可在客户端内调用 Step 模型。
* [DeepSeek Harness](/docs/zh/guides/developer/integrations/deepseek-harness)：DeepSeek 开源的 Agent Harness，通过本地 Web UI 添加自定义 Provider 接入 Step 5 Preview。

## MCP 服务

* [StepSearch MCP](/docs/zh/guides/developer/search-mcp)：通过 Step Plan 端点提供联网搜索与网页内容读取，供兼容 MCP 的客户端调用。