Face Swap with Model URLs (v2)

POST /api/images/swap/swap_urls_v2

This endpoint allows you to perform a face swap by uploading a selfie and specifying the target models using their URLs. The output is one or more swapped images.

Use this endpoint

Ideal when you already have URLs or cloud-hosted paths for your model images.

🔐 Authentication

This endpoint requires a valid Bearer Token in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

note

Make sure your token has permission to access face-swapping features. Contact support if unsure.

📥 Request

Content-Type: multipart/form-data

Field	Type	Description
face	file	The selfie image to use for the face swap.
model_ids	string	Comma-separated list of model IDs to use.
app	integer	Application ID associated with the request.

Example cURL

curl -X POST https://api.storyface.ai/api/images/swap_urls_v2 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "face=@/path/to/your/selfie.jpg" \
  -F "model_ids=1,2" \
  -F "app=123"

caution

The face field must contain a valid image file. Only JPEG and PNG are supported. Upload errors will result in a 400 Bad Request.

📤 Response

On success, the API returns a JSON object with a list of image URLs:

{
  "urls": [
    "https://cdn.storyface.ai/images/swap1.jpg",
    "https://cdn.storyface.ai/images/swap2.jpg"
  ]
}

⚠️ Error Responses

Status	Description	Example
400	Bad request	{ "field": "field error message" }
500	Internal server error	{ "general": "Internal server error" }

danger

Avoid sending large image files (>10MB). If file size exceeds limit, the request will be rejected with a 400 error.

---

🧪 Test this Endpoint

We are working on a built-in interactive tester component. Meanwhile, you can test the API using Postman or curl as shown above.

Coming Soon

This documentation will include an interface to try out this endpoint without external tools.