# 查询单任务账单

`GET /v1/video/tasks/{task_id}/billing`

读取本团队任务的稳定账单汇总及一页有序、不可变的账单事件。用 cursor 和 page_size 翻页；汇总属于整个任务，不是当前事件页的小计。任务不存在或对本团队不可见时返回 task_not_found。

- 在请求头 `Authorization: Bearer` 后面放 API 密钥。
- 汇总属于整个任务，不是当前事件页的小计。
- 用 `cursor` 和 `page_size` 翻页读取不可变的账单事件。
- 金额是六位小数的美元字符串。

## 请求头

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

## 路径参数

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| `task_id` | string | 必填 | 平台视频任务标识 |

## 查询参数

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| `cursor` | string | 可选 | 下一页不可变账单事件的不透明游标。 长度：1–256。 |
| `page_size` | integer | 可选 | 本页最多返回的账单事件数。 默认：50。 范围：1–100。 |

## 返回 · HTTP 200

稳定的任务级账单汇总及一页有序、不可变的事件。

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| `object` | string | 必填 | 单任务账单对象类型标识。 固定为：video.task.billing。 |
| `task_id` | string | 必填 | 本团队任务标识。 长度：4–128。 字符：A–Z a–z 0–9 _ -。 |
| `request_id` | string | 必填 | 请求标识。 长度：4–128。 字符：A–Z a–z 0–9 _ -。 |
| `billing_correlation_id` | string | 必填 | 账单关联标识。 长度：4–128。 字符：A–Z a–z 0–9 _ -。 |
| `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； |
| `task_status` | string | 必填 | 任务执行状态。 `queued`：排队中； `processing`：处理中； `succeeded`：已成功； `failed`：已失败； `cancelled`：已取消； |
| `settlement_status` | string | 必填 | 任务费用结算状态。 `reserved`：已预留费用； `pending`：待处理； `reconciliation_required`：需要核对； `settled`：已结算； `settled_with_receivable`：已结算，仍有应收金额； |
| `currency` | string | 必填 | 金额币种，美元。 固定为：USD。 |
| `reserved_amount` | string | 必填 | 任务预留金额。 格式：6 位小数。 |
| `charged_amount` | string | 必填 | 任务计费金额。 格式：6 位小数。 |
| `collected_liability_amount` | string | 必填 | 已收取的计费金额。 格式：6 位小数。 |
| `funding_debit_amount` | string | 必填 | 实际扣减的资金金额。 格式：6 位小数。 |
| `refunded_liability_amount` | string | 必填 | 已退回的计费金额。 格式：6 位小数。 |
| `funding_refund_amount` | string | 必填 | 实际退回的资金金额。 格式：6 位小数。 |
| `outstanding_receivable` | string | 必填 | 尚未收取的应收金额。失败或已取消且已结算的任务为零。 格式：6 位小数。 |
| `final_actual_cost` | string | 必填，可能为空 | 最终实际费用。任务排队、处理中，或结算处于 reserved、pending、reconciliation_required 时为空；settled 或 settled_with_receivable 时为金额。失败或已取消且已结算的任务为零。 格式：6 位小数。 |
| `events` | array | 必填 | 当前页的不可变账单事件列表。 数量：≤ 100。 |
| `events.billing_event_id` | string | 必填 | 账单事件标识。 长度：4–128。 字符：A–Z a–z 0–9 _ -。 |
| `events.task_id` | string | 必填 | 事件所属任务标识。 长度：4–128。 字符：A–Z a–z 0–9 _ -。 |
| `events.request_id` | string | 必填 | 事件关联的请求标识。 长度：4–128。 字符：A–Z a–z 0–9 _ -。 |
| `events.billing_correlation_id` | string | 必填 | 账单关联标识。 长度：4–128。 字符：A–Z a–z 0–9 _ -。 |
| `events.event_type` | string | 必填 | 账单事件类型。 `hold_created`：创建费用预留； `hold_increased`：增加费用预留； `hold_reduced`：减少费用预留； `charge_captured`：收取费用； `supplemental_charge`：补充计费； `receivable_created`：新增应收； `receivable_payment`：支付应收； `receivable_reduced`：减少应收； `hold_released`：释放费用预留； `refund_posted`：退款已记账； `charge_waived`：费用已免除； `manual_adjustment`：人工调整； |
| `events.billing_component` | string | 必填 | 计费组成项。 `generation_output`：生成结果； `reference_video`：参考视频； `reference_image`：参考图片； `reference_audio`：参考音频； `web_search`：联网搜索； `other`：其他计费组成项； |
| `events.amount` | string | 必填 | 本事件金额。charge_waived 时为零；hold_reduced 时大于零。 格式：6 位小数。 |
| `events.charge_amount` | string | 必填 | 本事件的计费金额。 格式：6 位小数。 |
| `events.refund_amount` | string | 必填 | 本事件的退款金额。 格式：6 位小数。 |
| `events.collected_liability_amount` | string | 必填 | 本事件已收取的计费金额。 格式：6 位小数。 |
| `events.funding_debit_amount` | string | 必填 | 本事件实际扣减的资金金额。 格式：6 位小数。 |
| `events.funding_refund_amount` | string | 必填 | 本事件实际退回的资金金额。 格式：6 位小数。 |
| `events.receivable_amount` | string | 必填 | 本事件的应收变动金额。 格式：6 位小数。 |
| `events.receivable_direction` | string | 必填，可能为空 | 应收变动方向。receivable_created 为 increase；receivable_payment 或 receivable_reduced 为 decrease；其他事件为空。 `increase`：增加应收； `decrease`：减少应收； `null`：空值； |
| `events.adjustment_direction` | string | 必填，可能为空 | 人工调整方向，manual_adjustment 时为 debit 或 credit，其他事件为空。 `debit`：扣减方向； `credit`：增加方向； `null`：空值； |
| `events.audit_reason` | string | 必填，可能为空 | 人工调整的审计原因；manual_adjustment 时非空，其他事件为空。 长度：1–1024。 |
| `events.component_detail_code` | string | 必填，可能为空 | billing_component 为 other 时的非空明细码；其余组成项为空。 长度：1–96。 字符：a–z 0–9 _。 |
| `events.currency` | string | 必填 | 金额币种，美元。 固定为：USD。 |
| `events.settlement_status` | string | 必填 | 事件记录的费用结算状态。 `reserved`：已预留费用； `pending`：待处理； `reconciliation_required`：需要核对； `settled`：已结算； `settled_with_receivable`：已结算，仍有应收金额； |
| `events.created_at` | integer | 必填 | 事件创建时间，Unix 整数秒。 范围：≥ 0。 |
| `events.billing_operation_id` | string | 可选 | 费用操作标识，hold_reduced 事件必须提供。 长度：4–128。 字符：A–Z a–z 0–9 _ -。 |
| `events.quote_revision_before` | integer | 可选 | 费用操作前的报价修订号，hold_reduced 事件必须提供。 范围：≥ 0。 |
| `events.quote_revision_after` | integer | 可选 | 费用操作后的报价修订号，hold_reduced 事件必须提供。 范围：≥ 1。 |
| `events.reservation_revision_before` | integer | 可选 | 费用操作前的预留修订号，hold_reduced 事件必须提供。 范围：≥ 0。 |
| `events.reservation_revision_after` | integer | 可选 | 费用操作后的预留修订号，hold_reduced 事件必须提供。 范围：≥ 1。 |
| `next_cursor` | string | 必填，可能为空 | 下一页游标，可为空。 长度：1–256。 |
| `reconciliation` | object | 必填，可能为空 | 结算状态为 reconciliation_required 时返回核对摘要；reserved、pending、settled 和 settled_with_receivable 时为空。 |
| `reconciliation.case_id` | string | 必填 | 核对事项标识。 长度：4–128。 字符：A–Z a–z 0–9 _ -。 |
| `reconciliation.reason_code` | string | 必填 | 费用需要核对的原因码。 `missing_billable_usage`：缺少可计费用量； `usage_schema_drift`：用量结构发生变化； `unknown_usage_unit`：用量单位未知； `price_rule_not_unique`：价格规则不唯一； `output_unavailable`：结果不可用； |
| `reconciliation.missing_meters` | array | 必填 | 缺少的计量字段列表；原因为 missing_billable_usage 时至少有一项，列表内不重复。 数量：≤ 16。 |
| `reconciliation.customer_action_required` | boolean | 必填 | 是否需要客户操作。 |

### 响应头

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

## 状态码

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

| 状态码 | 说明 | error.code |
| --- | --- | --- |
| 200 | 稳定的任务级账单汇总及一页有序、不可变的事件。 |  |
| 400 | 请求无效。 | invalid_request |
| 401 | API 密钥缺失或无效。 响应头：`WWW-Authenticate` | authentication_failed |
| 404 | 任务不存在或对本团队不可见。 | task_not_found |
| 429 | 请求频率限制拒绝此非创建操作。 响应头：`Retry-After` | rate_limited |
| 500 | 服务内部错误。 | internal_error |
| 503 | 服务暂时不可用。 | dependency_unavailable |

## 相关指南

- [对账](./api-docs-zh-billing-reconcile.md)
- [计费方式](./api-docs-zh-billing.md)

## 请求示例

```bash
curl --request GET "${CHENVOYA_BASE_URL}/v1/video/tasks/${TASK_ID}/billing" \
  --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}
TASK_ID = os.environ["TASK_ID"]
path = "/v1/video/tasks/{task_id}/billing".replace("{task_id}", urllib.parse.quote(TASK_ID, safe=""))
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 TASK_ID = process.env.TASK_ID;
if (!TASK_ID) throw new Error("Set TASK_ID");
const path = "/v1/video/tasks/{task_id}/billing".replace("{task_id}", encodeURIComponent(TASK_ID));
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"
	"net/url"
	"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")
	}
	taskID := os.Getenv("TASK_ID")
	if taskID == "" {
		fail("Set TASK_ID")
	}
	path := strings.Replace("/v1/video/tasks/{task_id}/billing", "{task_id}", url.PathEscape(taskID), 1)
	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": "video.task.billing",
  "task_id": "task_32ae2a5177b310d3bc1ec83a98f63889",
  "request_id": "req_6acd96894df9798feb0ddb21e5a52d70",
  "billing_correlation_id": "billcorr_2f6c57065a4404b27fb9b6b24ea9a0d0",
  "model": "dreamina-seedance-2-0-260128",
  "task_status": "succeeded",
  "settlement_status": "settled",
  "currency": "USD",
  "reserved_amount": "0.782453",
  "charged_amount": "0.361564",
  "collected_liability_amount": "0.361564",
  "funding_debit_amount": "0.361564",
  "refunded_liability_amount": "0.000000",
  "funding_refund_amount": "0.000000",
  "outstanding_receivable": "0.000000",
  "final_actual_cost": "0.361564",
  "events": [
    {
      "billing_event_id": "bevt_example_hold_0001",
      "task_id": "task_32ae2a5177b310d3bc1ec83a98f63889",
      "request_id": "req_6acd96894df9798feb0ddb21e5a52d70",
      "billing_correlation_id": "billcorr_2f6c57065a4404b27fb9b6b24ea9a0d0",
      "event_type": "hold_created",
      "billing_component": "generation_output",
      "amount": "0.782453",
      "charge_amount": "0.000000",
      "refund_amount": "0.000000",
      "collected_liability_amount": "0.000000",
      "funding_debit_amount": "0.000000",
      "funding_refund_amount": "0.000000",
      "receivable_amount": "0.000000",
      "receivable_direction": null,
      "adjustment_direction": null,
      "audit_reason": null,
      "component_detail_code": null,
      "currency": "USD",
      "settlement_status": "reserved",
      "created_at": 1793167380
    },
    {
      "billing_event_id": "bevt_example_capture_0001",
      "task_id": "task_32ae2a5177b310d3bc1ec83a98f63889",
      "request_id": "req_6acd96894df9798feb0ddb21e5a52d70",
      "billing_correlation_id": "billcorr_2f6c57065a4404b27fb9b6b24ea9a0d0",
      "event_type": "charge_captured",
      "billing_component": "generation_output",
      "amount": "0.361564",
      "charge_amount": "0.361564",
      "refund_amount": "0.000000",
      "collected_liability_amount": "0.361564",
      "funding_debit_amount": "0.361564",
      "funding_refund_amount": "0.000000",
      "receivable_amount": "0.000000",
      "receivable_direction": null,
      "adjustment_direction": null,
      "audit_reason": null,
      "component_detail_code": null,
      "currency": "USD",
      "settlement_status": "settled",
      "created_at": 1793167382
    },
    {
      "billing_event_id": "bevt_example_release_0001",
      "task_id": "task_32ae2a5177b310d3bc1ec83a98f63889",
      "request_id": "req_6acd96894df9798feb0ddb21e5a52d70",
      "billing_correlation_id": "billcorr_2f6c57065a4404b27fb9b6b24ea9a0d0",
      "event_type": "hold_released",
      "billing_component": "generation_output",
      "amount": "0.420889",
      "charge_amount": "0.000000",
      "refund_amount": "0.000000",
      "collected_liability_amount": "0.000000",
      "funding_debit_amount": "0.000000",
      "funding_refund_amount": "0.000000",
      "receivable_amount": "0.000000",
      "receivable_direction": null,
      "adjustment_direction": null,
      "audit_reason": null,
      "component_detail_code": null,
      "currency": "USD",
      "settlement_status": "settled",
      "created_at": 1793167383
    }
  ],
  "next_cursor": null,
  "reconciliation": 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"
}
```

404

```json
{
  "error": {
    "code": "task_not_found",
    "message": "task was not found"
  },
  "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"
}
```