# 接收任务结算通知

`POST task.billing_settled`

task.completed 已送达或放弃且任务结算为 settled 或 settled_with_receivable 后，发送 task.billing_settled，使用独立的七天投递窗口。完成三十天后仍未结算的任务不再发送结算通知。正文中的最终实际费用与查询任务的投影一致，失败或取消且已结算的任务为零。

- 返回任意 2xx 表示已收到；其他状态或超时会按计划重试。
- 签名、去重和重试规则与 `task.completed` 相同。
- 在 `task.completed` 送达或放弃、且结算确定后发送。
- 完成三十天后仍未结算的任务不再发送这条通知。

## 请求头

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| `Chenvoya-Event-Id` | string | 必填 | 事件标识的便利副本，此请求头未被签名覆盖。验签后以正文 event_id 去重。 格式：uuid。 |
| `Chenvoya-Signature` | string | 必填 | 通知签名，包含 t 与 v1。按回调通知总览校验时间戳，并使用原始正文计算 HMAC-SHA256 后做常量时间比较。 |

## 请求体 · application/json · 必填

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| `event_id` | string | 必填 | 已签名的事件唯一标识，接收方验签成功后使用此字段去重。 格式：uuid。 |
| `object` | string | 必填 | 通知对象类型，固定为 event。 固定为：event。 |
| `type` | string | 必填 | 通知类型，区分任务完成与任务结算。 `task.completed`：任务完成通知； `task.billing_settled`：任务结算通知； |
| `schema_version` | integer | 必填 | 通知正文格式版本，当前为整数一。 固定为：1。 |
| `created_at` | integer | 必填 | 事件创建时间，Unix 整数秒；与每次尝试的签名时间分别校验。 范围：≥ 0。 |
| `data` | object | 必填 | 事件冻结时的客户任务快照。 |
| `data.task_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 | 必填 | 任务终态，区分成功、失败与取消。 `succeeded`：已成功； `failed`：已失败； `cancelled`：已取消； |
| `data.delivery_status` | string | 必填 | 事件冻结时的结果交付状态。 `pending`：待交付； `materializing`：准备下载； `available`：可下载； `output_unavailable`：结果不可用； |
| `data.error` | object | 必填，可能为空 | 任务错误对象；没有错误时为空。 |
| `data.error.code` | string | 必填 | 机器可读错误码。 `no_common_asset_route`：素材暂不可用； `asset_not_ready`：引用素材仍在处理中； `asset_review_timeout`：素材审核超时； `route_misconfigured`：服务配置错误； `route_temporarily_unavailable`：暂不可用； `generation_expired`：生成已超时； `generation_failed`：生成失败； `input_fetch_failed`：输入素材下载失败； `input_url_not_allowed`：输入素材链接不允许下载； `input_too_large`：输入素材超过大小上限； `input_unsupported`：输入素材格式、尺寸或时长不受支持； `input_rejected`：输入素材未通过内容审核； `input_preparation_failed`：未能及时准备输入素材； `input_duration_exceeded`：输入素材总时长超过型号上限； |
| `data.error.message` | string | 必填 | 供人阅读的错误说明。 长度：1–1024。 |
| `data.error.details` | object | 可选 | 可选的结构化错误详情。 |
| `data.error.details.content_index` | integer | 可选 | 失败输入在原始 content 数组中的下标，从 0 起，文字项也计入。 范围：0–50。 |
| `data.settlement_status` | string | 必填 | 事件冻结时的费用结算状态。 `reserved`：已预留费用； `pending`：待处理； `reconciliation_required`：需要核对； `settled`：已结算； `settled_with_receivable`：已结算，仍有应收金额； |
| `data.final_actual_cost` | string | 必填，可能为空 | 最终实际费用，单位为美元并保留六位小数；尚未确定时为空。 格式：6 位小数。 |

## 响应

接收成功。任意 2xx 响应均确认送达，其他状态或超时将按计划重试。

### 重试计划

- 10 秒后
- 1 分钟后
- 5 分钟后
- 之后每小时一次
- 最长 7 天

### 验证签名

验签、去重和时间窗口的完整规则见「[验证回调签名](./api-docs-zh-callbacks-verify.md)」。

```python
import base64
import hashlib
import hmac
import time

def verify(signing_secret, header, body):
    fields = {}
    for item in header.split(","):
        name, _, value = item.strip().partition("=")
        fields[name] = value
    t, v1 = fields.get("t", ""), fields.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:
        return False
    key = base64.urlsafe_b64decode(signing_secret + "=" * (-len(signing_secret) % 4))
    signed = b"chenvoya.v1." + t.encode() + b"." + body
    expected = hmac.new(key, signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)
```

## 相关指南

- [接收回调](./api-docs-zh-callbacks.md)
- [计费方式](./api-docs-zh-billing.md)

## 请求体示例

```json
{
  "event_id": "7f9c2ba4-e88f-4d2b-9a2f-0c3e5b8d1a64",
  "object": "event",
  "type": "task.billing_settled",
  "schema_version": 1,
  "created_at": 1793167400,
  "data": {
    "task_id": "task_32ae2a5177b310d3bc1ec83a98f63889",
    "request_id": "req_6acd96894df9798feb0ddb21e5a52d70",
    "billing_correlation_id": "billcorr_2f6c57065a4404b27fb9b6b24ea9a0d0",
    "model": "dreamina-seedance-2-0-260128",
    "status": "succeeded",
    "delivery_status": "available",
    "error": null,
    "settlement_status": "settled",
    "final_actual_cost": "0.361564"
  }
}
```