API documentation

The public API is available on the Business plan. The reference below is generated from the same specification the server uses, so it lists exactly the endpoints an API key can call.

Authentication

Send your key in the Authorization header: Authorization: Bearer vc_live_…. Keys belong to one workspace and carry scopes. A call outside the key's scopes, or to an endpoint not listed here, returns 403.

Idempotency

Endpoints that create jobs require an Idempotency-Key header. Retrying with the same key and body returns the original response; the same key with a different body returns 409 idempotency_mismatch.

Rate limits

Requests over the limit return 429 rate_limited with a Retry-After header in seconds.

Following a job

Creating a job returns 202 with the job and the credits held. Poll GET /api/v1/w/{workspace_id}/jobs/{job_id} until the status is succeeded, failed, canceled, or expired.

Errors

Errors use application/problem+json with a stable code, for example insufficient_credits (402), moderation_blocked (422), validation_error (422), not_found (404).

Endpoint reference

31 operations, generated from the public API specification.

GET/api/v1/cast/libraryList the cast library

Scopes: jobs:read

Responses: 200

GET/api/v1/w/{workspace_id}/assetsList images

List images in this workspace.

Scopes: assets:read

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes
`kind`	query	string	no
`cursor`	query	string	no

Responses: 200, 422

DELETE/api/v1/w/{workspace_id}/assets/{asset_id}Remove an image

Soft-delete an image. The file is removed later.

Scopes: assets:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes
`asset_id`	path	string (uuid)	yes

Responses: 200, 422

GET/api/v1/w/{workspace_id}/assets/{asset_id}Read an image

Read one image in this workspace.

Scopes: assets:read

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes
`asset_id`	path	string (uuid)	yes

Responses: 200, 422

POST/api/v1/w/{workspace_id}/assets/{asset_id}/completeComplete an image upload

Download the uploaded object, validate it, and mark it ready or rejected.

Scopes: assets:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes
`asset_id`	path	string (uuid)	yes

Responses: 200, 422

GET/api/v1/w/{workspace_id}/assets/{asset_id}/download-urlCreate a download URL

Short-lived URL for one ready file in this workspace. A video is served only as its signed copy (Content Credentials); a clip intermediate is never served.

Scopes: assets:read

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes
`asset_id`	path	string (uuid)	yes

Responses: 200, 422

POST/api/v1/w/{workspace_id}/assets/uploadsStart an image upload

Start a three-step image upload. The file is checked when it is completed.

Scopes: assets:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes

JSON body
Field	Type	Required
`filename`	string	yes
`mime`	string	yes
`bytes`	integer	yes
`sha256`	string	yes

Responses: 201, 422

POST/api/v1/w/{workspace_id}/assets/zipZip several files for download

Queue an asset.zip job (0 credits) that packs 1 to 100 ready files of this workspace into one zip. The job output is {asset_id}: download it with download-url like any file. A delivery is packed as its signed copy. The files may add up to 2 GB at most.

Scopes: jobs:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes

JSON body
Field	Type	Required
`asset_ids`	string (uuid)[]	yes

Responses: 202, 422

GET/api/v1/w/{workspace_id}/castList cast members

Scopes: jobs:read

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes

Responses: 200, 422

POST/api/v1/w/{workspace_id}/castCreate a cast member

Scopes: jobs:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes

JSON body
Field	Type	Required
`name`	string	yes
`visual_description`	string	yes

Responses: 202, 422

POST/api/v1/w/{workspace_id}/cast/{member_id}/approveApprove a cast portrait

Scopes: jobs:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes
`member_id`	path	string (uuid)	yes

JSON body
Field	Type	Required
`portrait_asset_id`	string (uuid)	yes

Responses: 200, 422

POST/api/v1/w/{workspace_id}/cast/{member_id}/revokeRevoke a cast member

Scopes: jobs:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes
`member_id`	path	string (uuid)	yes

Responses: 200, 422

POST/api/v1/w/{workspace_id}/estimateEstimate the credits for a job

Scopes: jobs:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes

JSON body
Field	Type	Required
`kind`	string	yes
`params`	object	no

Responses: 200, 422

GET/api/v1/w/{workspace_id}/eventsStream job events

Scopes: jobs:read

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes

Responses: 200, 422

GET/api/v1/w/{workspace_id}/jobsList jobs

Scopes: jobs:read

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes
`kind`	query	string	no
`status`	query	string	no
`cursor`	query	string	no
`limit`	query	integer	no

Responses: 200, 422

GET/api/v1/w/{workspace_id}/jobs/{job_id}Read a job

Scopes: jobs:read

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes
`job_id`	path	string (uuid)	yes

Responses: 200, 422

POST/api/v1/w/{workspace_id}/jobs/{job_id}/cancelCancel a job

Scopes: jobs:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes
`job_id`	path	string (uuid)	yes

Responses: 200, 422

GET/api/v1/w/{workspace_id}/productsList products

List products in this workspace.

Scopes: products:read

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes

Responses: 200, 422

POST/api/v1/w/{workspace_id}/productsCreate a product

Create a product.

Scopes: products:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes

JSON body
Field	Type	Required
`name`	string	no
`description`	string	no
`brand_id`	string (uuid)	no
`attributes`	object	no

Responses: 201, 422

DELETE/api/v1/w/{workspace_id}/products/{product_id}Remove a product

Soft-delete a product.

Scopes: products:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes
`product_id`	path	string (uuid)	yes

Responses: 200, 422

GET/api/v1/w/{workspace_id}/products/{product_id}Read a product

Read a product.

Scopes: products:read

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes
`product_id`	path	string (uuid)	yes

Responses: 200, 422

PATCH/api/v1/w/{workspace_id}/products/{product_id}Update a product

Update a product.

Scopes: products:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes
`product_id`	path	string (uuid)	yes

JSON body
Field	Type	Required
`name`	string	no
`description`	string	no
`brand_id`	string (uuid)	no
`attributes`	object	no

Responses: 200, 422

POST/api/v1/w/{workspace_id}/products/{product_id}/imagesAttach an image to a product

Attach a ready image from this workspace to a product.

Scopes: products:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes
`product_id`	path	string (uuid)	yes

JSON body
Field	Type	Required
`asset_id`	string (uuid)	yes
`role`	string	no
`caption`	string	no
`sort`	integer	no

Responses: 201, 422

DELETE/api/v1/w/{workspace_id}/products/{product_id}/images/{image_id}Detach an image from a product

Detach a product image.

Scopes: products:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes
`product_id`	path	string (uuid)	yes
`image_id`	path	string (uuid)	yes

Responses: 200, 422

POST/api/v1/w/{workspace_id}/products/import-urlImport a product from a URL

Queue a product import. Returns the cpu job. At most 20 images.

Scopes: products:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes

JSON body
Field	Type	Required
`url`	string	yes

Responses: 202, 422

POST/api/v1/w/{workspace_id}/tools/image-editCreate an image edit job

Scopes: jobs:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes

JSON body
Field	Type	Required
`prompt`	string	yes
`inputs`	string (uuid)[]	yes
`cast_member_id`	string (uuid)	no
`seed`	integer	no

Responses: 202, 422

POST/api/v1/w/{workspace_id}/tools/image-generateCreate an image generation job

Scopes: jobs:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes

JSON body
Field	Type	Required
`prompt`	string	yes
`negative`	string	no
`width`	integer	yes
`height`	integer	yes
`count`	integer	yes
`seed`	integer	no

Responses: 202, 422

POST/api/v1/w/{workspace_id}/tools/image-to-videoCreate an image-to-video job

Scopes: jobs:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes

JSON body
Field	Type	Required
`prompt`	string	yes
`negative`	string	no
`seconds`	integer	yes
`resolution`	string	yes
`input`	string (uuid)	no
`seed`	integer	no

Responses: 202, 422

POST/api/v1/w/{workspace_id}/tools/remove-backgroundCreate a background removal job

Scopes: jobs:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes

JSON body
Field	Type	Required
`input`	string (uuid)	yes

Responses: 202, 422

POST/api/v1/w/{workspace_id}/tools/text-to-videoCreate a text-to-video job

Scopes: jobs:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes

JSON body
Field	Type	Required
`prompt`	string	yes
`negative`	string	no
`seconds`	integer	yes
`resolution`	string	yes
`input`	string (uuid)	no
`seed`	integer	no

Responses: 202, 422

POST/api/v1/w/{workspace_id}/tools/upscaleCreate an upscale job

Scopes: jobs:write

Parameters
Name	In	Type	Required
`workspace_id`	path	string (uuid)	yes

JSON body
Field	Type	Required
`input`	string (uuid)	yes
`scale`	integer	yes

Responses: 202, 422