Credits, keys and workspaces

Callable by name

Not listed on connect, to keep the list short. Call them directly by name, or find them with tools.

apply_brand_kit

Use a workspace's brand kit in a project

Copy a workspace's brand kit overlays into a project as the project's own list, to edit for this film or to use ANOTHER workspace's kit (any workspace of the account). Without workspace_id, the project's own workspace. A project with no list of its own already shows its workspace's kit. Free.

apply_brand_pack

Apply a branding pack to a project

Apply one of the workspace's packs to a project: its theme, then its channel mark, then its overlays. A piece the pack does not carry is left alone. The steps are not one transaction: if a step fails, the error lists the steps already applied. Themes apply to new scenes; scenes already made keep their look. Free.

create_budget

Give a sub-agent a capped budget

Creates a hard-capped budget and returns an api_key bound to it, shown once, to hand to an agent you spawn. That key can read anything this account can, and quote, hold and create smaller budgets inside its own; it cannot spend past its cap, nor past any budget it nests in. Called with a budget key, the new budget nests in yours. Other spending calls are not yet open to budget keys (they return budget_key_scope). Revoke with revoke_budget.

create_cli_token

Key for a CLI session on one project

Mint a long-lived API key scoped to ONE project, for a command-line session on the user's machine (typecut dev, typecut add, or plain curl): it lasts days (default 30, up to 90) instead of the connector's hour or an upload link's 2 hours. Send it as Authorization: Bearer <token> to https://app.typecut.ai/api/v1. It reaches only this project (read, edit, export/import its HyperFrames folder, render) and POST /uploads, which files local images, video and other files into it; it cannot mint further keys. The token is shown once: hand it to the CLI (e.g. TYPECUT_TOKEN in the environment), never paste it into a scene. The user can revoke it in Settings → API keys. Free.

create_workspace

Create a workspace

Create a workspace — one per brand, channel or client. It holds the defaults its projects inherit (language, aspect ratio, and later voice, theme, branding) and is the boundary a workspace-scoped API key is locked to. Free; plan-limited: over the limit it returns 402 plan_limit_reached with limit and current — tell the user, do not retry. Check list_workspaces first and reuse a workspace that already fits instead of making a near-duplicate. Needs an account-level key (a workspace-scoped key gets 403). Returns the id to pass as workspace_id to create_project.

get_budget

Read a budget

Free. A budget's cap, spent, held and remaining (the least left anywhere up its chain).

get_price_book

Read every price

Free. The whole price book: one line per thing that costs credits (image, video, voice per character, music, transcription, composition, render, analysis, the production base per minute), each classed pass-through (model generation) or tool (Typecut's own work), in credits and USD at list (1 credit = $0.01). Use it to budget before you plan; use estimate_project to price one project. price_book_version changes whenever any price does. A non-empty drift means an estimate may differ from the charge — say so.

No inputs.

hold_credits

Reserve credits

Reserves credits so parallel work cannot spend them: pass a quote_id (holds its credits_max) or credits. Moves no credits; lowers credits_available on get_account until released or expired (ttl_seconds, default 3600). Pass idempotency_key so a retry returns the same hold. Release it with release_hold when the work is done or abandoned.

list_brand_packs

List a workspace's branding packs

The branding packs a workspace keeps: each one a name plus a theme, a channel mark and overlay rules. Apply one to a project with apply_brand_pack. Free, reads only.

list_workspaces

List workspaces

List the workspaces (channels) on this account. A workspace carries the defaults a new project inherits — language, aspect ratio, voice, branding — so start here when creating a project and the user has not said where it belongs. If exactly one workspace exists, just use it without asking.

No inputs.

quote

Quote operations before running them

Free; spends nothing, holds nothing. Prices a list of operations against the price book and returns credits_expected and credits_max (and USD at list), per line and in total, with a quote_id and the price_book_version it was priced from. Operations: {type:"generation", slug, quantity?, units?, provider?} for a price-book line (units = characters for TTS, seconds for per-second lines); {type:"scenes", media_source, count, quality_tier?}; {type:"project", template_slug?, duration_seconds?, ...} (same inputs as estimate_project; add authoring:"own" when you write every scene yourself, so no scene media is priced). Budget against credits_max. bound:"estimate" means nothing enforces the max yet; the receipt (get_generation / get_project) says what was charged.

release_hold

Release a credit hold

Gives back what a hold still reserves. Safe to retry: a closed hold reports released: 0.

revoke_budget

Revoke a budget

Stops a budget and every budget under it: their keys stop working and their holds are released. Idempotent.

save_brand_pack

Create or replace a branding pack

Create a branding pack in a workspace, or replace the pack with the same id. A pack is: id (lowercase, up to 40), name, and any of theme_slug (a theme from list_catalog("themes")), mark (the channel mark: url, position, scale, opacity, formula; null to take it off) and overlays (rules, as set_overlays). Upload a logo first with create_upload and pass its public_url as mark.url. The free-plan Typecut watermark is not part of a pack. Up to 12 packs a workspace. Free.

set_brand_kit

Set a workspace's brand kit overlays

Set the overlay rules of a WORKSPACE's brand kit (the whole list, same rule shape as set_overlays). Every project in the workspace that has no overlay list of its own shows them, with no work per project: set the logo, the subscribe button and the end card once. Free.

set_branding

Put the channel mark on a project, and give it motion

Set the pinned brand mark (the corner "bug") on a project: image, corner, size, opacity, and a MOTION FORMULA. Until this tool the mark was reachable only from the settings panel, so a film built through the API came out unbranded even for a channel that has a logo. Every field is optional and only what you send changes; sending a url for an unbranded project turns the mark on. formula is what makes it live, and it is EITHER a built-in slug OR any active row author_formula has written — list_formulas is the current catalog. On the notated clock: "none" is a static stamp (the default), "corner" fades it up over a small rise, "pop" snaps it in, "breather" sways once a bar, "tick" squashes it on every downbeat of the project's own measured grid, "ghost" rests it low and lifts it on a scene cue. On the MEASURED clock, off the analysed audio: "pulse" breathes the mark with the narration, "goo" puts a white backdrop behind it whose contour rides the voice, "halo" surrounds it with a field of reaching bars. These need a scene whose audio has been analysed — get_scene_context reports which sources a scene has, and a look that follows audio the scene does not have simply holds still. The motion is compiled against the same bars the composition uses, so it lands with the music rather than near it; with no measured score it falls back to a steady grid. Amplitudes are capped and ticks have a cooldown — a mark cannot be made to strobe. Free, and it changes nothing else about the project. Re-render to see it in the MP4.

set_environment

Which environment does my work run on?

Free. Without environment: where this account's calls run now ({environment, source, switchable, worker, choices}). With environment ("staging" or "production"): switch it. Admin accounts only; for everyone else it is production and cannot change. Staging runs every call from this account (its agents, keys and browser) on the staging worker, to test a change before production gets it; switch back to production when done. Effective from the next call.

set_project_role

Mark a project reference (read-only) or working

A project, scene or link you were handed to LEARN FROM is read-only context unless the user says "work in" it. role "reference" marks it: reads and copy_scenes from it still work, but any mutating tool aimed at it is refused unless the call repeats confirm_project_id (the user said to). role "working" releases it, and needs confirm_project_id = project_id. Use "reference" on the project behind a link you were given to take style from. Free.

set_workspace_mix_profile

Read or set a workspace's default audio mix

Read or set the workspace's DEFAULT mix profile: how music ducks under voice (mix: mode bed|off and the duck dials) and where the voice / music / sfx buses sit (voMasterVolume / musicMasterVolume / sfxMasterVolume, 0..2). Set it once and every project created in that workspace afterwards starts with it — no per-project mixing, which is what makes projects made in bulk or by agents sound right without review. A new project takes, in order: the project named by create_project mix_from_project_id, else this default, else the standard (music ducks under voice); an explicit mix in the creation still wins. Existing projects are never changed — use set_mix on those. No arguments beyond workspace_id = read (profile is null when none is set). from_project_id copies that project's current profile (duck + bus levels; film-specific moments are never copied) into the workspace default — the quickest way: mix one project by ear with set_mix, then adopt it. profile sets it directly, in the shape a read returns; clear: true removes it. Needs edit rights on the workspace.