Quick start
Submit a photo task, then poll it
- Verify the account email. New generation requests require a verified account.
- Create an API key. Use the key manager below and save the key when it is shown.
- Submit multipart media. Keep the returned
taskId. - Poll the same route. Stop at
COMPLETED,FAILED, orCANCELLED.
1. Create the task
curl --request POST 'https://deepswapai.com/api/ai-tasks' \
--header 'Authorization: Bearer $DEEPSWAPAI_API_KEY' \
--form '[email protected]' \
--form '[email protected]'Accepted response
{
"taskId": "b6de3ea5-52ef-41a5-8a4b-276cf548dd9c",
"status": "PENDING"
}2. Poll the task
curl --get 'https://deepswapai.com/api/ai-tasks' \
--header 'Authorization: Bearer $DEEPSWAPAI_API_KEY' \
--data-urlencode 'taskId=b6de3ea5-52ef-41a5-8a4b-276cf548dd9c'Current completion contract: polling is supported. Webhook callbacks and official language SDKs are not currently published.
API key manager
Create and revoke keys without leaving the reference
Key management uses your signed-in DeepSwapAI account session. A new secret is displayed once. Store it in a server-side secret manager; never place it in browser code, mobile binaries, public repositories, logs, or support messages.
Not connected.
Sign in to manage keysWorkflow matrix
Choose the endpoint that matches the output unit
| Workflow | POST and GET path | Credit unit | Primary limits |
|---|---|---|---|
| Photo | /api/ai-tasks | 2 per task | 30 MB per image |
| Batch photo | /api/ai-tasks/batch-face-swap | 2 per generated output | 20 images, 30 MB each, 200 MB total |
| Mapped group photo | /api/ai-tasks/multi-face-swap | 2 per replacement face | 10 faces, 30 MB each, 120 MB total |
| Video | /api/ai-tasks/video | 720p: 2/s; 1080p: 5/s | 300 seconds, 200 MB target |
| GIF / short clip | /api/ai-tasks/gif | 3/s, 10 minimum | 30 seconds, 100 MB target |
Photo
POST /api/ai-tasks
Send sourceImage as the identity reference and targetImage as the scene to preserve. Optional numeric fields are faceRestoreVisibility and restoreVisibility. JPEG/JPG, PNG, WebP, GIF, BMP, HEIC, and HEIF inputs are accepted after content validation; each file can be up to 30 MB.
Poll: GET /api/ai-tasks?taskId=...
Batch photo
POST /api/ai-tasks/batch-face-swap
Use mode=singleToMulti with exactly one repeated sourceImages field and one or more targetImages fields. Use mode=multiToSingle with one or more sourceImages fields and exactly one targetImages field.
The request can contain no more than 20 images, 30 MB each and 200 MB combined. Accepted formats are JPEG, PNG, WebP, AVIF, HEIC, and HEIF.
Poll: GET /api/ai-tasks/batch-face-swap?taskId=...
Mapped group photo
POST /api/ai-tasks/multi-face-swap
Send the group photo as sourceImage. Add replacement identities in contiguous fields from targetFace0 through targetFace9. Optional faceBox0 through faceBox9 values are JSON objects with x, y, width, and height.
Either map every replacement face or omit every face box. JPEG, PNG, and WebP are accepted, with a 30 MB per-file and 120 MB total limit.
Poll: GET /api/ai-tasks/multi-face-swap?taskId=...
Video
POST /api/ai-tasks/video
Send sourceImage, targetVideo, and optional quality set to 720p or 1080p. The default is 1080p. The reference image can be up to 30 MB; MP4, MOV, and WebM targets can be up to 200 MB and 300 seconds.
Measured duration is rounded up. 720p costs 2 credits per second with a 6-credit minimum. 1080p costs 5 credits per second with a 15-credit minimum.
Poll: GET /api/ai-tasks/video?taskId=...
GIF / short clip
POST /api/ai-tasks/gif
Send sourceImage and targetGif. The target can be GIF, MP4, or WebM, up to 100 MB and 30 seconds. The reference image can be up to 30 MB. Duration is rounded up and billed at 3 credits per second with a 10-credit minimum.
Poll: GET /api/ai-tasks/gif?taskId=...
Task lifecycle
Keep the taskId and stop at a terminal state
Use the same API key to poll a task. A taskId can only be read by its owning account. Poll at a measured interval rather than in a tight loop. The response includes the task type, current status, credit cost, timestamps, parameters, and a result object when available.
Errors and limits
Handle status codes before retrying
| Status | Meaning | Client action |
|---|---|---|
| 400 | Invalid field, media, mapping, size, duration, or taskId. | Correct the request; do not retry unchanged. |
| 401 | Missing or invalid Bearer API key. | Replace or recreate the key. |
| 402 | Insufficient account credits. | Add credits, then submit a new task. |
| 403 | Account email is not verified. | Complete email verification. |
| 404 | The taskId does not belong to this account. | Check the route, key, and taskId. |
| 429 | Key limit exceeded or another generation is active. | Honor Retry-After when supplied and use backoff. |
| 500 | The request could not be accepted or read. | Retry later with bounded exponential backoff. |
API-key limits can vary by environment or account. When the per-key limit is exhausted, the response supplies Retry-After, X-RateLimit-Limit, and X-RateLimit-Remaining. Separate account-level protection allows one active generation at a time.
Billing and delivered output
Credits settle with the task; trial image identity remains visible
Generation credits are reserved with the task and failed processing tasks are refunded automatically. Reward credits do not count as a paid purchase.
Until the account has a PAID or COMPLETED credit order, every delivered trial image export contains DeepSwapAI.com and the account's 100% complete email address. Every character is visible: the email is never masked, shortened, hashed, or omitted. A trial image cannot be delivered without that complete-email watermark.
After a completed one-time credit purchase, future image exports are watermark-free. Existing trial files do not change retroactively. This statement applies only to image exports and does not describe GIF or video watermark behavior. Review the complete export policy and current credit pricing.
API questions
Current integration boundaries
Does the API support webhooks?
No. Submit the task, retain its taskId, and poll GET on the same workflow endpoint until a terminal status.
Is there an official SDK?
No official language SDK is currently published. Use any server-side HTTP client that supports Bearer headers, multipart form data, and JSON.
How are requests billed?
Photo tasks cost 2 credits; batch and group-photo requests scale by output or selected face; video and GIF requests use the duration formulas above. Failed processing tasks are refunded.
Do trial images contain a watermark?
Yes. Before a paid order, delivered trial image exports contain DeepSwapAI.com and the account's complete unmasked email. Payment changes future image exports only; this rule does not describe GIF or video behavior.