API reference
Base URL:
https://api.cinevva.com/v1All requests and responses are JSON, and all field names are snake_case. Send Content-Type: application/json on any request with a body, and your key as Authorization: Bearer ck_live_... (see authentication).
Endpoints
| Endpoint | Description |
|---|---|
POST /v1/rigs | Rig a mesh |
POST /v1/models | Generate a 3D model from an image |
GET /v1/jobs/{id} | Poll any job |
GET /v1/jobs | List your jobs |
GET /v1/animations | List the CC0 clip catalog |
GET /v1/assets | Search the CC0 asset library |
GET /v1/assets/categories | Categories and packs |
GET /v1/formats | Supported input and output formats |
GET /v1/account | Plan, balance, rate limit, recent usage |
Not everything is an HTTP endpoint. The MCP server exposes the same rigging and asset capabilities to AI agents, and optimization and format conversion are browser tools with no API today.
Access
The API requires an active Standard or Pro subscription. A key on a free account authenticates but every call returns 402 subscription_required. See pricing.
Everything long-running is a job
Rigging and generation both return a job: the same object, the same four statuses, the same polling endpoint. Write the waiting logic once and it serves every operation, including ones added later.
| Status | Meaning | Terminal |
|---|---|---|
queued | Accepted, waiting for a worker | no |
processing | Running | no |
succeeded | Done, output is populated | yes |
failed | Did not complete, error explains why | yes |
Internal states are collapsed into this set, so a new one appearing upstream cannot break your client. operation is likewise a stable verb rather than a vendor name, so changing the engine behind an operation is not a breaking change.
Errors
Errors carry a machine-readable code alongside a human-readable message. Branch on code; show message.
{
"error": {
"code": "insufficient_credits",
"message": "Your balance does not cover this rig."
}
}| Code | Status | Meaning |
|---|---|---|
unauthorized | 401 | Missing, invalid, or revoked API key |
forbidden | 403 | Key is valid but does not own this resource |
not_found | 404 | No such rig or endpoint |
invalid_request | 400 | Malformed body or an unknown parameter value |
unsupported_format | 400 | The mesh could not be read |
insufficient_credits | 402 | Balance will not cover the rig |
subscription_required | 402 | No active Standard or Pro subscription |
plan_required | 402 | Engine requires a higher plan |
rate_limited | 429 | Over the per-minute limit; see rate limits |
backend_unavailable | 503 | Rigger is at capacity or temporarily down; retry |
internal_error | 500 | Our fault. Retry, and tell us if it persists |
Full detail and handling advice on the errors page.
Rate limits
Authenticated responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. The limit is 60 requests per minute per key. See rate limits.
Versioning
The version is in the path. /v1 will not change field meanings or remove fields once documented. New optional fields may be added to responses, so parse leniently and ignore what you do not recognise.
CORS
/v1 responds with Access-Control-Allow-Origin: * and does not accept cookies. It is built for server-to-server use. Do not call it from a browser with a real key: anything shipped to a browser is public. Proxy through your own backend instead.