Attach media to a scene

The first editor-mutation primitive on the API: it shares the editor's media-attach service, so the change appears live in any open editor (via Realtime, applied in place) and behaves identically to picking media in the UI. Scene ids are globally unique, so the flat path is unambiguous.

Authorization

bearerAuth

AuthorizationBearer <token>

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

In: header

Path Parameters

sceneId*string

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

media_url*string

Public URL of the image or video to use as the scene background.

Formaturi

is_video?boolean

Set true when media_url points to a video.

thumbnail_url?|

Optional pre-generated thumbnail written to the scene chip.

Formaturi

Response Body

`application/json`

curl -X POST "https://example.com/scenes/497f6eca-6276-4993-bfeb-53cbbbba6f08/attach-media" \  -H "Content-Type: application/json" \  -d '{    "media_url": "http://example.com"  }'

{
  "data": {
    "scene_id": "861eef56-1159-4a95-802f-abab2d0cc192",
    "background": {
      "type": "image",
      "url": "http://example.com",
      "fit": "cover",
      "overflowBehavior": "loop",
      "muted": true,
      "volume": 0
    },
    "thumbnail_url": "string"
  }
}

{
  "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

Path Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`