# 列出团队任务

`GET /v1/video/tasks`

列出当前团队的全部任务，不限于创建任务的那一把 API Key，按创建时间从新到旧排序，同一时刻用任务标识排序。空团队返回空列表。列表含标识、模型、状态、时间，以及存在时的取消投影；用量、费用、结果及错误需查询任务详情。

- 在请求头 `Authorization: Bearer` 后面放 API 密钥。
- 列出团队的全部任务，不限于创建任务的那一把 API 密钥，从新到旧排列。
- 用 `next_cursor` 翻页；最后一页为空。
- 用量、费用、结果和错误请按任务 ID 查询任务详情。

## 请求头

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| `Authorization` | string | 必填 | Bearer 加一个空格和 API 密钥。缺失或无效时返回 401 authentication_failed。 |
| `X-Request-ID` | string | 可选 | 你自己的请求标识。无效或重复的值会被替换，最终值在响应头 X-Request-ID 返回。 |

## 查询参数

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| `cursor` | string | 可选 | 上一页 next_cursor 返回的不透明游标。不是服务为本团队此列表签发的游标返回 invalid_request。 长度：1–256。 |
| `page_size` | integer | 可选 | 此页最多返回的任务数。 默认：50。 范围：1–100。 |

## 返回 · HTTP 200

本团队的一页任务。

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| `object` | string | 必填 | 对象类型标识。 固定为：list。 |
| `data` | array | 必填 | 本页的任务列表项。 数量：≤ 100。 |
| `data.id` | string | 必填 | 平台任务标识。 长度：4–128。 字符：A–Z a–z 0–9 _ -。 |
| `data.request_id` | string | 必填 | 请求关联标识。 长度：4–128。 字符：A–Z a–z 0–9 _ -。 |
| `data.billing_correlation_id` | string | 必填 | 费用关联标识。 长度：4–128。 字符：A–Z a–z 0–9 _ -。 |
| `data.model` | string | 必填 | 本次使用的模型标识。 `dreamina-seedance-2-0-260128`：Seedance 2.0； `dreamina-seedance-2-0-fast-260128`：Seedance 2.0 Fast； `dreamina-seedance-2-0-mini-260615`：Seedance 2.0 Mini； |
| `data.status` | string | 必填 | 当前状态，具体含义见对应取值。 `queued`：排队中； `processing`：处理中； `succeeded`：已成功； `failed`：已失败； `cancelled`：已取消； |
| `data.phase` | string | 必填，可能为空 | 任务执行阶段；没有当前阶段时为空。 `preparing_assets`：准备素材； `waiting_route`：等待处理； `submitting`：准备生成； `provider_processing`：生成中； `reconciling`：确认结果中； `finalizing`：整理结果； `settlement_pending`：等待结算； `null`：空值； |
| `data.delivery_status` | string | 必填 | 结果交付状态。 `pending`：待交付； `materializing`：准备下载； `available`：可下载； `output_unavailable`：结果不可用； |
| `data.settlement_status` | string | 必填 | 当前费用结算状态。 `reserved`：已预留费用； `pending`：待处理； `reconciliation_required`：需要核对； `settled`：已结算； `settled_with_receivable`：已结算，仍有应收金额； |
| `data.created_at` | integer | 必填 | 创建时间，Unix 整数秒。 范围：≥ 0。 |
| `data.started_at` | integer | 必填，可能为空 | 任务开始时间，未开始时为空。 范围：≥ 0。 |
| `data.completed_at` | integer | 必填，可能为空 | 任务完成时间，未完成时为空。 范围：≥ 0。 |
| `data.cancellation` | object | 可选，可能为空 | 存在取消操作时附带其稳定标识、状态及原因码；没有操作时省略。 |
| `data.cancellation.cancel_operation_id` | string | 必填 | 取消操作的稳定标识。 长度：4–128。 字符：A–Z a–z 0–9 _ -。 |
| `data.cancellation.status` | string | 必填 | 当前状态，具体含义见对应取值。 `requested`：已请求取消； `effective`：取消已生效； `not_effective`：取消未生效； `failed`：失败； |
| `data.cancellation.reason_code` | string | 必填，可能为空 | 取消未生效或失败时的原因码；已请求或已生效时为空。 长度：1–96。 字符：a–z 0–9 _。 |
| `next_cursor` | string | 必填，可能为空 | 下一页游标；最后一页为空。 长度：1–256。 |

### 响应头

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| `X-Request-ID` | string | 必填 | 本次请求的标识：你提供的有效值，或替换后的值。 |

## 状态码

每个 `error.code` 的处理办法见「[错误码](./api-docs-zh-api-errors.md)」。

| 状态码 | 说明 | error.code |
| --- | --- | --- |
| 200 | 本团队的一页任务。 |  |
| 400 | 请求无效。 | invalid_request |
| 401 | API 密钥缺失或无效。 响应头：`WWW-Authenticate` | authentication_failed |
| 429 | 请求频率限制拒绝此非创建操作。 响应头：`Retry-After` | rate_limited |
| 500 | 服务内部错误。 | internal_error |
| 503 | 服务暂时不可用。 | dependency_unavailable |

## 相关指南

- [任务状态与结果](./api-docs-zh-video-tasks.md)
- [请求约定](./api-docs-zh-conventions.md)

## 请求示例

```bash
curl --request GET "${CHENVOYA_BASE_URL}/v1/video/tasks" \
  --header "Authorization: Bearer ${CHENVOYA_API_KEY}"
```

```python
import urllib.request
import urllib.parse
import json
import os
import sys
import re
import uuid

key = os.environ["CHENVOYA_API_KEY"].strip()
if not key or re.search(r"[\x00-\x1f\x7f-\x9f]", key):
    sys.exit("Set CHENVOYA_API_KEY to a non-empty value without control characters")
base = os.environ["CHENVOYA_BASE_URL"].rstrip("/")
headers = {"Authorization": "Bearer " + key}
path = "/v1/video/tasks"
request = urllib.request.Request(base + path, data=None, headers=headers, method="GET")
try:
    with urllib.request.urlopen(request) as response:
        print(response.read().decode("utf-8"))
except urllib.request.HTTPError as error:
    print(error.read().decode("utf-8"))
    sys.exit(1)
```

```javascript
// 需要 Node.js 20 及以上版本，保存为 .mjs 文件后运行。
const key = process.env.CHENVOYA_API_KEY?.trim();
if (!key || /[\x00-\x1f\x7f-\x9f]/.test(key)) {
  console.error("Set CHENVOYA_API_KEY to a non-empty value without control characters");
  process.exit(1);
}
const base = process.env.CHENVOYA_BASE_URL;
if (!base) throw new Error("Set CHENVOYA_BASE_URL");
const headers = {Authorization: `Bearer ${key}`};
const path = "/v1/video/tasks";
const response = await fetch(base.replace(/\/$/, "") + path, {method: "GET", headers, body: undefined});
console.log(await response.text());
if (!response.ok) process.exitCode = 1;
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"regexp"
	"strings"
)

func main() {
	key := strings.TrimSpace(os.Getenv("CHENVOYA_API_KEY"))
	if key == "" || regexp.MustCompile(`[\x00-\x1f\x7f-\x9f]`).MatchString(key) {
		fail("Set CHENVOYA_API_KEY to a non-empty value without control characters")
	}
	base := strings.TrimRight(os.Getenv("CHENVOYA_BASE_URL"), "/")
	if base == "" {
		fail("Set CHENVOYA_BASE_URL")
	}
	path := "/v1/video/tasks"
	request, err := http.NewRequest("GET", base+path, nil)
	if err != nil {
		fail(err.Error())
	}
	request.Header.Set("Authorization", "Bearer "+key)
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		fail(err.Error())
	}
	text, err := io.ReadAll(response.Body)
	response.Body.Close()
	if err != nil {
		fail(err.Error())
	}
	fmt.Println(string(text))
	if response.StatusCode < 200 || response.StatusCode > 299 {
		os.Exit(1)
	}
}

func fail(message string) {
	fmt.Fprintln(os.Stderr, message)
	os.Exit(1)
}
```

## 响应示例

200

```json
{
  "object": "list",
  "data": [
    {
      "id": "task_32ae2a5177b310d3bc1ec83a98f63889",
      "request_id": "req_6acd96894df9798feb0ddb21e5a52d70",
      "billing_correlation_id": "billcorr_2f6c57065a4404b27fb9b6b24ea9a0d0",
      "model": "dreamina-seedance-2-0-260128",
      "status": "succeeded",
      "phase": null,
      "delivery_status": "available",
      "settlement_status": "settled",
      "created_at": 1793167380,
      "started_at": 1793167381,
      "completed_at": 1793167382
    }
  ],
  "next_cursor": null
}
```

400

```json
{
  "error": {
    "code": "invalid_request",
    "message": "request parameters are invalid"
  },
  "trace_id": "trace_error_example"
}
```

401

```json
{
  "error": {
    "code": "authentication_failed",
    "message": "authentication failed"
  },
  "trace_id": "trace_error_example"
}
```

429

```json
{
  "error": {
    "code": "rate_limited",
    "message": "request rate limit exceeded"
  },
  "trace_id": "trace_error_example"
}
```

500

```json
{
  "error": {
    "code": "internal_error",
    "message": "internal server error"
  },
  "trace_id": "trace_error_example"
}
```

503

```json
{
  "error": {
    "code": "dependency_unavailable",
    "message": "service is not ready"
  },
  "trace_id": "trace_error_example"
}
```