# Request conventions

Shared rules for the API address, JSON, request IDs, times, amounts and paging.

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](./api-docs-en-api.md#connection) 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](./api-docs-en-errors.md).

## Next steps

- [Authentication](./api-docs-en-authentication.md): Send your API key in a request header with the Bearer scheme.
- [Idempotency and retries](./api-docs-en-idempotency.md): Retry with the same Idempotency-Key to get exactly one task and one charge.
- [API overview](./api-docs-en-api.md): Base URL, authentication, errors and every endpoint.