Docs / Get started
Core concepts
5 minute read · Updated 2026-09-11
Six objects carry everything. A workspace owns artists; an artist owns songs; songs and generations produce media assets; an artstyle keeps those assets looking related; and anything that takes minutes to render becomes a job.
The object model
| Object | What it is |
|---|---|
| workspace | The tenant. Every row in the system belongs to exactly one, and your API token authenticates as one. Also called an organization. |
| artist | A project or act. A workspace can hold several; how many depends on your plan. |
| song | An uploaded track with its audio, lyrics, and any saved waveform regions. |
| media_asset | Anything generated or uploaded — images, clips, finished videos. Assets link back to the song they belong to. |
| artstyle | A reusable visual definition. Pass it to a pipeline and every image it generates shares a look. |
| job | A unit of long-running work — every render is one. Has a status, a log, and eventually a result. |
Almost every write tool takes an `artist_id`, and most also take a `song_id`. Read them once at the start of a session with `list_artists` and `list_songs`, then reuse the ids — they are stable.
Tenancy
Your token resolves to exactly one workspace, and every request runs fully scoped to it. There is no cross-workspace read: a tool that lists "all songs" lists all songs *you* own.
This means the token is the tenant boundary. Treat it like a password — anyone holding it can read your library and spend your credits. Rotate it if it leaks.
Sync work and job work
This is the distinction that matters most when writing against the API, so it is worth stating plainly up front.
Reads, record writes, and single-image generation are synchronous — you call, you get the result. Anything that assembles video is not: it runs on a render worker with ffmpeg and a headless browser, takes minutes, and returns a job id immediately.
| Kind | Returns | Examples |
|---|---|---|
| sync | The result, directly. | list_songs, find_song, generate_image, generate_content_ideas, create_artstyle |
| job | { job_id, kind } — poll it. | run_studio_pipeline_inline, run_lyric_video_inline, run_clip_assembly_inline, start_studio_with_favorites |
A job id is not a result. See Jobs for the full lifecycle.
Credits
Reads are free. Generation is metered in credits, reserved when work starts and refunded if it fails. Your plan sets the monthly allowance; the current balance and the per-plan figures are on the billing page in the app rather than duplicated here, where they would drift.
Keep going