DocsDevelopers

API reference

Every endpoint of the public API v1, with parameters and examples.

JSON over HTTPS at https://www.loudscene.com/api/v1. Authenticate with Authorization: Bearer ls_live_… (API keys, Pro plan and up). This page is generated from the same OpenAPI document the server validates with.

Basics#

Authentication: a workspace API key as a Bearer token.
Rate limits: per key, reported in RateLimit-* headers.
Idempotency: send Idempotency-Key on POST to retry safely.
Errors: one JSON shape, with a code and a request id.
Webhooks: signed events for generations, renders and comments.

OpenAPI 3.1 JSON Create an API key

Brand#

POST/api/v1/brand/extract

Extract a brand from a website

Starts a brand_extract job. Poll GET /v1/jobs/{id}; when it succeeds the new brand kit appears in GET /v1/brand-kits.

Parameters

Name	In	Description
`Idempotency-Key`	header	Optional. Retries with the same key and body get the first answer for 24 hours.

Body

Field	Type	Description
`url`required	`string`	Website address, e.g. https://example.com (https is added when missing)

Request

curl -X POST https://www.loudscene.com/api/v1/brand/extract \
  -H "Authorization: Bearer $LOUDSCENE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url":"https://yourbrand.com"}'

Response · 202 The extraction job

202 · Job

{
  "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "kind": "brand_extract",
  "status": "queued",
  "stage": null,
  "progress": 0,
  "error": null,
  "result": null,
  "created_at": "2026-09-26T12:00:00Z",
  "finished_at": null
}

Field	Type	Description
`id`required	`string (uuid)`
`kind`required	`string`
`status`required	`"queued" \| "running" \| "succeeded" \| "failed" \| "canceled"`
`stage`required	`string \| null`
`progress`required	`number`
`error`required	`string \| null`
`result`required	`object \| null`	Kind-specific result (stills: signed PNG URLs).
`created_at`required	`string (date-time)`
`finished_at`required	`string (date-time) \| null`

Errors: 400 invalid request (see error.details) · 401 missing, unknown, revoked or expired api key · 403 the workspace's plan does not include the api · 404 not found in this workspace · 429 rate limited (see retry-after). See Errors.

GET/api/v1/brand-kits

List brand kits

Every brand kit of the key's workspace, default first.

Request

curl -X GET https://www.loudscene.com/api/v1/brand-kits \
  -H "Authorization: Bearer $LOUDSCENE_API_KEY"

Response · 200 Brand kits

200 · BrandKitList

{
  "data": [
    {
      "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
      "name": "Acme",
      "source_url": "https://acme.com",
      "is_default": true,
      "tokens": {},
      "created_at": "2026-09-26T12:00:00Z",
      "updated_at": "2026-09-26T12:01:30Z"
    }
  ]
}

Field	Type	Description
`data`required	`BrandKit[]`

Stories#

GET/api/v1/stories

List stories

Built-in stories (templates) with their editable fields, usable as storyId in POST /v1/videos.

Request

curl -X GET https://www.loudscene.com/api/v1/stories \
  -H "Authorization: Bearer $LOUDSCENE_API_KEY"

Response · 200 Stories

200 · StoryList

{
  "data": [
    {
      "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
      "name": "Acme",
      "category": "launch",
      "description": "Launch a product in 30 seconds.",
      "default_duration_sec": 18.4,
      "fields": {}
    }
  ]
}

Field	Type	Description
`data`required	`object[]`

Videos#

POST/api/v1/videos

Create a video

With storyId + fields the video is built instantly from the story (no AI, status ready). Otherwise a generate job writes it from the brief (status generating; subscribe to the video.generated webhook or poll GET /v1/videos/{id}).

Parameters

Name	In	Description
`Idempotency-Key`	header	Optional. Retries with the same key and body get the first answer for 24 hours.

Body

Field	Type	Description
`title`	`string`
`brief`	`string`	What the video should say. Moderated before generation.
`storyId`	`string`	A story id from GET /v1/stories. With `fields`, the video is built instantly without AI.
`fields`	`object`	Field values for the story (requires storyId). Unknown keys are rejected.
`brandKitId`	`string (uuid)`	Brand kit to use. Defaults to the workspace's default kit when neither this nor url is given.
`url`	`string`	Extract the brand from this site first (when no brand kit is given).
`format`	`"16:9" \| "9:16" \| "1:1" \| "4:5"`	Main format. Default 16:9.
`durationSec`	`number`	From 6.
`locale`	`string`

Request

curl -X POST https://www.loudscene.com/api/v1/videos \
  -H "Authorization: Bearer $LOUDSCENE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url":"https://yourbrand.com","brief":"We just launched v2: twice as fast.","format":"9:16"}'

Response · 201 The new video

201 · Video

{
  "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "title": "Launch day",
  "status": "generating",
  "story_id": null,
  "brand_kit_id": "8d3f2c1e-5a4b-4c3d-9e8f-7a6b5c4d3e2f",
  "default_format": "16:9",
  "duration_sec": 18.4,
  "current_version": null,
  "job": {
    "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
    "kind": "generate",
    "status": "queued",
    "stage": "scenes",
    "progress": 0.4,
    "error": null,
    "result": null,
    "created_at": "2026-09-26T12:00:00Z",
    "finished_at": null
  },
  "created_at": "2026-09-26T12:00:00Z",
  "updated_at": "2026-09-26T12:01:30Z"
}

Field	Type	Description
`id`required	`string (uuid)`
`title`required	`string`
`status`required	`"draft" \| "generating" \| "ready" \| "failed" \| "archived"`
`story_id`required	`string \| null`
`brand_kit_id`required	`string (uuid) \| null`
`default_format`required	`"16:9" \| "9:16" \| "1:1" \| "4:5"`	Aspect ratio
`duration_sec`required	`number \| null`
`current_version`required	`object \| null`
`job`required	`object \| null`	The generation job, while one is running
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`

GET/api/v1/videos/:id

Get a video

The video and its current version (the full VideoDoc).

Parameters

Name	In	Description
`id`	path	The object's id (a UUID), required.

Request

curl -X GET https://www.loudscene.com/api/v1/videos/<id> \
  -H "Authorization: Bearer $LOUDSCENE_API_KEY"

Response · 200 The video

200 · Video

{
  "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "title": "Launch day",
  "status": "ready",
  "story_id": "product-launch",
  "brand_kit_id": "8d3f2c1e-5a4b-4c3d-9e8f-7a6b5c4d3e2f",
  "default_format": "16:9",
  "duration_sec": 18.4,
  "current_version": {
    "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
    "number": 1,
    "source": "api",
    "created_at": "2026-09-26T12:00:00Z",
    "doc": {}
  },
  "job": null,
  "created_at": "2026-09-26T12:00:00Z",
  "updated_at": "2026-09-26T12:01:30Z"
}

Field	Type	Description
`id`required	`string (uuid)`
`title`required	`string`
`status`required	`"draft" \| "generating" \| "ready" \| "failed" \| "archived"`
`story_id`required	`string \| null`
`brand_kit_id`required	`string (uuid) \| null`
`default_format`required	`"16:9" \| "9:16" \| "1:1" \| "4:5"`	Aspect ratio
`duration_sec`required	`number \| null`
`current_version`required	`object \| null`
`job`required	`object \| null`	The generation job, while one is running
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`

PATCH/api/v1/videos/:id

Update a video

Send a complete doc (linted server-side) or a fields patch; either way the result is saved as a new immutable version. title renames the video.

Parameters

Name	In	Description
`id`	path	The object's id (a UUID), required.

Body

Field	Type	Description
`doc`	`VideoDoc`	A complete VideoDoc. Its code is linted server-side; the result becomes a new version.
`fields`	`object`	Field values to change in the current version.
`title`	`string`
`note`	`string`	Shown in the version history.

Request

curl -X PATCH https://www.loudscene.com/api/v1/videos/<id> \
  -H "Authorization: Bearer $LOUDSCENE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"headline":"Now in 12 countries"},"note":"Weekly refresh"}'

Response · 200 The updated video

200 · Video

{
  "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "title": "Launch day",
  "status": "ready",
  "story_id": "product-launch",
  "brand_kit_id": "8d3f2c1e-5a4b-4c3d-9e8f-7a6b5c4d3e2f",
  "default_format": "16:9",
  "duration_sec": 18.4,
  "current_version": {
    "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
    "number": 1,
    "source": "api",
    "created_at": "2026-09-26T12:00:00Z",
    "doc": {}
  },
  "job": null,
  "created_at": "2026-09-26T12:00:00Z",
  "updated_at": "2026-09-26T12:01:30Z"
}

Field	Type	Description
`id`required	`string (uuid)`
`title`required	`string`
`status`required	`"draft" \| "generating" \| "ready" \| "failed" \| "archived"`
`story_id`required	`string \| null`
`brand_kit_id`required	`string (uuid) \| null`
`default_format`required	`"16:9" \| "9:16" \| "1:1" \| "4:5"`	Aspect ratio
`duration_sec`required	`number \| null`
`current_version`required	`object \| null`
`job`required	`object \| null`	The generation job, while one is running
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`

POST/api/v1/videos/:id/stills

Render still frames

Starts a stills job for the current version. When the job succeeds, GET /v1/jobs/{id} returns signed PNG URLs (valid 10 minutes).

Parameters

Name	In	Description
`id`	path	The object's id (a UUID), required.
`Idempotency-Key`	header	Optional. Retries with the same key and body get the first answer for 24 hours.

Body

Field	Type	Description
`times`required	`number[]`	Seconds into the video
`format`	`"16:9" \| "9:16" \| "1:1" \| "4:5"`	Aspect ratio

Request

curl -X POST https://www.loudscene.com/api/v1/videos/<id>/stills \
  -H "Authorization: Bearer $LOUDSCENE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"times":[1,4.5,9],"format":"1:1"}'

Response · 202 The stills job

202 · Job

{
  "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "kind": "stills",
  "status": "queued",
  "stage": null,
  "progress": 0,
  "error": null,
  "result": null,
  "created_at": "2026-09-26T12:00:00Z",
  "finished_at": null
}

Field	Type	Description
`id`required	`string (uuid)`
`kind`required	`string`
`status`required	`"queued" \| "running" \| "succeeded" \| "failed" \| "canceled"`
`stage`required	`string \| null`
`progress`required	`number`
`error`required	`string \| null`
`result`required	`object \| null`	Kind-specific result (stills: signed PNG URLs).
`created_at`required	`string (date-time)`
`finished_at`required	`string (date-time) \| null`

Renders#

POST/api/v1/videos/:id/renders

Render an MP4

Renders the current version in one format. One credit covers every format of a version up to 60 s. An identical finished render is returned instead of rendering again.

Parameters

Name	In	Description
`id`	path	The object's id (a UUID), required.
`Idempotency-Key`	header	Optional. Retries with the same key and body get the first answer for 24 hours.

Body

Field	Type	Description
`format`required	`"16:9" \| "9:16" \| "1:1" \| "4:5"`	Aspect ratio
`resolution`	`720 \| 1080 \| 2160`	Default 1080
`fps`	`24 \| 30 \| 60`	Default: the video's fps

Request

curl -X POST https://www.loudscene.com/api/v1/videos/<id>/renders \
  -H "Authorization: Bearer $LOUDSCENE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"format":"16:9","resolution":1080,"fps":30}'

Response · 202 The render

202 · Render

{
  "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "video_id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "version_id": "6c5b4a39-2817-4f6e-8d5c-4b3a29180f7e",
  "format": "16:9",
  "resolution": 1080,
  "fps": 30,
  "status": "queued",
  "progress": 0,
  "url": null,
  "poster_url": null,
  "duration_sec": null,
  "bytes": null,
  "error": null,
  "created_at": "2026-09-26T12:00:00Z",
  "finished_at": null
}

Field	Type	Description
`id`required	`string (uuid)`
`video_id`required	`string (uuid)`
`version_id`required	`string (uuid)`
`format`required	`"16:9" \| "9:16" \| "1:1" \| "4:5"`	Aspect ratio
`resolution`required	`integer`	From -9007199254740991.
`fps`required	`integer`	From -9007199254740991.
`status`required	`"queued" \| "running" \| "succeeded" \| "failed" \| "canceled"`
`progress`required	`number`
`url`required	`string \| null`	MP4 URL once succeeded
`poster_url`required	`string \| null`
`duration_sec`required	`number \| null`
`bytes`required	`integer \| null`
`error`required	`string \| null`
`created_at`required	`string (date-time)`
`finished_at`required	`string (date-time) \| null`

GET/api/v1/renders/:id

Get a render

Status, progress and, once succeeded, the MP4 and poster URLs.

Parameters

Name	In	Description
`id`	path	The object's id (a UUID), required.

Request

curl -X GET https://www.loudscene.com/api/v1/renders/<id> \
  -H "Authorization: Bearer $LOUDSCENE_API_KEY"

Response · 200 The render

200 · Render

{
  "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "video_id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "version_id": "6c5b4a39-2817-4f6e-8d5c-4b3a29180f7e",
  "format": "16:9",
  "resolution": 1080,
  "fps": 30,
  "status": "succeeded",
  "progress": 1,
  "url": "https://…/video.mp4",
  "poster_url": "https://…/poster.jpg",
  "duration_sec": 18.4,
  "bytes": 4839210,
  "error": null,
  "created_at": "2026-09-26T12:00:00Z",
  "finished_at": "2026-09-26T12:01:30Z"
}

Field	Type	Description
`id`required	`string (uuid)`
`video_id`required	`string (uuid)`
`version_id`required	`string (uuid)`
`format`required	`"16:9" \| "9:16" \| "1:1" \| "4:5"`	Aspect ratio
`resolution`required	`integer`	From -9007199254740991.
`fps`required	`integer`	From -9007199254740991.
`status`required	`"queued" \| "running" \| "succeeded" \| "failed" \| "canceled"`
`progress`required	`number`
`url`required	`string \| null`	MP4 URL once succeeded
`poster_url`required	`string \| null`
`duration_sec`required	`number \| null`
`bytes`required	`integer \| null`
`error`required	`string \| null`
`created_at`required	`string (date-time)`
`finished_at`required	`string (date-time) \| null`

POST/api/v1/videos/:id/variants

Render variants

Renders several formats at once, and optionally starts translated copies of the video (one new video per extra locale, each with its own translation job).

Parameters

Name	In	Description
`id`	path	The object's id (a UUID), required.
`Idempotency-Key`	header	Optional. Retries with the same key and body get the first answer for 24 hours.

Body

Field	Type	Description
`formats`required	`"16:9" \| "9:16" \| "1:1" \| "4:5"[]`
`locales`	`string[]`	Extra languages: each becomes a translated copy of the video (Pro and Agency).
`resolution`	`720 \| 1080 \| 2160`	Short side in pixels (2160 = 4K)

Request

curl -X POST https://www.loudscene.com/api/v1/videos/<id>/variants \
  -H "Authorization: Bearer $LOUDSCENE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"formats":["16:9","9:16","1:1","4:5"],"locales":["de","fr"]}'

Response · 202 Renders and translated copies

202 · Variants

{
  "renders": [
    {
      "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
      "video_id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
      "version_id": "6c5b4a39-2817-4f6e-8d5c-4b3a29180f7e",
      "format": "16:9",
      "resolution": 1080,
      "fps": 30,
      "status": "queued",
      "progress": 0.4,
      "url": "https://…/video.mp4",
      "poster_url": "https://…/poster.jpg",
      "duration_sec": 18.4,
      "bytes": 4839210,
      "error": null,
      "created_at": "2026-09-26T12:00:00Z",
      "finished_at": null
    }
  ],
  "translations": [
    {
      "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
      "title": "Launch day",
      "status": "draft",
      "story_id": "product-launch",
      "brand_kit_id": "8d3f2c1e-5a4b-4c3d-9e8f-7a6b5c4d3e2f",
      "default_format": "16:9",
      "duration_sec": 18.4,
      "current_version": {
        "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
        "number": 1,
        "source": "api",
        "created_at": "2026-09-26T12:00:00Z",
        "doc": {}
      },
      "job": {
        "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
        "kind": "generate",
        "status": "queued",
        "stage": "scenes",
        "progress": 0.4,
        "error": null,
        "result": null,
        "created_at": "2026-09-26T12:00:00Z",
        "finished_at": null
      },
      "created_at": "2026-09-26T12:00:00Z",
      "updated_at": "2026-09-26T12:01:30Z"
    }
  ]
}

Field	Type	Description
`renders`required	`Render[]`
`translations`required	`Video[]`

Jobs#

GET/api/v1/jobs/:id

Get a job

Progress and result of an asynchronous job (brand extraction, stills, generation).

Parameters

Name	In	Description
`id`	path	The object's id (a UUID), required.

Request

curl -X GET https://www.loudscene.com/api/v1/jobs/<id> \
  -H "Authorization: Bearer $LOUDSCENE_API_KEY"

Response · 200 The job

200 · Job

{
  "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "kind": "generate",
  "status": "running",
  "stage": "scenes",
  "progress": 0.4,
  "error": null,
  "result": null,
  "created_at": "2026-09-26T12:00:00Z",
  "finished_at": null
}

Field	Type	Description
`id`required	`string (uuid)`
`kind`required	`string`
`status`required	`"queued" \| "running" \| "succeeded" \| "failed" \| "canceled"`
`stage`required	`string \| null`
`progress`required	`number`
`error`required	`string \| null`
`result`required	`object \| null`	Kind-specific result (stills: signed PNG URLs).
`created_at`required	`string (date-time)`
`finished_at`required	`string (date-time) \| null`