Request conventions
Shared rules for the API address, JSON, request IDs, times, amounts and paging.
On this page
Every endpoint follows these conventions. The endpoint pages describe their own fields.
API address
Save the API address as CHENVOYA_BASE_URL without a trailing slash; every path in these docs follows it, for example POST /v1/video/generations. The address is shown in the API overview and on the console's Integration page.
JSON
Request and response bodies are JSON; send Content-Type: application/json with a body. Field names and values are English identifiers: use them as they are.
Request IDs
You may send your own request ID in the X-Request-ID header; invalid or repeated values are replaced. The X-Request-ID response header returns the ID used for the request, at most 64 characters. When you report a problem, include it with the trace_id of the error response.
IDs
| ID | Format | Example |
|---|---|---|
| Task ID | A letter, then 4–128 letters, digits, _ or - in all | task_32ae2a5177b310d3bc1ec83a98f63889 |
| Asset ID | ast- and 32 lowercase hexadecimal digits | starts with ast- |
Request ID request_id | Same format as a task ID | req_6acd96894df9798feb0ddb21e5a52d70 |
Billing correlation ID billing_correlation_id | Same format as a task ID | billcorr_2f6c57065a4404b27fb9b6b24ea9a0d0 |
Times
Time fields are whole seconds since the Unix epoch, such as created_at. A time that has not happened yet, such as started_at of a task that has not started, is null.
Amounts
Amounts are USD, written as strings with six decimal places, such as "0.361564". An amount that is not final yet is null. Do not convert amounts to floating point before you calculate.
Paging
Lists page with a cursor: page_size sets the page length (1–100, default 50), and the next_cursor of a response goes into the cursor of the next request. The last page has a null next_cursor. Cursors are opaque: never build one yourself; a cursor the service did not issue for this list of your team returns 400 invalid_request.
Errors
Error responses carry an error object and a trace_id. Handle error.code; see Handle errors.