Quickstart

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.

New keys start with all six permissions below selected. Use the Read and Write checkboxes to select the subset 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.

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/account/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"
    }
  }'

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.