Yapper Docs
Api reference
POST
/audio/speech

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.

Authorization

bearerAuth processes:write
AuthorizationBearer <token>

In: header

Scope: processes:write

Header Parameters

Idempotency-Key?string

Stable caller-provided key for retry-safe speech generation.

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/audio/speech" \  -H "Content-Type: application/json" \  -d '{    "script": "string"  }'
{  "data": {    "assetId": "string",    "type": "audio",    "url": "http://example.com",    "duration": 0,    "script": "string",    "voice": {      "voiceId": "string",      "provider": "string",      "name": "string"    },    "creditsCharged": 0,    "freeCharactersRemainingToday": 0  }}
{  "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"  }}

Edit a session's timeline POST

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.

Get agent usage GET

The in-app agent's usage for the current billing period: the included allowance shared by every chat, pay-as-you-go credits charged after it ran out, and the split by agent model. Matches the Agent Usage card on the account usage page.