ToAPIsToAPIs
任务

列出账户任务

分页或批量查询当前账户的持久化任务

GET
/api/v1/tasks

国内用户请注意: 中国大陆用户请使用 https://api.toapis.cn 作为接口地址 (Base URL). 文档示例中的 https://api.toapis.com 请替换为 https://api.toapis.cn.

鉴权, 分页与错误处理见接入方式.

使用说明

分页返回账户的持久化任务列表, 用于查询生成任务的状态和账务. 默认查询近 24 小时, 最长 31 天, 按内部 ID 倒序. ids 批量查询不分页, 响应 meta 不含 from/to.

只返回持久化的任务元数据, 不返回生成结果 URL 或提示词. 查询不会轮询上游, 也不会触发结算, 退款或 Webhook. 视频转存或结算未完成时状态仍为 processing 且 finished_at=null. 接口在返回账务数据前会先做可确认性检查: 检查不通过时直接返回 503, 而不是给出不可靠的数据.

单条任务的账务无法确认时 billing=null. billing.status=pending 时省略金额字段, 确认后为 settled 或 refunded.

鉴权

Authorizationstring请求头必填

使用系统访问令牌, 格式为 Bearer YOUR_SYSTEM_ACCESS_TOKEN. 模型 API Key 不能用于此接口, 无需 X-User-Id.

请求参数

fromstring查询

带时区的 RFC 3339 起始时间, 包含该时刻. 与 to 成对提供.

约束: date-time.

tostring查询

带时区的 RFC 3339 结束时间, 不包含该时刻, 必须晚于 from.

约束: date-time.

modelstring查询

精确匹配模型标识.

约束: maxLength=191.

cursorstring查询

原样传入上一页的 next_cursor. 保留原筛选条件, 改变条件后重新开始.

约束: maxLength=2048.

limitinteger查询默认值: 20

每页最多返回的条目数.

约束: minimum=1; maximum=50; 默认值: 20.

typestring查询

任务类型. 不支持 status 查询参数.

约束: image, video, music, other.

client_business_idstring查询

精确匹配业务 ID. 不允许首尾空白或控制字符.

约束: minLength=1; maxLength=191.

idsstring查询

逗号分隔的平台任务 ID, 原始项最多 20 个, 与所有其他查询参数互斥. 去重后按首次出现顺序返回可见项, 他人或不存在的任务被省略.

请求示例

请求示例

curl --request GET \
  --url 'https://api.toapis.com/api/v1/tasks?from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z&type=video&limit=20' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'
import requests

response = requests.get(
    "https://api.toapis.com/api/v1/tasks",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    params={
        "from": "2026-11-01T00:00:00Z",
        "to": "2026-11-02T00:00:00Z",
        "type": "video",
        "limit": "20"
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())
const url = new URL("https://api.toapis.com/api/v1/tasks");
url.search = new URLSearchParams({
  "from": "2026-11-01T00:00:00Z",
  "to": "2026-11-02T00:00:00Z",
  "type": "video",
  "limit": "20"
}).toString();

const response = await fetch(url, {
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
  signal: AbortSignal.timeout(30_000),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

响应字段

示例使用虚构数据. 金额样例假设 credits_per_usd="100", 实际换算以响应为准.

列表位于 data.items, 使用 has_more 和 next_cursor 翻页. 末页游标为 null, 不返回总数.

codeinteger

业务状态码, 成功时为 0.

messagestring

响应消息, 成功时为空字符串. 错误消息会按请求语言返回.

dataobject

本次查询的结果对象.

data.itemsobject[]

当前页的记录列表, 空结果为 [].

data.items[].idstring

平台任务 ID. 任务详情查询使用此值, 不是业务 ID.

data.items[].client_business_idstring | null

创建任务时保存的客户侧业务 ID, 不等同于平台任务 ID. 无法确认或不适用时为 null.

data.items[].api_key_idstring | null

关联模型 API Key 的 ID. 没有关联 Key 时为 null.

data.items[].typestring

任务类型. 可选值: image, video, music, other.

data.items[].modelstring

模型标识.

data.items[].statusstring

任务对外状态. 视频转存或结算未完成时仍为 processing. 可选值: pending, processing, completed, failed.

data.items[].progressinteger

任务进度百分比, 范围为 0-100.

data.items[].created_atstring | null

创建时间. 时间格式为带时区的 RFC 3339. 无法确认或不适用时为 null.

data.items[].finished_atstring | null

可确认的任务终态时间. 仍在处理或终态未确认时为 null. 时间格式为带时区的 RFC 3339.

data.items[].billingobject | null

可确认的任务账务信息, 无法确认时为 null.

data.items[].billing.statusstring

任务账务状态. pending 时不返回金额; 确认后为 settled 或 refunded. 可选值: pending, settled, refunded.

data.items[].billing.creditsstring

确认后的任务账务金额, 单位为 credits. pending 时省略此字段. 以十进制字符串返回以保持精度.

data.items[].billing.cost_usdstring

确认后的任务账务 USD 金额. pending 时省略此字段. 以十进制字符串返回以保持精度.

data.has_moreboolean

是否还有下一页.

data.next_cursorstring | null

下一页游标, 原样作为 cursor 传入并保留筛选条件. 末页为 null.

data.metaobject

数据来源, 查询范围和数据口径等元信息.

data.meta.scopestring

查询的数据归属范围, 当前为认证账户自身.

data.meta.sourcestring

数据来源. 本地配置或账本快照不表示 Stripe 实时状态.

data.meta.consistencystring

数据一致性类型. eventual 表示最终一致, 记录可能稍后更新.

data.meta.fromstring

查询时间范围的下界, 包含该时刻.

data.meta.tostring

查询时间范围的上界, 不包含该时刻.

响应示例

响应示例

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "id": "task_example_01",
        "client_business_id": "order_example_01",
        "api_key_id": "42",
        "type": "video",
        "model": "example-video-model",
        "status": "completed",
        "progress": 100,
        "created_at": "2026-11-01T08:00:00Z",
        "finished_at": "2026-11-01T08:01:00Z",
        "billing": {
          "status": "settled",
          "credits": "2",
          "cost_usd": "0.02"
        }
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "meta": {
      "scope": "self",
      "source": "persisted_tasks",
      "consistency": "eventual",
      "from": "2026-11-01T00:00:00Z",
      "to": "2026-11-02T00:00:00Z"
    }
  }
}