Create a project

Mode-discriminated by mode:

templates — runs the full plan → scaffold → generate pipeline from a template + a topic (prompt) or your own script (markdown-structured supported). The main path.
blank — an empty project with one chapter, no planning; edit it via later API calls.

For templates, call GET /v1/projects/requirements first to learn the required inputs (and preview a script's parsed structure).

Authorization

bearerAuth

AuthorizationBearer <token>

Typecut API key. Generate one in app.typecut.ai → Settings → API keys. Send as Authorization: Bearer tc_live_….

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

mode*string

Creation mode "templates" runs the full plan → scaffold → generate pipeline from a template + a topic (prompt) or your own script.

Value in"templates"

templateSlug*string

Template to generate from (its scene vocabulary + pacing). Required.

Length1 <= length <= 200

workspaceId?|

Workspace to place the project in. Required when the account has multiple workspaces (else a 422 lists the candidates); omitted for workspace-scoped keys.

Formatuuid

prompt?string

A topic/brief — the model writes the script. Provide this OR script.

Length1 <= length <= 20000

sources?array<>

Reference links to ground the generation. We read each (article text, YouTube transcript, PDF, or a website's pages) into a structured digest that feeds the script. The kind is detected server-side.

Itemsitems <= 15

script?string

Your own finished narration, used as the source. Provide this OR prompt. May be a markdown document (see scriptFormat): # Title, ## Chapters, paragraphs become beats. Text is used verbatim (see scriptFidelity).

Length1 <= length <= 100000

scriptFidelity?string

How faithfully to keep your script. 'verbatim' (segment only, never reword) or 'adapt' (default — the model may restructure/rephrase).

Value in"verbatim" | "adapt"

scriptFormat?string

How to parse script into chapters/blocks. 'auto' (default) detects markdown headings (#/##); 'markdown' forces it; 'plaintext' treats it as flat prose. With markdown headings, ## define chapters and # becomes the project title.

Value in"markdown" | "plaintext" | "auto"

name?string

Project name. Defaults to the script # H1, else the topic, else the template.

Length1 <= length <= 200

usePresets?boolean

Fill unset fields from the workspace presets (voice, captions, etc.). Default true.

bulkGenerate?boolean

Run generation (TTS + scenes) after scaffolding. Default true. False = plan only.

ttsPresetId?|

Voice (tts_presets id). Required unless the workspace has a default voice.

Formatuuid

durationSeconds?integer

Target length (prompt mode). Ignored in verbatim script mode (length is implied).

Range5 <= value <= 7200

aspectRatio?string

Aspect ratio. Defaults to the workspace preset, else 16:9.

Value in"16:9" | "9:16" | "4:3" | "1:1"

musicTrackId?|

Optional background music (music_tracks id; see GET /v1/catalogs/music).

Formatuuid

audio?

Audio mix masters (0–2), mirroring the editor VO/Music/SFX faders. Each is applied multiplicatively in the render mix. Omit any to keep the editor-neutral default (vo 1, music 0.3, sfx 0.7). Read back via GET /v1/projects/{id} → audio.

logo?

Channel logo / watermark — a static image pinned to a corner of every scene. scale is logo width as a fraction of video width (default 0.12). Omit to inherit the workspace branding preset. Read back via GET /v1/projects/{id} → logo.

mode*string

Creation mode. "blank" creates an empty project with one chapter, no LLM planning. Additional modes (e.g. "prompt") will be added in a future release.

Value in"blank"

name?string

Project name. Defaults to "Untitled Project".

Length1 <= length <= 200

workspaceId?|

Workspace to place the project in. Required for workspace-scoped API keys (may be omitted — the scoped workspace is used).

Formatuuid

aspectRatio?string

Project aspect ratio. Defaults to "16:9".

Value in"16:9" | "9:16" | "4:3" | "1:1"

ttsPresetId?|

Optional default TTS preset for the project.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/projects" \  -H "Content-Type: application/json" \  -d '{    "mode": "templates",    "templateSlug": "narrative"  }'

{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "ready",
    "generationId": "c95151f1-2c42-47db-881c-ef453e626e62",
    "editor_url": "https://app.typecut.ai/project/52e088d6-345f-47f5-86af-31b694175f8e",
    "credit_cost": 0,
    "credits_remaining": 0
  }
}

{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

402application/json

403application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`