Yapper Docs
Api reference
POST
/sessions

Creates a session to group related generations in the Yapper web app. Pass its id as sessionId on POST /processes, POST /assets/import, and POST /assets/uploads. Free. Uses the processes:write scope.

Authorization

bearerAuth processes:write
AuthorizationBearer <token>

In: header

Scope: processes:write

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

curl -X POST "https://example.com/sessions" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "title": "string",  "imageUrl": "http://example.com",  "imageAssetId": "string",  "generations": {    "inProgress": 0,    "completed": 0  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "webUrl": "http://example.com",  "links": {    "self": "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"  }}

Create a media process POST

Starts a generation process and charges team credits. V1 types: image-generation, video-generation, audio-generation, image-upscale, video-upscale, video-lipsync, background-removal, music-generation. The model must match the type (see GET /models). music-generation runs on elevenlabs-music: durationSeconds sets the exact length (10 to 300 seconds, default 60) and the price. Write lyrics into prompt under [Verse]/[Chorus] headings to have them sung as written, or set instrumental: true for no vocals; style and title are optional, and prompt, style and title together may be 4100 characters. Describe the sound rather than naming an artist or song to imitate; those prompts are refused. The Suno model "music" appears in GET /models but cannot be started through the API. For seedance-2.5-edit, the first referenceVideos item is the required base video; editOperation defaults to edit, while extend, sequel, and prequel allow an omitted prompt. On seedance-2.5 and seedance-2.5-edit, every 480p run is a draft by default (send draft: false for a plain 480p render; draft: true also sets resolution 480), and draftVideoId (a draft's output assetId) on seedance-2.5 finishes that same shot within 7 days, edit drafts included, at resolution 1080 (the default) or 2160 (4K) as the draft's draft.finishResolutions lists; send at most resolution with it, since every other input comes from the draft. video-lipsync takes sourceVideoAssetId and audioAssetId from the team asset library; the server-measured audio duration determines its quote and charge. Sync-Max is train-once: omit trainingId on the first run, then reuse the trainingId returned on the process for faster later runs against the same trained source. Sync-Pro and Sync-v3 are single-shot and require no training. Always send an Idempotency-Key: retries with the same key and body return the original process instead of double-charging; the same key with a different body returns idempotency_conflict. input is validated per process type AND against the model's published capabilities (aspectRatios, resolutions, videoLengths from GET /models) — unsupported values are rejected with invalid_request, never silently coerced. Internal fields (batchId, filteringId, agent context) are ignored; pass sessionId instead to group the process and its outputs in a session (see /sessions), plus workspaceFolderId to file the outputs into a folder of that session's workspace as they finish, and editor: true to make it an edit in that session's Editor (its outputs join the Editor strip). libraryFolderId (any process, with or without a session) files the outputs into a Library folder as they finish, before the webhook. background-removal takes imageAssetId (a team image) or imageUrl (imported first). metadata (flat string/number/boolean/null values, max 16 keys) is echoed back on reads. webhookSecret is optional for legacy unsigned webhook delivery; when supplied with webhookUrl, notifications are HMAC-signed and may be attempted twice with a stable delivery id.

Add a webhook endpoint POST

Sends workspace events to url as signed JSON POSTs: { id, type, createdAt, data }. Events: process.completed: A generation finished with outputs. process.failed: A generation failed. asset.created: A new image, video or audio asset appeared: a generation output, an upload or an import. asset.favorited: An asset was favorited. asset.unfavorited: An asset was unfavorited. asset.filed: An asset was put in a folder: a session workspace folder or a Library folder (data.folder gives its kind, id, name and path). credits.alert: A credit alert rule fired (GET /credit-alerts): the balance dropped below its level, or a member or API key reached its share of a credit limit or its spend this month. data.rule names it. Each request carries X-Yapper-Event-Id, X-Yapper-Event-Type, X-Yapper-Delivery-Id, X-Yapper-Timestamp and X-Yapper-Signature, which is one or more comma-separated v1=<hex> values, each the HMAC-SHA256 of `<X-Yapper-Timestamp>.<raw body>` with a signing secret: accept the request if any matches. Answer 2xx within 10 seconds. Anything else is retried after 1m, 5m, 30m, 2h, 6h, 12h, 24h, then given up (catch up with GET /events). Delivery is at least once and unordered: dedupe on the event id. An endpoint with no successful delivery for 3 days is disabled. It only receives events for assets and processes its creator can read. At most 10 endpoints per workspace.