API v1

Receive a billing settlement notification

POSTtask.billing_settledSent to your registered callback address

Chenvoya sends task.billing_settled after task.completed is delivered or abandoned and settlement reaches settled or settled_with_receivable.

View Markdown
  • Any 2xx response confirms receipt; other answers and timeouts are retried on schedule.
  • Signature, deduplication and retry rules are those of task.completed.
  • Sent after task.completed is delivered or abandoned and settlement is final.
  • A task still unsettled thirty days after completion gets no such event.

Headers

#Chenvoya-Event-IdstringRequired

A convenience copy of the event ID. This header is not covered by the signature. After verifying the signature, deduplicate using event_id inside the signed body.

Formatuuid
#Chenvoya-SignaturestringRequired

The notification signature contains t and v1. Check the timestamp as described in Callbacks, calculate HMAC-SHA256 over the original body bytes and compare in constant time.

Request bodyapplication/json · Required

#event_idstringRequired

The unique event ID inside the signed body. Deduplicate on this field after successful signature verification.

Formatuuid
#objectstringRequired

The notification object type, always event.

Alwaysevent
#typestringRequired

Whether this notification reports task completion or billing settlement.

task.completedThe task reached a final state
task.billing_settledThe task billing has been settled
#schema_versionintegerRequired

The notification format version, currently the integer 1.

Always1
#created_atintegerRequired

Event creation time in whole Unix seconds. Check it separately from each delivery attempt's signature timestamp.

Range≥ 0
#dataobjectRequired

The customer task snapshot saved when this event was created.

9 child fields
#task_idstringRequired

The platform Task ID belonging to your team.

Length4–128CharactersA–Z a–z 0–9 _ -
#request_idstringRequired

The Request ID associated with task creation.

Length4–128CharactersA–Z a–z 0–9 _ -
#billing_correlation_idstringRequired

The billing correlation ID associated with task creation.

Length4–128CharactersA–Z a–z 0–9 _ -
#modelstringRequired

The public model ID used for this task.

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
#statusstringRequired

The final task status: succeeded, failed or cancelled.

succeededSucceeded
failedFailed
cancelledCancelled
#delivery_statusstringRequired

Result delivery status when the event snapshot was saved.

pendingNot yet delivered
materializingPreparing the download
availableReady to download
output_unavailableResult unavailable
#errorobjectRequiredNullable

The task error object, or null when there is no error.

3 child fields
#codestringRequired

A code your application can use to handle the error.

no_common_asset_routeAssets temporarily unavailable
asset_not_readyA referenced asset is still processing
asset_review_timeoutAsset review timed out
route_misconfiguredService configuration error
route_temporarily_unavailableTemporarily unavailable
generation_expiredGeneration expired
generation_failedGeneration failed
input_fetch_failedAn input could not be downloaded from its URL
input_url_not_allowedAn input URL is not allowed
input_too_largeAn input exceeds its size limit
input_unsupportedAn input format, dimensions or duration is unsupported
input_rejectedAn input did not pass content review
input_preparation_failedThe inputs could not be prepared in time
input_duration_exceededThe combined input duration exceeds the model limit
#messagestringRequired

A readable explanation of the error.

Length1–1024
#detailsobject

Optional fields with more information about the error.

1 child fields
#content_indexinteger

Zero-based position of the failed input in the original content array, including text items.

Range0–50
#settlement_statusstringRequired

The billing settlement status when the event snapshot was saved.

reservedReserved
pendingPending
reconciliation_requiredUnder review
settledSettled
settled_with_receivableSettled - amount due
#final_actual_coststringRequiredNullable

The final charge as a USD string with six decimal places, or null until determined.

Format6 decimal places

Your response

The notification was received. Any 2xx response confirms delivery; other responses and timeouts cause scheduled retries.

Retry schedule

  1. after 10 seconds
  2. after 1 minute
  3. after 5 minutes
  4. then every hour
  5. for up to 7 days

Verify the signature

The full signature, deduplication and age rules are on Verify callback signatures.

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)
Receive callbacksHow billing works