Face Swap API Documentation

Authentication

All API requests require a Bearer token in the Authorization header. You can generate API keys from your Dashboard. Keep your keys secret and never expose them in client-side code.

1Authorization: Bearer prsp-your-api-key

Quick Start

Get started with a face swap in under a minute. Choose your preferred language below to see a complete working example.

1curl -X POST https://api.prospolabs.com/v1/swap/realistic \
2  -H "Authorization: Bearer prsp-your-api-key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "source_image": "base64_encoded_source...",
6    "target_image": "base64_encoded_target...",
7    "output_format": "jpeg",
8    "output_quality": 95
9  }'

Model Endpoints

1{
2  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3  "status": "completed",
4  "model": "realistic",
5  "result_url": "https://storage.example.com/results/a1b2c3d4.jpeg?token=...",
6  "inference_time": 2.05
7}

1{
2  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3  "status": "completed",
4  "model": "cartoon",
5  "result_url": "https://storage.example.com/results/a1b2c3d4.jpeg?token=...",
6  "inference_time": 2.05
7}

1{
2  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3  "status": "completed",
4  "model": "fast",
5  "result_url": "https://storage.example.com/results/a1b2c3d4.jpeg?token=...",
6  "inference_time": 2.05
7}

1{
2  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3  "status": "completed",
4  "model": "cartoon-lite",
5  "result_url": "https://storage.example.com/results/a1b2c3d4.jpeg?token=...",
6  "inference_time": 2.05
7}

Sync vs Async API

Use the standard endpoint for synchronous processing, or append /async to the path for asynchronous processing (e.g. /v1/swap/realistic/async).

1{
2  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3  "status": "completed",
4  "model": "realistic",
5  "result_url": "https://storage.example.com/results/a1b2c3d4.jpeg?token=...",
6  "inference_time": 2.05
7}

1{
2  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3  "status": "queued",
4  "model": "realistic",
5  "created_at": "2026-02-19T14:32:15.000Z",
6  "poll_url": "https://api.prospolabs.com/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
7}

1// GET /v1/jobs/{request_id}
2
3// When queued:
4{ "request_id": "a1b2c3d4-...", "status": "queued", "model": "realistic" }
5
6// When processing:
7{ "request_id": "a1b2c3d4-...", "status": "processing", "model": "realistic" }
8
9// When completed:
10{
11  "request_id": "a1b2c3d4-...",
12  "status": "completed",
13  "model": "realistic",
14  "result_url": "https://storage.example.com/results/a1b2c3d4.jpeg?token=...",
15  "inference_time": 2.05
16}
17
18// When failed:
19{
20  "request_id": "a1b2c3d4-...",
21  "status": "failed",
22  "model": "realistic"
23}

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your account. Configure a webhook URL in your dashboard or pass it per-request via the webhook_url field.

Event Types

Payload Format

1{
2  "event": "inference.completed",
3  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
4  "data": {
5    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
6    "model": "realistic",
7    "result_url": "https://storage.example.com/results/a1b2c3d4.jpeg?token=...",
8    "processing_time_ms": 2050
9  },
10  "timestamp": "2026-02-19T14:32:27.000Z"
11}

Verifying Webhook Signatures

Every webhook includes an X-Prospo-Signature header containing an HMAC-SHA256 signature. Verify it against your webhook secret to ensure the request is authentic.

1import crypto from 'crypto';
2
3function verifyWebhook(payload, signature, secret) {
4  const expected = crypto
5    .createHmac('sha256', secret)
6    .update(payload)
7    .digest('hex');
8  return crypto.timingSafeEqual(
9    Buffer.from(signature),
10    Buffer.from(expected)
11  );
12}
13
14// In your webhook handler:
15app.post('/api/webhook', (req, res) => {
16  const signature = req.headers['x-prospo-signature'];
17  const isValid = verifyWebhook(
18    JSON.stringify(req.body),
19    signature,
20    process.env.WEBHOOK_SECRET
21  );
22  if (!isValid) return res.status(401).send('Invalid signature');
23
24  const { event, data } = req.body;
25  if (event === 'inference.completed') {
26    console.log('Result ready:', data.result_url);
27  }
28  res.status(200).send('OK');
29});

Retry Policy

If your endpoint returns a non-2xx status code, we'll retry delivery with exponential backoff:

• 1First retry: 30 seconds after initial attempt
• 2Second retry: 2 minutes after first retry
• 3Third retry: 10 minutes after second retry
• 4Final retry: 1 hour after third retry
• 5After 4 failed attempts, the webhook is marked as failed

Rate Limits

The Prospolabs API is built for high-throughput workloads. Monitor your current usage via the response headers X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Error Handling

The API uses standard HTTP status codes to indicate the outcome of requests. All error responses include a JSON body with a machine-readable code and a human-readable message.

Error Response Example

1{
2  "detail": "Insufficient credits. Please top up your balance."
3}