模型、价格，以及调用账户可使用的内容

GET

/v1/models

curl --request GET \
  --url https://api.stack.foldbun.com/v1/models \
  --header 'Authorization: Bearer <token>'

• 生产环境。

免费，不计量，不受模型池速率限制。available 和 pool 描述的是调用账户。

授权方式

• bearer

响应

200

全部模型，附带价格以及对调用账户的可用性。

媒体类型application/json

object

data

必填

每个模型一项。

Array<object>

一个模型，附带价格以及对调用账户的可用性。

object

id

必填

模型 ID，用于请求中的 model 字段。

string

name

必填

显示名称。

string

task

必填

模型所做的工作类型。

string

允许的值： segment ocr parse embed remove-background

endpoints

必填

接受该模型的端点。

Array<string>

license

模型权重的许可证。

string

prices

必填

模型的价目表。

Array<object>

object

unit

必填

计价单位：encode_image、prompt、point、box、refine、image、page 或 text。

string

price

必填

每个单位的额度。

number

available

必填

调用账户当前是否可使用该模型。

boolean

pool

为账户提供服务的模型池（public、free、paid）；内部账户或不可用时为 null。

string | null

freeDailyCalls

每个 UTC 日免费包含的调用次数（null：没有）。

integer | null

perMinute

包含的每日额度内调用的每分钟速率（null：无限制）。超出后，公共池返回 429；有免费池时改为从余额中扣费。

integer | null

unlockedBy

不可用时：解锁方式，例如“top-up”。

string | null

示例

{
  "data": [
    {
      "id": "sam3",
      "name": "SAM 3",
      "task": "segment",
      "endpoints": [
        "/v1/segment",
        "/v1/refine"
      ],
      "license": "SAM License",
      "prices": [
        {
          "unit": "encode_image",
          "price": 0.5
        },
        {
          "unit": "prompt",
          "price": 0.05
        },
        {
          "unit": "point",
          "price": 0.02
        },
        {
          "unit": "refine",
          "price": 0.02
        }
      ],
      "available": true,
      "pool": "paid",
      "freeDailyCalls": null,
      "perMinute": null,
      "unlockedBy": null
    }
  ]
}

default

错误信封。HTTP 状态码与 code 对应；只有 retryable: true 的错误才值得原样重复。失败的调用不收费。

状态码	错误码
400	invalid_request, invalid_image（图片通过了上传检查，但无法解码）, unsupported
401	unauthorized
402	insufficient_balance
403	model_locked
404	not_found, image_not_found
409	idempotency_conflict, request_in_progress
413	payload_too_large
429	rate_limited, daily_limit_reached, too_many_batches（均带有 Retry-After）
500	internal_error
502	upstream_error, bad_model_output
503	model_unavailable, model_busy, unavailable（均带有 Retry-After）
504	upstream_timeout

model_unavailable 也用于唯一提供该模型的 GPU 节点短时失联：失联后约一分钟内，交互式调用立即返回该错误并带较短的 Retry-After（5 秒），同步和批量调用则继续排队到各自的截止时间，不会直接失败。

各错误码的含义和重试建议：错误。

媒体类型application/json

所有错误响应的响应体。

object

error

必填

错误。

object

code

必填

稳定的、机器可读的错误码。应依据该字段而不是 message 判断。与 HTTP 状态码的对应关系见响应部分。

string

message

必填

面向人的说明。措辞可能变化。

string

retryable

必填

为 true 时，原样重复同一请求有可能成功。

boolean

retryAfterMs

必填

建议重试前等待的毫秒数；无建议时为 0。

integer

示例

{
  "error": {
    "code": "model_busy",
    "message": "model sam3 is busy; retry shortly",
    "retryable": true,
    "retryAfterMs": 5000
  }
}

响应头

Retry-After

integer

>= 1

重试前须等待的整秒数；出现在 429 和 503 响应中。

X-Request-Id

string

/^[0-9a-f]{16}$/

服务器生成的请求 ID（16 个十六进制字符）；出现在每个响应中。联系支持时应提供该值。