# Chenvoya API

> Video generation with Seedance 2.0 models through one API: create a task, poll it or receive a signed callback, then download the result.

Set CHENVOYA_BASE_URL to the API address shown in the console and CHENVOYA_API_KEY to your API key. Send the key with the Bearer scheme in the Authorization header.

Save IDEMPOTENCY_KEY before create or cancel requests. Reuse the same value and body when a result is unknown. Do not create a new value for a retry. HTTP 202 is acceptance; poll the task or use a verified callback endpoint. Read task details for current results and billing.

## Guides

- [Quickstart](./api-docs-en-quickstart.md): Generate your first video in three steps: create an API key, submit a task, get the result.
- [Authentication](./api-docs-en-authentication.md): Send your API key in a request header with the Bearer scheme.
- [Request conventions](./api-docs-en-conventions.md): Shared rules for the API address, JSON, request IDs, times, amounts and paging.
- [Video models](./api-docs-en-video-models.md): What Seedance 2.0, 2.0 Fast and 2.0 Mini accept and produce.
- [Generate a video](./api-docs-en-video-generate.md): Requests for text to video, first frames, first and last frames, reference images and reference media.
- [Task status and results](./api-docs-en-video-tasks.md): What the task states mean, polling or callbacks, downloading results and cancelling tasks.
- [Upload assets](./api-docs-en-assets.md): Register an asset, wait until it is active, then reference it with asset:// in generation requests.
- [Receive callbacks](./api-docs-en-callbacks.md): After you register a callback address, we send it signed events when a task finishes and when its charge is settled.
- [Verify callback signatures](./api-docs-en-callbacks-verify.md): Use the signing secret from registration to check that every event comes from us.
- [How billing works](./api-docs-en-billing.md): Funds for the upper bound are reserved at creation and settled on actual usage; failed and cancelled tasks are free.
- [Reconcile charges](./api-docs-en-billing-reconcile.md): Use task billing to check the reservation, debits, refunds and amount due of every task.
- [Idempotency and retries](./api-docs-en-idempotency.md): Retry with the same Idempotency-Key to get exactly one task and one charge.
- [Handle errors](./api-docs-en-errors.md): The shape of error responses, and which errors you can retry as they are.
- [Rate limits and allowances](./api-docs-en-limits.md): Request rate, large-request concurrency, balance and asset allowances can each refuse a new request.
- [FAQ](./api-docs-en-faq.md): Common questions about charges, failures, how long results stay and API keys.
- [OpenAPI and Markdown](./api-docs-en-downloads.md): Download the API definition, a page index for AI assistants and the Markdown of every page.

## API reference

- [API overview](./api-docs-en-api.md): Base URL, authentication, errors and every endpoint.
- [The video task object](./api-docs-en-api-video-tasks-object.md): Detailed task view.
- [Create a video task](./api-docs-en-api-video-tasks-create.md): Submit a prompt with optional images, videos or audio to create an asynchronous generation task; the task ID and the reserved amount come back at once.
- [Read a video task](./api-docs-en-api-video-tasks-retrieve.md): Check execution progress, delivery, usage and the billing summary.
- [List team tasks](./api-docs-en-api-video-tasks-list.md): Returns tasks across your team, including those created with other API keys.
- [Cancel a video task](./api-docs-en-api-video-tasks-cancel.md): Requires service.use permission and Idempotency-Key.
- [Read task billing](./api-docs-en-api-video-tasks-billing.md): Retrieve the whole-task billing summary and one ordered page of permanent billing events.
- [The asset object](./api-docs-en-api-assets-object.md): For active assets, size_bytes and sha256 are required.
- [Register an asset](./api-docs-en-api-assets-create.md): Requires service.use.
- [Check an asset](./api-docs-en-api-assets-retrieve.md): Requires service.use and an asset owned by your team.
- [Receive a task completion notification](./api-docs-en-api-events-task-completed.md): Chenvoya sends task.completed when a task reaches succeeded, failed or cancelled.
- [Receive a billing settlement notification](./api-docs-en-api-events-task-billing-settled.md): Chenvoya sends task.billing_settled after task.completed is delivered or abandoned and settlement reaches settled or settled_with_receivable.
- [Error codes](./api-docs-en-api-errors.md): Every error.code with its meaning, status and endpoints.
- [Statuses and reasons](./api-docs-en-api-statuses.md): Every value of the task, delivery, settlement, asset and billing fields.

## Downloads

- [Whole documentation in English](./api-docs-en.md)
- [Whole documentation in Chinese](./api-docs.md)
- [API definition](./api-openapi.json)