快速开始

快速开始

API

MCP 服务
API 概览认证可用模型

指南

快速开始任务与轮询错误处理

计费与限制

定价与积分速率限制

集成

OpenAPI 规范与 SDK
API

定价与积分

积分如何扣、何时退,以及怎么读余额

定价与积分

API 按生成次数计费,单位为积分。一个任务一次扣费,与模型耗时长短无关。

各模型单价

模型每次生成消耗积分
tripo8
tripo-text8
trellis210
trellis2-multiview12
hunyuan3d12
tripo-multiview15

各模型的能力与限制见 可用模型。GET /api/v1/models 返回的 creditsCost 就是同一份价格,建议运行时读取,而不是把价格写死在代码里。

什么时候扣费

积分在创建任务时扣除,不是完成时。也就是说:

  • POST /api/v1/3d/generations 成功 → 积分已经扣了,即使之后生成失败。
  • 失败的生成会退款,任务响应里会出现 usage.credits_refunded。
  • 在创建任务之前就被拒绝的请求——400、401、402、403、429——不产生费用。

扣减是原子的:只有余额足够时才会更新。并发发十个请求但只够五个, 结果是五个成功、其余拿到 402 且不扣费。余额永远不会变成负数。

读取余额

每个成功响应都带本次交易后的余额:

{
  "id": "task_abc123",
  "status": "completed",
  "data": { "model_url": "https://r2.example.com/model.glb", "format": "glb", "model": "trellis2" },
  "usage": {
    "credits_consumed": 10,
    "credits_remaining": 490
  }
}
字段出现时机
credits_consumed任务成功完成
credits_remaining任何带 usage 块的响应
credits_refunded失败任务被退款时

余额以 credits_remaining 为准。不要用本地减法预测余额——退款、重试和并发任务会让本地记账很快失真。

积分不足

HTTP/2 402
{
  "error": {
    "message": "Insufficient credits",
    "type": "credits_error",
    "code": "insufficient_credits",
    "param": null
  }
}

402 不充值就不可重试。跑大批量前先探底:跑一次最便宜的生成读 credits_remaining,或直接看控制台的账单页。

估算批量成本

总积分 ≈ Σ(所选模型单价 × 生成次数)

100 张图跑 trellis2 就是 100 × 10 = 1000 积分。若预计会有重跑(输入不合格、上游超时),按 10–15% 预留,别撞到批量跑到一半没额度。

积分在网页版 Studio 和 API 之间是共用的。你在浏览器里生成同样消耗这份余额, 所以在 UI 里用得凶的那天,集成能用的额度会变少。

错误处理

如何处理 API 错误和边界情况

速率限制

请求额度、429 响应,以及正确的退避方式

目录

定价与积分
各模型单价
什么时候扣费
读取余额
积分不足
估算批量成本