POST
/api/v1/face-swap-imagePhoto Swap
Swap a face on a photo.
Upload the base photo and the face to put on it. Same job flow as video, and usually much quicker.
- Returns a jobPoll it, or get a webhook
- Failed jobs are freeThe whole hold comes back
- Safe to retrySend an Idempotency-Key
curl -X POST https://api.kreatorsfactory.com/api/v1/face-swap-image \ -H "Authorization: Bearer $KREATORSFACTORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "image_key": "api/images/…/photo.png", "face_key": "api/images/…/face.jpg" }'
How it works
- 1Upload your filesPOST /uploads returns a file_key for each one.
- 2Start the jobYou get an id and a status_url straight away.
- 3Wait for itPoll status_url, or let your callback_url hear about it.
- 4Download the resultoutput_url is a signed link. Keep your own copy.
Request parameters
Send JSON with Content-Type: application/json. Job endpoints also accept an optional Idempotency-Key header. See Safe Retries.
| Field | Type | Required | Description |
|---|---|---|---|
image_key | string | Yes | file_key of the base image. |
face_key | string | Yes | file_key of the face to swap in. |
callback_url | string | No | We POST the result here when the job finishes, signed with your webhook secret. See Webhooks. |
Response
Response200
{ "id": "7f3c2a9e-5b1d-4c8e-9a0f-2d6b1e4c7a31", "status": "queued", "status_url": "/api/v1/jobs/7f3c2a9e-5b1d-4c8e-9a0f-2d6b1e4c7a31"}Every job endpoint answers with the same three fields. Poll status_url rather than building the path yourself; see Job Status for what it returns.
Errors
Every error arrives as {"error": {"code", "message"}}. Branch on code; the message may change. All errors.
| HTTP | Code | What it means |
|---|---|---|
| 401 | unauthorized | Missing, unknown or revoked key. |
| 402 | insufficient_balance | Your balance won't cover the estimated hold. Top up to continue. |
| 400 | invalid_input | A field failed validation, or a file_key doesn't start with api/. |
| 400 | capability_unavailable | This capability is switched off right now. |
| 429 | rate_limited | You're sending too fast. Back off and retry. |
| 429 | at_capacity | The platform is briefly full. Retry shortly. |
| 502 / 500 | internal_error | Failed on our side. Nothing is charged; retry, and tell us if it keeps happening. |
These arrive inside error on a job that finished as failed, not as an HTTP status. A failed job is refunded in full.
| Code on the job | What it means |
|---|---|
face_not_detected | No face was found in the input. |
unsupported_format | The file couldn't be decoded once work started. |
input_too_large | Over a size or duration limit found during processing. |
content_rejected | The input or the result failed a content check. |
processing_failed | The render didn't complete. |
The whole round trip
Upload, start the job, and poll until it’s done.
# 1 · Upload each input (repeat per file) and keep its file_keyKEY=$(curl -s https://api.kreatorsfactory.com/api/v1/uploads \ -H "Authorization: Bearer $KREATORSFACTORY_API_KEY" \ -F "file=@input.mp4" | jq -r .file_key) # 2 · Start the job, with your file_keys in place of the …JOB=$(curl -s -X POST https://api.kreatorsfactory.com/api/v1/face-swap-image \ -H "Authorization: Bearer $KREATORSFACTORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "image_key": "api/images/…/photo.png", "face_key": "api/images/…/face.jpg" }') # 3 · Poll status_url until status is succeeded or failedcurl -s "https://api.kreatorsfactory.com$(echo "$JOB" | jq -r .status_url)" \ -H "Authorization: Bearer $KREATORSFACTORY_API_KEY"