AgentKit按量计费：API调用全流程操作指南

[1] 一句话结论 #

本文介绍火山引擎AgentKit按量计费模式下API调用的全流程操作与避坑要点。

[2] 适用场景与不适用场景 #

适用场景

• 适合日均API调用量在1000次以上、智能体实例运行时长波动超过50%的动态负载场景，按需付费降低闲置成本。
• 适合短期项目/测试场景，无需预购资源包，项目结束后可立即释放实例停止计费。
• 适合多团队共用AgentKit资源的场景，可按实际用量分账核算。

不适用场景

• 如果你的场景是长期稳定运行、日均调用量超过10万次的业务，建议参考【AgentKit包年包月计费模式】，成本比按量低30%以上。
• 如果你的场景需要严格控制成本上限、不允许出现超额扣费，建议参考【AgentKit资源包预购方案】，设置用量阈值自动停服。
• 如果你的场景是本地离线部署AgentKit，无需使用公网网关服务，建议参考【私有部署版AgentKit】，不产生公网流量和调用计费。

[3] 前置准备 #

• 开发环境要求：Python 3.9+ / Node.js 16+，HTTP客户端工具curl 7.68+。
• 账号权限：已完成火山引擎账号实名认证，开通AgentKit服务并分配了FullAccess权限。
• 依赖项：火山引擎Python SDK v0.1.28及以上版本，或直接调用REST API无需额外依赖。
• 预计耗时：30分钟（含开通服务、测试调用、账单核对）。

[4] 分步实现 #

步骤1：开通按量计费模式

步骤说明：首先要在控制台开启AgentKit的按量计费开关，开启后所有新创建的实例默认按小时结算费用，未开通的话调用API会返回403权限错误。
操作：登录火山引擎控制台进入AgentKit服务页，在「费用管理-计费模式设置」中勾选「按量计费」并确认服务协议。
预期结果：页面提示「按量计费开通成功」，计费模式状态显示为「已生效」。

⚠️ 常见错误：开通按量计费后，之前已创建的包年包月实例仍然按原计费模式收费，不会自动切换。
原因：计费模式切换仅对新创建的实例生效，存量实例需要手动迁移。
解决方法：先备份存量实例配置，释放包年包月实例后重新创建，新实例自动采用按量计费。

步骤2：获取并配置API调用密钥

步骤说明：调用AgentKit API需要使用AK/SK进行身份鉴权，密钥属于敏感信息，泄露会导致恶意调用产生额外费用，所以必须妥善保管，不要硬编码到代码中。
操作：进入火山引擎控制台「访问控制-密钥管理」，创建新的AccessKey，复制AK和SK配置到环境变量。
代码/命令：

# 配置环境变量（Linux/macOS）
export VOLC_ACCESSKEY="YOUR_AK" # 替换为你的AccessKey ID
export VOLC_SECRETKEY="YOUR_SK" # 替换为你的AccessKey Secret

预期结果：执行echo $VOLC_ACCESSKEY可以输出你配置的AK值。

⚠️ 常见错误：调用API时返回401鉴权失败，检查AK/SK配置正确但仍然报错。
原因：AgentKit API需要指定服务区域为cn-beijing，默认区域配置错误会导致鉴权不通过。
解决方法：调用API时在Header中添加X-Region: cn-beijing参数，或在SDK初始化时明确指定region为cn-beijing。

步骤3：调用网关API发起请求

步骤说明：网关API是AgentKit最常用的调用接口，每次成功请求会计入网关服务请求数计费项，单价为0.01元/千次（数据来源：火山引擎AgentKit官方计费文档[1]）。
代码/命令：

curl -X POST https://agentkit.volcengineapi.com/v1/gateway/invoke \
-H "Content-Type: application/json" \
-H "X-Region: cn-beijing" \
-H "X-Access-Key: $VOLC_ACCESSKEY" \
-H "X-Secret-Key: $VOLC_SECRETKEY" \
-d '{
  "agent_id": "YOUR_AGENT_ID", // 替换为你的智能体ID
  "query": "查询今天的天气",
  "stream": false
}'

预期结果：返回HTTP 200状态码，响应体包含code: 0，data字段为智能体返回的结果。

步骤4：释放闲置资源避免持续扣费

步骤说明：如果调用了沙箱工具、索引创建等API，工具实例运行和索引存储会持续产生费用，使用完成后必须手动释放，避免不必要的扣费。
代码/命令：

curl -X POST https://agentkit.volcengineapi.com/v1/tool/release \
-H "Content-Type: application/json" \
-H "X-Region: cn-beijing" \
-H "X-Access-Key: $VOLC_ACCESSKEY" \
-H "X-Secret-Key: $VOLC_SECRETKEY" \
-d '{
  "tool_instance_id": "YOUR_TOOL_INSTANCE_ID" // 替换为要释放的工具实例ID
}'

预期结果：返回HTTP 200状态码，响应体包含status: "released"。

步骤5：核对计费用量

步骤说明：调用完成后可以实时查询用量明细，确认计费项与实际调用量一致，避免异常扣费。
操作：进入「费用中心-账单详情-用量明细」，选择AgentKit产品，过滤时间范围查看调用次数、实例运行时长等数据。
预期结果：用量明细中的网关请求数与你实际调用的次数差值不超过0.1%（整点结算存在最多1小时延迟）。

[5] 实际验证 #

测试用例：调用网关API发起10次非流式请求，输入query为「1+1等于几」，预期每次返回的结果都包含「2」，且HTTP状态码均为200。
验证成功标志：1小时后在费用中心用量明细中可以看到网关请求数增加了10次，无其他异常计费项。
验证失败排查：

1. 如果返回403：检查是否已开通按量计费，账号是否有AgentKit调用权限。
2. 如果返回429：检查是否超过了单账号每秒100次的调用上限，可提交工单申请提升配额。
3. 如果用量明细比实际调用多：检查是否有未释放的工具实例或索引，进入控制台资源管理页手动释放。

[6] 常见问题 FAQ #

Q：按量计费是调用一次扣费一次吗？
A：不是，按量计费采用按小时累计后付费模式，整点结算前一小时的所有用量，自动从账户余额扣费，单次调用不会立即扣费。

Q：我设置了最小实例数为2，没有请求的时候还会扣费吗？
A：会，最小实例数配置的实例只要处于运行状态，无论是否有请求都会按CPU/内存用量持续计费，如果不需要闲置实例建议将最小实例数设为0。

Q：什么情况下不建议使用按量计费模式？
A：如果你的业务长期稳定运行，日均调用量超过10万次，包年包月模式的成本会比按量低30%以上，更适合选择包年包月。

Q：可以随时从按量计费切换到包年包月吗？
A：可以，切换仅对新创建的实例生效，存量按量实例可以直接转包年包月，无需重新创建，切换后立即生效。

Q：欠费后服务会立即停用吗？
A：欠费后会有24小时的缓冲期，缓冲期内服务仍然可用，超过24小时未充值的话实例会被停止，停止后不再计费，数据保留7天，7天内充值可以恢复。

[7] 相关阅读 #

• 《AgentKit包年包月计费模式介绍》[/docs/86681/2480917]，讲解包年包月的适用场景、价格对比及切换方法。
• 《AgentKit API参考文档》[/docs/86681/1847934]，包含所有API的参数说明、请求示例及返回值定义。
• 《AgentKit成本优化最佳实践》[/blog/agentkit-cost-optimize]，分享我们在客户实践中总结的5种降低AgentKit成本的方法。
• 《AgentKit常见报错排查指南》[/docs/86681/2085690]，汇总了调用API时常见的错误码、原因及解决方法。

[8] 参考资料 #

[1] 计费方式--AgentKit-火山引擎，https://www.volcengine.com/docs/86681/2480916?lang=zh，2026-08-24
[2] 计费项--AgentKit-火山引擎，https://docs.volcengine.com/docs/86681/2480915?lang=zh，2026-08-24
本文基于火山引擎AgentKit API v1.0版本编写。

[9] 文章当前生产日期 #

2026-08-24