Face Swap with URL Models and Uploaded Face

POST /api/images/swap_file_urls

This endpoint enables the swapping of faces between a model array hosted at public URLs and an image uploaded from the client device. The processed images are stored in Google Cloud Storage and returned as an array of URLs.

Use this endpoint

Recommended when your model images are hosted online and the client uploads the face image directly.

This method improves performance by avoiding repeated uploads of the same model images, which is especially useful for mobile devices with limited bandwidth.

🔐 Authentication

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

Authorization: Bearer YOUR_API_TOKEN

📥 Request

Content-Type: multipart/form-data

Field	Type	Description
face	file	The selfie image containing the face to be swapped.
models	string	A JSON array or comma-separated list of model URLs.
watermark	integer	Optional watermark ID to apply on the output images.
app	integer	The application ID initiating the request.

Example cURL

curl -X POST https://api.storyface.ai/api/images/swap_file_urls \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "face=@/path/to/your/selfie.jpg" \
  -F "models=https://example.com/model1.jpg,https://example.com/model2.jpg" \
  -F "watermark=1" \
  -F "app=123"

caution

Ensure the models field contains valid public URLs accessible by our servers. Invalid or private URLs will lead to request failure.

📤 Response

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

⚠️ Error Responses

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

danger

All uploaded files must be under 10MB. Larger files will be rejected with a 400 error.

---

🧪 Test this Endpoint

We're building an embedded tester to allow real-time testing.

Coming Soon

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