Yapper Docs

Quickstart

Create a key, check credits, and poll your first process.

1. Create a team API key

Open Account → API, give the key a name that identifies its person, app, or environment (for example, “Production app”), choose its permissions, and create it. All permissions are selected by default. Save the secret immediately — Yapper only shows the full secret once.

Workspace owners and admins can choose Edit API key from a key’s actions menu, including keys previously named “Default key”. Names can contain up to 80 characters. You can update the name and permissions without rotating the secret or losing usage history. Renaming alone does not change access.

Use the key as a bearer token:

export YAPPER_API_KEY="yap_live_..."

API key permissions

Keys belong to the workspace where they were created. A key's name is a label; it does not transfer ownership or restrict access to a particular person or integration. Keys act as their creator and require that person to remain a member of the workspace. API access requires an active paid subscription. Owner and admin API keys with billing:read can retrieve billing history after cancellation.

New keys start with the Processes, Assets, Models, and Usage permissions selected. Use the Read and Write checkboxes to select what your integration needs. Read and write are independent: selecting write does not automatically grant read access. Each key's saved permissions are shown in Account → API and loaded when you edit it.

Permission changes apply to subsequent requests immediately. Requests requiring a removed permission return 403 with missing_scope; running generations continue. Clearing all permissions leaves the key with no authenticated API access. Editing a revoked key does not reactivate it.

PermissionAccess
processes:readList workspace processes and poll their status and outputs. Read sessions, including each session's conversation with the Yapper agent, its workspace, and its canvas.
processes:writeStart media generations and speech generation, or request generation quotes. Edit session workspaces and canvases, and run canvas cards.
assets:readList and fetch workspace assets.
assets:writeImport media from URLs and upload local media.
models:readRead available models and schemas, voices, skills, and the authenticated workspace context.
usage:readRead workspace credit balance, usage, spend breakdowns, the credit log, storage, and the member list (names and emails).
sharing:writeManage project access and send invitations. Owner and admin keys can list, resend, and revoke pending invitations.
billing:readList Stripe invoices and receipts for the workspace. Requires an owner or admin API key.
limits:writeSet or clear member credit limits and credit alerts (owner or admin API key), and mute alerts that email you (any member).

Sharing, Billing, and Credit limits are opt-in for new keys.

Workspace administration

  • Use GET /api/v1/billing/invoices for invoice status, amounts, and PDF links, and GET /api/v1/billing/receipts for successful Stripe charges with receipt links. Amounts use the currency's minor unit. Pass the returned nextCursor to fetch the next page, including when a page has no visible entries.
  • Use GET /api/v1/members/invites to find the pending invitation's email and inviteRef. Pass both in the body of POST /api/v1/members/invites/resend or POST /api/v1/members/invites/revoke. Resending renews the expiration and schedules an email. Only workspace owners can manage admin invitations.
  • Use PATCH /api/v1/members/{userId}/credit-limit with {"creditLimit": 5000, "creditLimitPeriod": "monthly"}. Use "lifetime" for a lifetime cap or null as the limit to clear it. Admins can manage members and guests. Owners can also manage admins.

These permissions apply to the public API endpoints, not every feature in the Yapper app. Workspace processes and assets include those created through the app, not just those created by the key. Generations spend shared workspace credits and remain subject to usage limits and rate limits. Keys do not provide public API access to billing changes, member management, or API key management.

Use the model catalog and API reference for currently supported generation types, models, and request parameters.

2. Check credits

API requests spend the same workspace credits as the team.

curl https://yapper.so/api/v1/credits \
  -H "Authorization: Bearer $YAPPER_API_KEY"
{
  "totalCredits": 5000,
  "usedCredits": 1240,
  "availableCredits": 3760,
  "purchaseUrl": "https://yapper.so/settings/usage?tab=credits"
}

3. List models

curl https://yapper.so/api/v1/models \
  -H "Authorization: Bearer $YAPPER_API_KEY"

4. List and poll processes

Generations started in the Yapper app show up here too — the API and app share one team workspace.

curl "https://yapper.so/api/v1/processes?status=completed&limit=5" \
  -H "Authorization: Bearer $YAPPER_API_KEY"

Poll one process:

curl https://yapper.so/api/v1/processes/PROCESS_ID \
  -H "Authorization: Bearer $YAPPER_API_KEY"

Public statuses: queued, processing, completed, failed.

While a process is queued or processing, the response includes suggestedPollAfterSeconds. Wait that long before polling again: it tracks the time left on the estimate, then drops to short checks once the estimate has passed.

Completed response:

{
  "id": "proc_abc123",
  "type": "image-generation",
  "status": "completed",
  "model": "gpt-image-2",
  "creditsUsed": 12,
  "outputs": [
    {
      "type": "image",
      "assetId": "asset_img_123",
      "url": "https://...",
      "width": 1024,
      "height": 1024,
      "duration": null,
      "mimeType": "image/png"
    }
  ],
  "links": { "self": "/api/v1/processes/proc_abc123" }
}

5. Start a process

POST /api/v1/processes starts a generation and spends team credits. Send an Idempotency-Key header for retry-safe creation:

curl -X POST https://yapper.so/api/v1/processes \
  -H "Authorization: Bearer $YAPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: job_123" \
  -d '{
    "type": "image-generation",
    "model": "gpt-image-2",
    "input": {
      "prompt": "A polished product photo of a stainless steel water bottle",
      "aspectRatio": "1:1",
      "resolution": "1080"
    }
  }'

Test without spending

Add "testMode": true to the same body to try your whole flow for free. The request is checked like a real one and a process is created, but no model runs and no credits are charged. About 2 seconds later it completes with the standard "This is a test asset" image, video or audio clip, at the closest common aspect ratio. It is saved to your library and sent to your webhooks like real work.

The process, its assets and their webhook events carry testMode: true, so you can filter them out downstream. Test runs don't count toward usage, and each key can make 200 test starts an hour.

6. Upload local media and lip-sync it

For a local image, video, or audio file, create an upload ticket with POST /api/v1/assets/uploads, PUT the raw bytes to its uploadUrl using every returned header verbatim, then POST its completeUrl. The completed response contains the asset id.

After uploading the source video and matched audio, quote the lip-sync without spending credits:

curl -X POST https://yapper.so/api/v1/processes \
  -H "Authorization: Bearer $YAPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "video-lipsync",
    "model": "sync-lipsync-v3",
    "input": {
      "sourceVideoAssetId": "video_asset_id",
      "audioAssetId": "audio_asset_id"
    },
    "dryRun": true
  }'

The server uses the audio asset's measured duration for the exact quote. Send the same body without dryRun and with a stable Idempotency-Key to start it.

Model behavior differs:

  • max is train-once. Omit trainingId on the first Max request; that run trains from the source video before generating and therefore takes longer. Poll the process, save the returned trainingId, and reuse it for faster later Max requests against the same trained source.
  • lipdub-v2, pro, and sync-lipsync-v3 are single-shot models. They require no training and should not receive trainingId. For a lipdub-v2 source video longer than the safe 59-second cap, Yapper creates or reuses a cached variant containing its first 59 seconds.

7. Keep a character consistent with elements

An element is a named character, location or prop: an @ID that prompts tag, a main image, and other images. Elements belong to the whole workspace. Make one from image assets, naming any image you want to use on its own:

curl -X POST https://yapper.so/api/v1/elements \
  -H "Authorization: Bearer $YAPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mentionId": "hero",
    "category": "character",
    "imageAssetIds": ["front_asset_id", "coat_asset_id"],
    "imageNames": { "coat_asset_id": "coat-on" }
  }'

The @ID must be free in the workspace; a clash answers 409 with a free one to use. Search the library with GET /api/v1/elements?query=her (the start of an @ID, name or image name is enough).

Then pass elements in input.elements and tag each in the prompt the same way. @hero uses the element's main image; @hero:coat-on uses the image named coat-on:

curl -X POST https://yapper.so/api/v1/processes \
  -H "Authorization: Bearer $YAPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hero_walk_1" \
  -d '{
    "type": "image-generation",
    "model": "gpt-image-2",
    "input": {
      "prompt": "@hero:coat-on walks past @hero in the rain",
      "elements": ["@hero", "@hero:coat-on"]
    }
  }'

This works on any image model, and any video model that takes reference images. Each element counts as one reference image, and only its images and tag are sent: never its name or description. Every element response carries a webUrl that opens it in the web app, and GET /api/v1/links?view=elements links the whole element library.

On this page