Create a rig

POST/v1/rigs

Submits a mesh for rigging. Returns immediately with a job id; rigging itself runs asynchronously and takes tens of seconds. Poll GET /v1/jobs/{id} for the result.

Request body

Field	Type	Required	Description
model_url	string	one of	Publicly reachable URL of the mesh to rig
model_base64	string	one of	The mesh inline, base64-encoded. Practical ceiling ~10 MB
from_job	string	one of	Id of a previous job whose output to rig. See chaining
rig_type	string	no	Body plan. Defaults to biped
engine	string	no	fast (default) or pro. See engines
output_format	string	no	glb (default) or fbx
rotation_y	number	no	Degrees to rotate the model about Y before rigging
animation_url	string	no	A clip to retarget into the output. Fast engine only. Billed per clip

Provide exactly one of model_url, model_base64, or from_job. model_url is preferred over base64, which inflates the payload by a third and has no resumability if the request drops. Use from_job to rig the output of a generation without downloading and re-uploading it.

rig_type values

biped, quadruped, hexapod, octopod, avian, serpentine, aquatic, others.

Pick the body plan that matches your mesh. It determines where limbs are expected, so a quadruped submitted as biped will produce a poor rig rather than an error. If you are not sure, biped is right for anything humanoid and quadruped for most four-legged animals.

rotation_y

Rigging expects the character to face +Z. If yours faces another way, rotate it with rotation_y rather than re-exporting: -90 for a model facing +X, 90 for −X, 180 for −Z. Getting this wrong is the single most common cause of a rig that looks structurally right but animates sideways.

Response

202 Accepted

{
  "id": "8f14e45f-ceea-467a-9c1a-1f0d0e6b7a21",
  "object": "job",
  "operation": "rig",
  "status": "queued",
  "output": null,
  "error": null,
  "engine": "fast",
  "rig_type": "biped",
  "output_format": "glb",
  "poll_url": "/v1/jobs/8f14e45f-ceea-467a-9c1a-1f0d0e6b7a21",
  "estimated_seconds": 30,
  "created_at": "2026-08-30T19:44:02.113Z"
}

Poll GET /v1/jobs/{id} until it is terminal.

estimated_seconds is a typical figure for the chosen engine, not a guarantee. A large or dense mesh takes longer. Do not use it as a timeout; use a deadline well past the slow end (300 seconds is safe for both engines).

Examples

# Rig a quadruped with the Fast engine, output FBX
curl -X POST https://api.cinevva.com/v1/rigs \
  -H "Authorization: Bearer $CINEVVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_url": "https://example.com/wolf.glb",
    "rig_type": "quadruped",
    "engine": "fast",
    "output_format": "fbx"
  }'

# A model authored facing +X, corrected on the way in
curl -X POST https://api.cinevva.com/v1/rigs \
  -H "Authorization: Bearer $CINEVVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_url": "https://example.com/knight.fbx",
    "rig_type": "biped",
    "rotation_y": -90
  }'

Errors

Status	Code	Cause
400	invalid_request	No model source; a from_job that has not succeeded; unknown rig_type, engine, or output_format
400	unsupported_format	The file could not be read as a mesh we can rig
401	unauthorized	Missing or invalid API key
402	subscription_required	No active Standard or Pro subscription
402	insufficient_credits	Balance will not cover the rig
402	plan_required	The Pro engine requires a higher plan on your account
429	rate_limited	Over 60 requests per minute
503	backend_unavailable	Rigger at capacity. Retry with backoff

Billing

Requires an active Standard or Pro subscription. Credits are reserved when the job is accepted: the rig itself, plus a retarget for each clip you pass via animation_url. A rig that fails for our reasons is refundable; see when you are charged.