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.
| Permission | Access |
|---|---|
processes:read | List 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:write | Start media generations and speech generation, or request generation quotes. Edit session workspaces and canvases, and run canvas cards. |
assets:read | List and fetch workspace assets. |
assets:write | Import media from URLs and upload local media. |
models:read | Read available models and schemas, voices, skills, and the authenticated workspace context. |
usage:read | Read workspace credit balance, usage, spend breakdowns, the credit log, storage, and the member list (names and emails). |
sharing:write | Manage project access and send invitations. Owner and admin keys can list, resend, and revoke pending invitations. |
billing:read | List Stripe invoices and receipts for the workspace. Requires an owner or admin API key. |
limits:write | Set 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/invoicesfor invoice status, amounts, and PDF links, andGET /api/v1/billing/receiptsfor successful Stripe charges with receipt links. Amounts use the currency's minor unit. Pass the returnednextCursorto fetch the next page, including when a page has no visible entries. - Use
GET /api/v1/members/invitesto find the pending invitation'semailandinviteRef. Pass both in the body ofPOST /api/v1/members/invites/resendorPOST /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-limitwith{"creditLimit": 5000, "creditLimitPeriod": "monthly"}. Use"lifetime"for a lifetime cap ornullas 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:
maxis train-once. OmittrainingIdon the first Max request; that run trains from the source video before generating and therefore takes longer. Poll the process, save the returnedtrainingId, and reuse it for faster later Max requests against the same trained source.lipdub-v2,pro, andsync-lipsync-v3are single-shot models. They require no training and should not receivetrainingId. For alipdub-v2source 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.