REST API · v1 · reference

API reference

Every endpoint of https://actoria.ai/api/v1, generated from the same schemas the server validates against. Authenticate with Authorization: Bearer act_live_…; GET endpoints take query parameters, POST endpoints a JSON body. Field names match the MCP tools one to one. Machine-readable version: openapi.json; guides and examples in the overview.

account

Who you are: plan, balance, limits, models and prices.

GET/api/v1/accountscope read · tool get_account

Account, balance and limits

Who you are in Actoria: plan, token balance, whether generation is allowed, and the hard limits (actors per frame, reference caps per model, parallel videos, upload sizes). Call first in a session.

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/account" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

GET/api/v1/modelsscope read · tool list_models

Generation models

Models available for frames (first frame of a scene), final frames and videos: which are enabled, the default, duration ranges, resolutions, cost in tokens, reference caps and what each model needs (a frame, references). Disabled models are listed with enabled=false and can't be used.

Query parameters

category enum Omit for all categoriesframevideofinalFrame

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/models" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

GET/api/v1/estimatescope read · tool estimate_cost

Estimate cost

Token cost of a frame, a video or a recast before generating it (duration/resolution are clamped to the model's range, see applied). Recast is charged per second of the source video.

Query parameters

kindrequired	enum	`framevideorecast`
videoModel	enum	Video/recast only; default seedance (recast: seedance \| seedance_20 \| seedance_mini)`wan22h3h3_hqwan3seedanceseedance_miniseedance_15seedance_20`
durationS	integer (1–30)	Video/recast only; default 5 (recast: length of the source video)
resolution	enum	Video/recast only; default 720p`720p1080p4k`

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/estimate?kind=frame" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

library

Actors, props and locations — the reusable references.

GET/api/v1/actorsscope read · tool list_actors

List actors

Your saved actors (characters). usable=false means the actor can't be filmed yet: a photo actor needs face verification on the website, a synthetic actor needs a portrait (create_actor generates it). Use actor ids in references.

Query parameters

limit

integer (1–200)

default: 100

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/actors" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

GET/api/v1/propsscope read · tool list_props

List props

Your saved props (objects/products with reference images). Props with an image are reproduced exactly; props without one participate as text.

Query parameters

limit

integer (1–200)

default: 100

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/props" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

GET/api/v1/locationsscope read · tool list_locations

List locations

Your saved locations (places/settings). At most one location per scene.

Query parameters

limit

integer (1–200)

default: 100

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/locations" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

GET/api/v1/library/searchscope read · tool search_references

Search library

Case-insensitive substring search over your actors, props and locations by name/description. Returns ids to use in references.

Query parameters

queryrequired	string (≤ 80 chars)
kinds	array<enum>	Default: all kinds

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/library/search?query=%E2%80%A6" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

POST/api/v1/actorsscope generate · tool create_actor

Create an actor

Create a character. source=prompt: a synthetic actor from a description/traits — a portrait sheet is generated (costs tokens, returns a job to wait_job). source=photo: a REAL person from their photo (portrait of exactly one adult) — requires consent=true and the person must pass a face check by camera; the tool returns a verification link and the actor is unusable until verified. Never describe celebrities or real people in prompts.

Request body (application/json)

namerequired	string (≤ 60 chars)
source	enum	`promptphoto`default: "prompt"
prompt	string (≤ 1000 chars)	Free-text appearance for synthetic actors (fictional)
traits	object
↳gender	enum	`malefemale`
↳age	enum	`18–2525–3535–4545–6060+`
↳ethnicity	string (≤ 40 chars)
↳build	string (≤ 40 chars)
↳height	string (≤ 20 chars)
↳hair	string (≤ 80 chars)
↳eyes	string (≤ 40 chars)
↳outfit	string (≤ 120 chars)
↳vibe	string (≤ 80 chars)
↳extra	string (≤ 200 chars)
image	one of	photo only: {type: url\|base64} of the person's portrait, or {type: asset} of a previously uploaded actor photo
↳type: "actor"	object
↳typerequired	const "actor"
↳idrequired	string	Saved actor id (act_…) from list_actors. Photo actors must be verified.
↳type: "prop"	object
↳typerequired	const "prop"
↳idrequired	string	Saved prop id (prp_…) from list_props
↳type: "location"	object
↳typerequired	const "location"
↳idrequired	string	Saved location id (loc_…) from list_locations; at most one per scene
↳type: "asset"	object
↳typerequired	const "asset"
↳idrequired	string	Asset id (ast_…) returned by upload_reference; its kind decides how it is used
↳type: "frame"	object
↳typerequired	const "frame"
↳sceneId	string	Own scene id — takes that scene's frame
↳which	enum	Which frame of the scene: last = last frame of its finished video (best for continuation), first, final`firstlastfinal`default: "last"
↳url	string	Alternatively an exact frame URL previously returned by list_frames / get_scene / wait_job (must be your own)
↳type: "url"	object
↳typerequired	const "url"
↳urlrequired	string (≤ 2048 chars, URL)	Public https URL of a PNG/JPEG/WebP (≤12 MB). Fetched, moderated and stored as an asset.
↳kindrequired	enum	How to use the image: frame = first frame the video starts from (no people allowed); prop = object/product to reproduce exactly; location = place/setting reference`frameproplocation`
↳name	string (≤ 60 chars)	Short name used in prompts (e.g. 'red sneaker')
↳prompt	string (≤ 500 chars)	Text description of the object/place for the prompt
↳type: "base64"	object
↳typerequired	const "base64"
↳datarequired	string	Base64 image data (data: URL prefix allowed). Decoded size ≤ 3 MB — prefer 'url' for larger images.
↳mimeType	enum	`image/pngimage/jpegimage/webp`
↳kindrequired	enum	How to use the image: frame = first frame the video starts from (no people allowed); prop = object/product to reproduce exactly; location = place/setting reference`frameproplocation`
↳name	string (≤ 60 chars)
↳prompt	string (≤ 500 chars)
consent	boolean	photo only: you confirm the right to use this person's likeness and that they will pass the face check themselvesdefault: false
generatePortrait	boolean	prompt only: start the portrait job right away (needed before filming)default: true
callbackUrl	string (≤ 2048 chars, URL)	Webhook: https URL that receives a signed POST (job.succeeded / job.failed) when the portrait job finishes — see /developers

Responses: 201· errors as {error, code} — see errors

curl -X POST https://actoria.ai/api/v1/actors \
  -H "Authorization: Bearer $ACTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'

POST/api/v1/actors/{actorId}/verificationscope generate · tool verify_actor

Face verification link

Status of a photo actor's face verification and a FRESH verification link (links expire within minutes — request a new one right before use). The person in the photo opens the link on their phone and passes the camera check; after that the actor becomes usable in generations. Already verified actors are reported as such without a new link.

Path parameters

actorIdrequired

string

Photo actor id (act_…) from list_actors or create_actor

Responses: 200· errors as {error, code} — see errors

curl -X POST https://actoria.ai/api/v1/actors/act_…/verification \
  -H "Authorization: Bearer $ACTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

references

Direct images (URL, base64 or multipart) as temporary references.

POST/api/v1/referencesscope upload · tool upload_reference

Upload a reference image

Store an image (https URL or small base64) as a reference asset: kind=frame — a first frame to animate (must contain NO people); kind=prop — an object/product; kind=location — a place/setting. The image is moderated like website uploads. Assets expire in 7 days unless save_to_library=true (prop/location become library items). Reference the result as {type: "asset", id}. Real faces are rejected here — use create_actor(source: "photo") for people.

Request body (application/json)

kindrequired	enum	How to use the image: frame = first frame the video starts from (no people allowed); prop = object/product to reproduce exactly; location = place/setting reference`frameproplocation`
sourcerequired	one of
↳type: "url"	object
↳typerequired	const "url"
↳urlrequired	string (≤ 2048 chars, URL)	Public https URL of a PNG/JPEG/WebP, ≤ 12 MB
↳type: "base64"	object
↳typerequired	const "base64"
↳datarequired	string	Base64 image data (data: URL prefix allowed), decoded ≤ 3 MB — prefer url for larger files
↳mimeType	enum	`image/pngimage/jpegimage/webp`
name	string (≤ 60 chars)	Short name used in prompts and the library
prompt	string (≤ 500 chars)	Text description for prompts (material, colour, what matters)
save_to_library	boolean	prop/location only: keep it permanently as a library itemdefault: false

Responses: 201· errors as {error, code} — see errors

curl -X POST https://actoria.ai/api/v1/references \
  -H "Authorization: Bearer $ACTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"frame","source":{"type":"url","url":"https://…"}}'

POST/api/v1/references/uploadscope upload · tool upload_reference

Upload a reference image (multipart)

Form fields (multipart/form-data)

filerequired	string	PNG, JPEG or WebP, ≤ 12 MB
kindrequired	enum	frame — a first frame to animate (no people); prop — an object; location — a place`frameproplocation`
name	string (≤ 60 chars)
prompt	string (≤ 500 chars)
save_to_library	boolean	prop/location only: keep it permanently as a library itemdefault: false

Responses: 201· errors as {error, code} — see errors

curl -X POST https://actoria.ai/api/v1/references/upload \
  -H "Authorization: Bearer $ACTORIA_API_KEY" \
  -F "file=@photo.png" \
  -F "kind=prop"

photos

Standalone photos — a prompt plus references, no project needed.

POST/api/v1/photosscope generate · tool generate_photo

Generate a photo

Generate a standalone photo from a prompt and optional references (saved actors/props/location by id, or direct images with kind prop/location) — no project or scene needed; the result appears under Photos on the Videos tab. Takes 10–60 s, so by default the call waits and returns the image. Costs the frame price (estimate_cost kind=frame). Frame-kind references are ignored — the photo is the frame. Real faces only via verified photo actors.

Request body (application/json)

promptrequired	string (≤ 6000 chars)	What the photo shows, in English (mention saved references by name if you like)
references	array<one of> (≤ 12 items)	Actors (≤3 for 16:9, ≤2 otherwise), props, one location, or direct images with kind prop/locationdefault: []
↳type: "actor"	object
↳typerequired	const "actor"
↳idrequired	string	Saved actor id (act_…) from list_actors. Photo actors must be verified.
↳type: "prop"	object
↳typerequired	const "prop"
↳idrequired	string	Saved prop id (prp_…) from list_props
↳type: "location"	object
↳typerequired	const "location"
↳idrequired	string	Saved location id (loc_…) from list_locations; at most one per scene
↳type: "asset"	object
↳typerequired	const "asset"
↳idrequired	string	Asset id (ast_…) returned by upload_reference; its kind decides how it is used
↳type: "frame"	object
↳typerequired	const "frame"
↳sceneId	string	Own scene id — takes that scene's frame
↳which	enum	Which frame of the scene: last = last frame of its finished video (best for continuation), first, final`firstlastfinal`default: "last"
↳url	string	Alternatively an exact frame URL previously returned by list_frames / get_scene / wait_job (must be your own)
↳type: "url"	object
↳typerequired	const "url"
↳urlrequired	string (≤ 2048 chars, URL)	Public https URL of a PNG/JPEG/WebP (≤12 MB). Fetched, moderated and stored as an asset.
↳kindrequired	enum	How to use the image: frame = first frame the video starts from (no people allowed); prop = object/product to reproduce exactly; location = place/setting reference`frameproplocation`
↳name	string (≤ 60 chars)	Short name used in prompts (e.g. 'red sneaker')
↳prompt	string (≤ 500 chars)	Text description of the object/place for the prompt
↳type: "base64"	object
↳typerequired	const "base64"
↳datarequired	string	Base64 image data (data: URL prefix allowed). Decoded size ≤ 3 MB — prefer 'url' for larger images.
↳mimeType	enum	`image/pngimage/jpegimage/webp`
↳kindrequired	enum	How to use the image: frame = first frame the video starts from (no people allowed); prop = object/product to reproduce exactly; location = place/setting reference`frameproplocation`
↳name	string (≤ 60 chars)
↳prompt	string (≤ 500 chars)
aspect	enum	`16:99:161:14:5`default: "16:9"
frameModel	enum	See list_models (category frame); default: admin default, else Nano Banana with actors / Seedream without`nanobananakrea2qwenseedreamfarm`
wait	boolean	Wait for the result and return the imagedefault: true
waitTimeoutS	integer (5–120)	default: 90
callbackUrl	string (≤ 2048 chars, URL)	Webhook: https URL that receives a signed POST (job.succeeded / job.failed) when the job finishes — see /developers

Responses: 201202· errors as {error, code} — see errors

curl -X POST https://actoria.ai/api/v1/photos \
  -H "Authorization: Bearer $ACTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"…"}'

GET/api/v1/photosscope read · tool list_photos

List photos

Your standalone photos (generate_photo / the Photos section of the Videos tab), newest first — finished ones with URLs, plus pending and failed ones.

Query parameters

limit	integer (1–100)	default: 20
status	enum	done — only finished photos; pending — only generating/failed`alldonepending`default: "all"

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/photos" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

GET/api/v1/photos/{photoId}scope read · tool get_photo

Photo status

A photo made with generate_photo: status (queued/running/succeeded/failed), ETA, and the image URL when ready.

Path parameters

photoIdrequired

string

photoId from generate_photo / list_photos (prj_…)

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/photos/prj_…" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

generation

First frames and videos inside projects and scenes.

GET/api/v1/framesscope read · tool list_frames

List reusable frames

Recent frames you own (first/final/last frames of scenes, keyframes) — reuse them as {type: "frame", url} references or continue from a scene's last frame. withProvenance reports whether a frame can be animated by Seedance 2.5/2.0/Lite (only frames of BytePlus origin can).

Query parameters

projectId	string
limit	integer (1–50)	default: 20
withProvenance	boolean	Also report seedanceCompatible per frame (reads files, slower)default: false

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/frames" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

GET/api/v1/videosscope read · tool list_videos

List videos

Generated videos: scene clips and finished films (Repository). Use ids/URLs for audio tools, continuation and downloads.

Query parameters

projectId	string
limit	integer (1–50)	default: 20
include	enum	`scenesfinalall`default: "all"

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/videos" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

POST/api/v1/framesscope generate · tool generate_frame

Generate a first frame

Create the first frame (still image) of a scene from a prompt and references — saved actors/props/location by id or direct images (url/base64 with kind prop/location). Creates a project and a scene when none is given; frames take 10–60 s, so by default the call waits and returns the image. Costs tokens (see estimate_cost). Not needed for video models that build the scene from references (Seedance 2.5/2.0/Lite, H3/Wan 3 without a frame) — generate_video can go straight from references.

Request body (application/json)

prompt	string (≤ 9500 chars)	Frame composition and setting, in English. Required unless references include an actor or a locationdefault: ""
references	array<one of> (≤ 12 items)	Actors (≤3 for 16:9, ≤2 otherwise), props, one location, or direct images (kind prop/location). Frame-kind references are not allowed heredefault: []
↳type: "actor"	object
↳typerequired	const "actor"
↳idrequired	string	Saved actor id (act_…) from list_actors. Photo actors must be verified.
↳type: "prop"	object
↳typerequired	const "prop"
↳idrequired	string	Saved prop id (prp_…) from list_props
↳type: "location"	object
↳typerequired	const "location"
↳idrequired	string	Saved location id (loc_…) from list_locations; at most one per scene
↳type: "asset"	object
↳typerequired	const "asset"
↳idrequired	string	Asset id (ast_…) returned by upload_reference; its kind decides how it is used
↳type: "frame"	object
↳typerequired	const "frame"
↳sceneId	string	Own scene id — takes that scene's frame
↳which	enum	Which frame of the scene: last = last frame of its finished video (best for continuation), first, final`firstlastfinal`default: "last"
↳url	string	Alternatively an exact frame URL previously returned by list_frames / get_scene / wait_job (must be your own)
↳type: "url"	object
↳typerequired	const "url"
↳urlrequired	string (≤ 2048 chars, URL)	Public https URL of a PNG/JPEG/WebP (≤12 MB). Fetched, moderated and stored as an asset.
↳kindrequired	enum	How to use the image: frame = first frame the video starts from (no people allowed); prop = object/product to reproduce exactly; location = place/setting reference`frameproplocation`
↳name	string (≤ 60 chars)	Short name used in prompts (e.g. 'red sneaker')
↳prompt	string (≤ 500 chars)	Text description of the object/place for the prompt
↳type: "base64"	object
↳typerequired	const "base64"
↳datarequired	string	Base64 image data (data: URL prefix allowed). Decoded size ≤ 3 MB — prefer 'url' for larger images.
↳mimeType	enum	`image/pngimage/jpegimage/webp`
↳kindrequired	enum	How to use the image: frame = first frame the video starts from (no people allowed); prop = object/product to reproduce exactly; location = place/setting reference`frameproplocation`
↳name	string (≤ 60 chars)
↳prompt	string (≤ 500 chars)
sceneId	string	Regenerate the frame of an existing scene (given references replace its cast/props/location)
projectId	string	Add a new scene to this project; omitted → a new project is created
aspect	enum	New project only`16:99:161:14:5`default: "16:9"
projectTitle	string (≤ 80 chars)
frameModel	enum	Default: admin default, else Nano Banana with actors / Seedream without. Props with images force nanobanana`nanobananakrea2qwenseedreamfarm`
wait	boolean	Wait for the result and return the imagedefault: true
waitTimeoutS	integer (5–120)	default: 90
callbackUrl	string (≤ 2048 chars, URL)	Webhook: https URL that receives a signed POST (job.succeeded / job.failed) when the job finishes — see /developers

Responses: 201202· errors as {error, code} — see errors

curl -X POST https://actoria.ai/api/v1/frames \
  -H "Authorization: Bearer $ACTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

POST/api/v1/videosscope generate · tool generate_video

Generate a video

Generate a scene video. Sources: an existing scene (sceneId — uses its first frame), a continuation (continueFromSceneId — starts from that scene's last frame, same models and camera), or a new scene built from references (actors/props/location by id, or direct images). Optional first frame: {type: "frame", sceneId|url} or an uploaded image {type: url|base64|asset, kind: "frame"} — note Seedance 2.5/2.0/Lite only animate frames of their own origin (use seedance_15, h3, wan3 or wan22 for uploaded frames). Videos take 1–15 minutes: the call returns a job — poll with wait_job. Costs tokens (estimate_cost).

Request body (application/json)

prompt	string (≤ 9500 chars)	What happens in the shot (action, dialogue in quotes, camera notes), in English. Required for new scenesdefault: ""
references	array<one of> (≤ 12 items)	Optional first frame (at most one), actors, props, one locationdefault: []
↳type: "actor"	object
↳typerequired	const "actor"
↳idrequired	string	Saved actor id (act_…) from list_actors. Photo actors must be verified.
↳type: "prop"	object
↳typerequired	const "prop"
↳idrequired	string	Saved prop id (prp_…) from list_props
↳type: "location"	object
↳typerequired	const "location"
↳idrequired	string	Saved location id (loc_…) from list_locations; at most one per scene
↳type: "asset"	object
↳typerequired	const "asset"
↳idrequired	string	Asset id (ast_…) returned by upload_reference; its kind decides how it is used
↳type: "frame"	object
↳typerequired	const "frame"
↳sceneId	string	Own scene id — takes that scene's frame
↳which	enum	Which frame of the scene: last = last frame of its finished video (best for continuation), first, final`firstlastfinal`default: "last"
↳url	string	Alternatively an exact frame URL previously returned by list_frames / get_scene / wait_job (must be your own)
↳type: "url"	object
↳typerequired	const "url"
↳urlrequired	string (≤ 2048 chars, URL)	Public https URL of a PNG/JPEG/WebP (≤12 MB). Fetched, moderated and stored as an asset.
↳kindrequired	enum	How to use the image: frame = first frame the video starts from (no people allowed); prop = object/product to reproduce exactly; location = place/setting reference`frameproplocation`
↳name	string (≤ 60 chars)	Short name used in prompts (e.g. 'red sneaker')
↳prompt	string (≤ 500 chars)	Text description of the object/place for the prompt
↳type: "base64"	object
↳typerequired	const "base64"
↳datarequired	string	Base64 image data (data: URL prefix allowed). Decoded size ≤ 3 MB — prefer 'url' for larger images.
↳mimeType	enum	`image/pngimage/jpegimage/webp`
↳kindrequired	enum	How to use the image: frame = first frame the video starts from (no people allowed); prop = object/product to reproduce exactly; location = place/setting reference`frameproplocation`
↳name	string (≤ 60 chars)
↳prompt	string (≤ 500 chars)
sceneId	string	Animate an existing scene
continueFromSceneId	string	Chain: new scene starting from the last frame of this finished scene (cast/location inherited unless references override them)
projectId	string	Add a new scene to this project; omitted → new project
aspect	enum	New project only`16:99:161:14:5`default: "16:9"
projectTitle	string (≤ 80 chars)
videoModel	enum	See list_models; default: admin default or the project's last scene model`wan22h3h3_hqwan3seedanceseedance_miniseedance_15seedance_20`
durationS	integer (1–30)	Clamped to the model's range/steps — see applied.durationS
resolution	enum	1080p: seedance/seedance_15/seedance_20/wan3; 4k: seedance_20 only; others 720p`720p1080p4k`
motion	enum	`lowmediumhigh`
camera	enum	`staticpandollyorbithandheld`
audio	boolean	Generate sound (default true; wan22 is always silent)
wait	boolean	Wait up to waitTimeoutS for the result (prefer wait_job polling)default: false
waitTimeoutS	integer (5–120)	default: 120
callbackUrl	string (≤ 2048 chars, URL)	Webhook: https URL that receives a signed POST (job.succeeded / job.failed) when the job finishes — see /developers

Responses: 201202· errors as {error, code} — see errors

curl -X POST https://actoria.ai/api/v1/videos \
  -H "Authorization: Bearer $ACTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

jobs

Status and long-polling of generation jobs.

GET/api/v1/jobs/{jobId}scope read · tool get_job

Job status

Status of a generation job (queued/running/succeeded/failed), ETA, and the result URL when done. Failed jobs refund their tokens. Accepts frame/video jobs (job_…) and recast jobs (v2v_…: preparing/ready/running/done/failed with a stage).

Path parameters

jobIdrequired

string

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/jobs/job_…" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

GET/api/v1/jobs/{jobId}/waitscope read · tool wait_job

Wait for a job

Block up to timeoutS (max 240) seconds for a job to finish, streaming progress; returns the result with a small preview image (frame or video poster) and links to the full files. If it times out (timedOut=true) simply call it again.

Path parameters

jobIdrequired

string

Query parameters

timeoutS

integer (5–120)

default: 60

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/jobs/job_…/wait" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

projects

Projects, scenes, script-to-video and assembly.

GET/api/v1/projectsscope read · tool list_projects

List projects

Your projects (a project = aspect ratio + ordered scenes). Generation tools create a project automatically when none is given.

Query parameters

limit

integer (1–200)

default: 50

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/projects" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

GET/api/v1/projects/{projectId}scope read · tool get_project

Get project with scenes

A project and all its scenes (cast, props, frames, video URLs, active jobs, autorun state).

Path parameters

projectIdrequired

string

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/projects/prj_…" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

GET/api/v1/scenes/{sceneId}scope read · tool get_scene

Get scene

One scene: prompts, models, cast, props, location, frames (first/final/last), video URL, keyframes and the active job if any.

Path parameters

sceneIdrequired

string

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/scenes/scn_…" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

POST/api/v1/projects/from-scriptscope generate · tool create_script_video

Video from a script

Turn a script (10–20000 chars, English preferred; Russian is translated) into a project with scenes: the text is split by paragraphs/time-codes, cast is matched by names, camera/motion inferred. With autorun=true the server pipeline generates every scene's frame and video and (assemble=true) stitches the film — follow progress with get_project; the finished film appears in list_videos (final). Creation itself is free; generation charges tokens per scene.

Request body (application/json)

scriptrequired	string (≤ 20000 chars)
title	string (≤ 80 chars)	default: ""
aspect	enum	`16:99:161:14:5`default: "16:9"
style	string	default: "cinematic"
actorIds	array<string> (≤ 10 items)	default: []
locationId	string \| null	default: null
propIds	array<string> (≤ 8 items)	default: []
templateId	string \| null	default: null
sceneDurations	array<number (1–60)> (≤ 40 items) \| null	default: null
exact	boolean	default: false
videoModel	enum \| null	default: null
sceneLenS	enum \| null	default: null
resolution	enum \| null	default: null
camera	enum \| null	default: null
motion	enum \| null	default: null
singleScene	boolean \| null	default: null
autorun	boolean	Start the generation pipeline right awaydefault: true
assemble	boolean	Stitch the film when all scenes are ready (1 token per scene)default: true
audio	boolean	Voice the farm scenes (V2A) before assemblingdefault: false

Responses: 201· errors as {error, code} — see errors

curl -X POST https://actoria.ai/api/v1/projects/from-script \
  -H "Authorization: Bearer $ACTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"script":"…"}'

POST/api/v1/projects/{projectId}/finishscope generate · tool finish_project

Finish (assemble the film)

Stitch all scenes with videos into one film (Repository). Takes up to a couple of minutes; returns the final video. 1 token per scene.

Path parameters

projectIdrequired

string

Responses: 200· errors as {error, code} — see errors

curl -X POST https://actoria.ai/api/v1/projects/prj_…/finish \
  -H "Authorization: Bearer $ACTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

POST/api/v1/projects/{projectId}/autorun/stopscope generate · tool stop_autorun

Stop the pipeline

Stop a running script pipeline (the current generation finishes normally, nothing new starts).

Path parameters

projectIdrequired

string

Responses: 200· errors as {error, code} — see errors

curl -X POST https://actoria.ai/api/v1/projects/prj_…/autorun/stop \
  -H "Authorization: Bearer $ACTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

audio

Speech, sound effects, captions and audio edits.

GET/api/v1/audio/sourcesscope read · tool list_audio_sources

Audio sources

Videos and scene clips you can add speech/sound/captions to (ids for the audio tools).

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/audio/sources" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

POST/api/v1/audio/speechscope generate · tool generate_speech

Speech from text (TTS)

Synthesize a voice line for a video/scene (5 tokens). Returns an audio asset (poll get_audio_asset until done), then place it with apply_audio_edit. Voices: Wise_Woman (Wise woman), Calm_Woman (Calm woman), Lively_Girl (Lively girl), Sweet_Girl_2 (Sweet girl), Friendly_Person (Friendly person), Deep_Voice_Man (Deep voice man), Casual_Guy (Casual guy), Patient_Man (Patient man), Elegant_Man (Elegant man), Young_Knight (Young knight).

Request body (application/json)

kindrequired	enum	video = a finished film from list_videos(final); scene = a scene clip`videoscene`
idrequired	string (≤ 64 chars)	final video id (fv_…) or scene id (scn_…)
textrequired	string (≤ 5000 chars)
voice	enum	`Wise_WomanCalm_WomanLively_GirlSweet_Girl_2Friendly_PersonDeep_Voice_ManCasual_GuyPatient_ManElegant_ManYoung_Knight`
speed	number (0.5–2)	1 = normal

Responses: 202· errors as {error, code} — see errors

curl -X POST https://actoria.ai/api/v1/audio/speech \
  -H "Authorization: Bearer $ACTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"video","id":"…","text":"…"}'

POST/api/v1/audio/sound-effectsscope generate · tool generate_sound_effect

AI sound for a fragment

Generate ambient/foley sound for a 1–30 s fragment of a video/scene (video-to-audio; cost as for scene sound). Returns an audio asset to poll with get_audio_asset.

Request body (application/json)

kindrequired	enum	video = a finished film from list_videos(final); scene = a scene clip`videoscene`
idrequired	string (≤ 64 chars)	final video id (fv_…) or scene id (scn_…)
startSrequired	number (0–3600)
endSrequired	number (0–3600)
prompt	string (≤ 500 chars)	What the sound should be (optional)

Responses: 202· errors as {error, code} — see errors

curl -X POST https://actoria.ai/api/v1/audio/sound-effects \
  -H "Authorization: Bearer $ACTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"video","id":"…","startS":1,"endS":1}'

POST/api/v1/audio/transcriptionsscope generate · tool transcribe_audio

Auto captions (speech recognition)

Transcribe the speech of a video/scene (whole or a fragment) into timed captions (5 tokens, Whisper). Poll get_audio_asset; the transcript arrives in asset.transcript.captions — put them into apply_audio_edit captions.

Request body (application/json)

kindrequired	enum	video = a finished film from list_videos(final); scene = a scene clip`videoscene`
idrequired	string (≤ 64 chars)	final video id (fv_…) or scene id (scn_…)
startS	number (0–3600)
endS	number (0–3600)

Responses: 202· errors as {error, code} — see errors

curl -X POST https://actoria.ai/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $ACTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"video","id":"…"}'

GET/api/v1/audio/assets/{assetId}scope read · tool get_audio_asset

Audio asset status

Status of a speech/sound/caption asset: running → done (url, durationS, transcript) or failed (tokens refunded).

Path parameters

assetIdrequired

string

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/audio/assets/aud_…" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

POST/api/v1/audio/editsscope generate · tool apply_audio_edit

Apply an audio edit

Render and save an audio edit onto a video/scene: mutes (intervals), clips (placed audio assets from generate_speech/generate_sound_effect with gains) and burnt-in captions. The file is replaced in place; the original is kept for revert on the website. edl: {v: 1, mutes: [{start, end}], clips: [{id, assetId, start, gain?, baseGain?, trimEnd?}], captions?: [{id, start, end, text, pos?, size?}]}.

Request body (application/json)

kindrequired	enum	video = a finished film from list_videos(final); scene = a scene clip`videoscene`
idrequired	string (≤ 64 chars)	final video id (fv_…) or scene id (scn_…)
edlrequired	object
↳vrequired	const 1
↳mutesrequired	array<object> (≤ 64 items)
↳startrequired	number (0–3600)
↳endrequired	number (0–3600)
↳clipsrequired	array<object> (≤ 32 items)
↳idrequired	string (≤ 40 chars)
↳assetIdrequired	string
↳startrequired	number (0–3600)
↳gain	number (0–2)
↳baseGain	number (0–1)
↳trimEnd	number (0.05–3600)
↳captions	array<object> (≤ 200 items)
↳idrequired	string (≤ 40 chars)
↳startrequired	number (0–3600)
↳endrequired	number (0–3600)
↳textrequired	string (≤ 300 chars)
↳pos	enum	`topmiddlebottom`
↳size	enum	`sml`
↳clipId	string (≤ 40 chars)
baseUrl	string (≤ 300 chars)	The source URL you edited (optional consistency check)

Responses: 200· errors as {error, code} — see errors

curl -X POST https://actoria.ai/api/v1/audio/edits \
  -H "Authorization: Bearer $ACTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"video","id":"…","edl":{"v":1,"mutes":[],"clips":[]}}'

recast

Recast (video → video) with your actors.

GET/api/v1/recast/sourcesscope read · tool list_recast_sources

Recast sources

Everything needed for a recast: your finished videos (4–30 s are eligible), uploaded reference videos (status ready/preparing), actors usable for recast (synthetic actors with a Seedream portrait, verified photo actors), props and locations with images, the models with per-second prices and limits, and the pending job if one is running.

Responses: 200· errors as {error, code} — see errors

curl "https://actoria.ai/api/v1/recast/sources" \
  -H "Authorization: Bearer $ACTORIA_API_KEY"

POST/api/v1/recast/uploadsscope upload · tool upload_recast_video

Upload a reference video for recast

Fetch a video by public https URL (MP4/MOV/WebM, 4–60 s, ≤100 MB, short side ≥300 px) and register it as a recast reference: frames are moderated, then the job becomes `ready` (poll get_job). Only 30 s are used. You must hold the rights to the footage and the consent of the people in it (rightsConfirmed=true). One upload at a time, daily limit applies. Free — the recast itself is charged.

Request body (application/json)

urlrequired	string (≤ 2048 chars, URL)	Public https URL of the video file
title	string (≤ 80 chars)	Name for the source (default: file name)
rightsConfirmed	boolean	You confirm the rights to this footage and the consent of the people in itdefault: false

Responses: 202· errors as {error, code} — see errors

curl -X POST https://actoria.ai/api/v1/recast/uploads \
  -H "Authorization: Bearer $ACTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://…"}'

POST/api/v1/recastsscope generate · tool recast

Recast a video

Recast (video → video): take the motion, camera and timing from a source video and replace the people in it with your actors (in order of first appearance, ≤4), optionally props and a location. Source: your finished video (4–30 s) or an upload from upload_recast_video (status ready). Charged per second of the source (see list_recast_sources prices); one recast at a time; takes minutes — poll with wait_job. Seedance 2.5 handles up to 30 s (2.0 / Lite up to 15 s).

Request body (application/json)

sourcerequired	one of
↳type: "video"	object
↳typerequired	const "video"
↳idrequired	string	Your finished video id (fin_…) from list_videos(final) / list_recast_sources
↳type: "upload"	object
↳typerequired	const "upload"
↳jobIdrequired	string	Upload id (v2v_…) from upload_recast_video, status ready
actors	array<string> (≤ 4 items)	Actor ids in order of first appearance in the video (≤4). Photo actors must be verified; synthetic actors need a Seedream portraitdefault: []
props	array<string> (≤ 8 items)	Prop ids with images to feature exactly as pictureddefault: []
locationId	string	Location id with an image — replaces the video's setting
description	string (≤ 500 chars)	What to change besides the people (clothes, mood, setting) — English preferred. Motion, camera and timing always follow the video
prompt	string (≤ 10000 chars)	Advanced: a full prompt sent as is instead of the generated one
model	enum	seedance = 2.5 (≤30 s, 720p/1080p); seedance_20 (≤15 s, up to 4k); seedance_mini (≤15 s, 720p)`seedanceseedance_20seedance_mini`default: "seedance"
resolution	enum	`720p1080p4k`default: "720p"
generateAudio	boolean	Let Seedance generate a soundtrack (off by default)default: false
keepDialogue	boolean	Put the source's original soundtrack on the resultdefault: true
wait	boolean	Wait up to waitTimeoutS for the result (prefer wait_job polling — recasts take minutes)default: false
waitTimeoutS	integer (5–120)	default: 120
callbackUrl	string (≤ 2048 chars, URL)	Webhook: https URL that receives a signed POST (job.succeeded / job.failed) when the job finishes — see /developers

Responses: 201202· errors as {error, code} — see errors

curl -X POST https://actoria.ai/api/v1/recasts \
  -H "Authorization: Bearer $ACTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":{"type":"video","id":"…"}}'

Errors

Every error is JSON with a human-readable error and a stable code. Validation errors add issues, payment errors add url, rate limits add retryAfterS and a Retry-After header. One long-poll (GET /jobs/{jobId}/wait) is capped at 120 s.

invalid_request	422	The request body or query doesn't match the schema (see `issues`).
invalid_json	400	The body is not valid JSON.
invalid_token	401	Missing, unknown, revoked or expired API key / token.
insufficient_scope	403	The key lacks the scope the endpoint needs (`scope` says which).
forbidden	403	The account is blocked.
verify_email	403	Confirm your e-mail on the website first.
paywall	402	No active subscription or not enough tokens (`kind`, `required`, `available`, `url`).
not_found	404	Unknown endpoint, or the object doesn't exist / isn't yours.
scene_busy	409	The scene already has a running job.
concurrent_limit	409	Too many videos rendering at once for your plan (`lane`, `limit`).
payload_too_large	413	The request body exceeds the cap.
prompt_unsafe	422	The prompt mentions minors or other prohibited content (`term`).
actor_unverified	422	A photo actor hasn't passed the face check (`url`).
moderation_rejected	422	The image failed moderation (people in a frame/prop/location reference, explicit content).
model_disabled	422	The requested model is switched off — see GET /models.
launch_rejected	422	The generation rules rejected the request (message explains).
rate_limited	429	Slow down and retry after `retryAfterS` seconds (`Retry-After` header).
provider_unavailable	502	The generation provider failed; tokens are refunded.
disabled	503	The API is temporarily switched off by the administrator.
internal	500	Unexpected error on our side.