查询单任务账单

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

读取本团队任务的稳定账单汇总及一页有序、不可变的账单事件。

查看 Markdown

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

请求头

#Authorizationstring必填

Bearer 加一个空格和 API 密钥。缺失或无效时返回 401 authentication_failed。

#X-Request-IDstring

你自己的请求标识。无效或重复的值会被替换，最终值在响应头 X-Request-ID 返回。

路径参数

#task_idstring必填

平台视频任务标识

查询参数

#cursorstring

下一页不可变账单事件的不透明游标。

长度1–256

#page_sizeinteger

本页最多返回的账单事件数。

默认50范围1–100

请求示例

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

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)

// 需要 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;

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)
}

返回HTTP 200

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

#objectstring必填

单任务账单对象类型标识。

固定为video.task.billing

#task_idstring必填

本团队任务标识。

长度4–128字符A–Z a–z 0–9 _ -

#request_idstring必填

请求标识。

长度4–128字符A–Z a–z 0–9 _ -

#billing_correlation_idstring必填

账单关联标识。

长度4–128字符A–Z a–z 0–9 _ -

#modelstring必填

本任务使用的模型标识。

dreamina-seedance-2-0-260128Seedance 2.0

dreamina-seedance-2-0-fast-260128Seedance 2.0 Fast

dreamina-seedance-2-0-mini-260615Seedance 2.0 Mini

#task_statusstring必填

任务执行状态。

queued排队中

processing处理中

succeeded已成功

failed已失败

cancelled已取消

#settlement_statusstring必填

任务费用结算状态。

reserved已预留费用

pending待处理

reconciliation_required需要核对

settled已结算

settled_with_receivable已结算，仍有应收金额

#currencystring必填

金额币种，美元。

固定为USD

#reserved_amountstring必填

任务预留金额。

格式6 位小数

#charged_amountstring必填

任务计费金额。

格式6 位小数

#collected_liability_amountstring必填

已收取的计费金额。

格式6 位小数

#funding_debit_amountstring必填

实际扣减的资金金额。

格式6 位小数

#refunded_liability_amountstring必填

已退回的计费金额。

格式6 位小数

#funding_refund_amountstring必填

实际退回的资金金额。

格式6 位小数

#outstanding_receivablestring必填

尚未收取的应收金额。失败或已取消且已结算的任务为零。

格式6 位小数

#final_actual_coststring必填可能为空

最终实际费用。任务排队、处理中，或结算处于 reserved、pending、reconciliation_required 时为空；settled 或 settled_with_receivable 时为金额。失败或已取消且已结算的任务为零。

格式6 位小数

#eventsarray必填

当前页的不可变账单事件列表。

数量≤ 100

25 个子字段

#billing_event_idstring必填

账单事件标识。

长度4–128字符A–Z a–z 0–9 _ -

#task_idstring必填

事件所属任务标识。

长度4–128字符A–Z a–z 0–9 _ -

#request_idstring必填

事件关联的请求标识。

长度4–128字符A–Z a–z 0–9 _ -

#billing_correlation_idstring必填

账单关联标识。

长度4–128字符A–Z a–z 0–9 _ -

#event_typestring必填

账单事件类型。

hold_created创建费用预留

hold_increased增加费用预留

hold_reduced减少费用预留

charge_captured收取费用

supplemental_charge补充计费

receivable_created新增应收

receivable_payment支付应收

receivable_reduced减少应收

hold_released释放费用预留

refund_posted退款已记账

charge_waived费用已免除

manual_adjustment人工调整

#billing_componentstring必填

计费组成项。

generation_output生成结果

reference_video参考视频

reference_image参考图片

reference_audio参考音频

web_search联网搜索

other其他计费组成项

#amountstring必填

本事件金额。charge_waived 时为零；hold_reduced 时大于零。

格式6 位小数

#charge_amountstring必填

本事件的计费金额。

格式6 位小数

#refund_amountstring必填

本事件的退款金额。

格式6 位小数

#collected_liability_amountstring必填

本事件已收取的计费金额。

格式6 位小数

#funding_debit_amountstring必填

本事件实际扣减的资金金额。

格式6 位小数

#funding_refund_amountstring必填

本事件实际退回的资金金额。

格式6 位小数

#receivable_amountstring必填

本事件的应收变动金额。

格式6 位小数

#receivable_directionstring必填可能为空

应收变动方向。receivable_created 为 increase；receivable_payment 或 receivable_reduced 为 decrease；其他事件为空。

可选increasedecreasenull

#adjustment_directionstring必填可能为空

人工调整方向，manual_adjustment 时为 debit 或 credit，其他事件为空。

可选debitcreditnull

#audit_reasonstring必填可能为空

人工调整的审计原因；manual_adjustment 时非空，其他事件为空。

长度1–1024

#component_detail_codestring必填可能为空

billing_component 为 other 时的非空明细码；其余组成项为空。

长度1–96字符a–z 0–9 _

#currencystring必填

金额币种，美元。

固定为USD

#settlement_statusstring必填

事件记录的费用结算状态。

reserved已预留费用

pending待处理

reconciliation_required需要核对

settled已结算

settled_with_receivable已结算，仍有应收金额

#created_atinteger必填

事件创建时间，Unix 整数秒。

范围≥ 0

#billing_operation_idstring

费用操作标识，hold_reduced 事件必须提供。

长度4–128字符A–Z a–z 0–9 _ -

#quote_revision_beforeinteger

费用操作前的报价修订号，hold_reduced 事件必须提供。

范围≥ 0

#quote_revision_afterinteger

费用操作后的报价修订号，hold_reduced 事件必须提供。

范围≥ 1

#reservation_revision_beforeinteger

费用操作前的预留修订号，hold_reduced 事件必须提供。

范围≥ 0

#reservation_revision_afterinteger

费用操作后的预留修订号，hold_reduced 事件必须提供。

范围≥ 1

#next_cursorstring必填可能为空

下一页游标，可为空。

长度1–256

#reconciliationobject必填可能为空

结算状态为 reconciliation_required 时返回核对摘要；reserved、pending、settled 和 settled_with_receivable 时为空。

4 个子字段

#case_idstring必填

核对事项标识。

长度4–128字符A–Z a–z 0–9 _ -

#reason_codestring必填

费用需要核对的原因码。

missing_billable_usage缺少可计费用量

usage_schema_drift用量结构发生变化

unknown_usage_unit用量单位未知

price_rule_not_unique价格规则不唯一

output_unavailable结果不可用

#missing_metersarray必填

缺少的计量字段列表；原因为 missing_billable_usage 时至少有一项，列表内不重复。

数量≤ 16

#customer_action_requiredboolean必填

是否需要客户操作。

响应头

#X-Request-IDstring必填

本次请求的标识：你提供的有效值，或替换后的值。

响应示例

响应

{
  "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
}

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

{
  "error": {
    "code": "task_not_found",
    "message": "task was not found"
  },
  "trace_id": "trace_error_example"
}

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

状态码

每个 error.code 的处理办法见「错误码」。

状态码	说明与 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

对账计费方式

查询单任务账单

请求头

路径参数

查询参数

返回HTTP 200

响应头

状态码

相关指南