Yapper Docs
Api reference
POST
/sessions/{sessionId}/timeline/edits

Applies operations in order and saves them together; when any fails, nothing is saved and the error names it. Makes the timeline when the session has none. A timeline open in the web app picks the edit up live, and a concurrent edit returns conflict. Free. Uses the processes:write scope.

Operations, as { type, ...fields } (? = optional):

  • addVideoClip: assetId, startTime?, track?, trimStart?, trimEnd?, ref?
  • addImageClip: assetId, duration?, startTime?, track?, ref?
  • addAudioClip: assetId, startTime?, track?, trimStart?, trimEnd?, volumePercent?, volumeDecibels?, ref?
  • moveClip: clipId, startTime?, track?
  • trimClip: clipId, trimStart, trimEnd
  • setClipVolume: clipId, volumePercent?, volumeDecibels?
  • transformClip: clipId, x?, y?, scale?, rotation?, reset?
  • removeClip: clipId
  • setTransition: leftClipId, rightClipId, transition?, durationSeconds?, easing?
  • removeTransition: leftClipId, rightClipId
  • setClipLook: clipId, opacityPercent?, blendMode?, filter?, filterIntensityPercent?, adjustments?
  • setClipKeyframes: clipId, property, keyframes
  • addText: text, startTime, duration?, fontFamily?, fontSize?, color?, textAlign?, fontWeight?, letterSpacing?, lineHeight?, backgroundEnabled?, backgroundColor?, backgroundCornerRadius?, strokeEnabled?, strokeColor?, strokeWidth?, positionX?, positionY?, ref?
  • updateText: textClipId, text?, startTime?, duration?, fontFamily?, fontSize?, color?, textAlign?, fontWeight?, letterSpacing?, lineHeight?, backgroundEnabled?, backgroundColor?, backgroundCornerRadius?, strokeEnabled?, strokeColor?, strokeWidth?, positionX?, positionY?
  • removeText: textClipId
  • removeAllCaptions
  • styleCaptions: fontFamily?, fontSize?, color?, textAlign?, fontWeight?, letterSpacing?, lineHeight?, backgroundEnabled?, backgroundColor?, backgroundCornerRadius?, strokeEnabled?, strokeColor?, strokeWidth?, positionX?, positionY? Times are seconds on the timeline; trimStart/trimEnd are seconds into the source media. Tracks run 1-8 and track 1 is the top layer, drawn over the tracks below (overlays, picture-in-picture). New clips default to track 1 (audio: track 2), placed at the end of that track. assetId is a team asset from yapper_list_assets of the matching type (images last 5s unless duration is set). ref names a new clip so later operations in the same call can use it as clipId, textClipId, leftClipId or rightClipId. transformClip: x and y move the clip center by fractions of the frame, scale 1 fills the frame, rotation in degrees. setTransition: the two clips must touch on one track; transition is dissolve, dip-to-black, dip-to-white, slide-left, slide-right, wipe-left, wipe-right, zoom-in or blur-dissolve. setClipKeyframes: property x, y, scale, rotation, opacity or volume; keyframes [{ time (seconds from the clip's start), value, easing? }], and [] removes the animation. Text: fontSize is relative (captions about 5, titles 8-14), positionX/positionY run -0.5 to 0.5 from the frame center, and any Google Fonts family works. Unknown values fail with the allowed list.

Authorization

bearerAuth processes:write
AuthorizationBearer <token>

In: header

Scope: processes:write

Path Parameters

sessionId*string

Header Parameters

Idempotency-Key?string

Optional key that makes the edit safe to retry: a retry with the same key and body returns the first response (Idempotency-Replayed: true, with the timeline as it is now) instead of editing again, and the same key with a different body returns idempotency_conflict. Scoped to the credential and session.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/sessions/string/timeline/edits" \  -H "Content-Type: application/json" \  -d '{    "operations": [      {        "type": "addVideoClip"      }    ]  }'
{  "sessionId": "string",  "exists": true,  "name": "string",  "duration": 0,  "clips": [    {      "clipId": "string",      "kind": "video",      "assetId": "string",      "track": 1,      "startTime": 0,      "endTime": 0,      "trimStart": 0,      "trimEnd": 0,      "volume": 0    }  ],  "transitions": [    {}  ],  "textClips": [    {}  ],  "mutedTracks": [    0  ],  "gaps": [    {}  ],  "revision": 0,  "updatedAt": "2019-08-24T14:15:22Z",  "webUrl": "http://example.com",  "created": true,  "applied": [    "string"  ],  "refs": {    "property1": "string",    "property2": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Unwire two canvas cards DELETE

Removes the wires from the source card into the target card, on every port or only targetPort. not_found when there is no such wire. Shows up live on the canvas in the Yapper web app. Free. Uses the processes:write scope.

Generate speech audio POST

Legacy synchronous text-to-speech compatibility endpoint for ElevenLabs and Cartesia. New integrations should use audio-generation via POST /processes plus GET /audio/voices so model capabilities, references, process polling, and output lineage match image/video generation. This endpoint still generates spoken audio from a script and stores it as a team audio asset (readable via GET /assets/{assetId} and listed by GET /assets). No polling — the response returns the finished asset. Pass a voiceId from a previous response to reuse a voice, or a voiceQuery (e.g. "warm female narrator") to pick one by description; omitting both uses a neutral narrator. The first 5,000 script characters per team per UTC day are free; characters beyond that bill team credits at 30 credits per 1,000 characters for ElevenLabs voices or 15 credits per 1,000 characters for Cartesia voices (403 insufficient_credits when the team balance cannot cover the request). The response reports creditsCharged and freeCharactersRemainingToday. Always send an Idempotency-Key: retries with the same key and body replay the original response (Idempotency-Replayed: true) instead of double-billing and double-generating; the same key with a different body returns idempotency_conflict.