GIF Face Swap API documentation

Replace one tracked face in an animated GIF and return a real GIF. VidMage converts GIF to MP4, detects faces inside the task, measures duration server-side, and returns NEEDS_INPUT when selection is ambiguous.

Endpoints

Contract item	Value
Capability	`gif-face-swap`
Submit	`POST https://vidmage.ai/api/v1/gif-face-swap/submit`
Query	`POST https://vidmage.ai/api/v1/gif-face-swap/query`
Task identifier	`taskId`
Result field	`gifUrl`

Authenticate with Authorization: Bearer YOUR_API_KEY. Save the task identifier and query the same capability. Use a stable Idempotency-Key for submission retries.

Product guide: AI GIF Face Swap API for Animated Images

Parameters and input rules

Field	Type	Required	Default	Meaning and limits
`targetGifUrl`	`string`	Yes	Not specified	Animated-GIF fileUrl returned by upload_files.
`referenceFaceImageUrl`	`string`	Yes	Not specified	Publicly reachable URL of the photo containing the replacement face.
`targetFaceIndex`	`integer`	No	Not specified	Optional explicit tracked-face index. Omit to auto-select only one detected target face. Minimum: `0` Maximum: `99`
`referenceFaceIndex`	`integer`	No	Not specified	Optional explicit reference-face index. Omit to auto-select only one detected reference face. Minimum: `0` Maximum: `99`

Measured media limits

Input	Rule
`targetGifUrl`	The server measures this media for billing. Maximum 300 seconds. Do not send `gifDuration` in the submission body.

Example request

{
  "targetGifUrl": "https://upload.wikimedia.org/wikipedia/commons/2/2c/Rotating_earth_%28large%29.gif",
  "referenceFaceImageUrl": "https://vidmage.ai/assets/images/samples/smiling-man-sweater.webp"
}

# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries.
curl -X POST "https://vidmage.ai/api/v1/gif-face-swap/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"targetGifUrl":"https://upload.wikimedia.org/wikipedia/commons/2/2c/Rotating_earth_%28large%29.gif","referenceFaceImageUrl":"https://vidmage.ai/assets/images/samples/smiling-man-sweater.webp"}'
# -> { "success": true, "taskId": "...", "creditsRequired": ..., "creditsConsumed": 0, "usageDeferred": true }

Task results and recovery

URL of the completed animated GIF. Read gifUrl from the completed query response. Preserve taskId while the task is running.

curl -X POST "https://vidmage.ai/api/v1/gif-face-swap/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "gifUrl": "https://..." } }

Submission authorizes this task; provider work and billing can advance during queries. Initial creditsConsumed: 0 does not mean the task is free. A timeout is not a confirmed failure. Recover the existing task instead of resubmitting.

For face selection and error recovery, follow Task lifecycle. MCP uses the normalized taskId argument in get_task_result, including capabilities whose REST identifier is requestId.

Credits

Component / option	Rate	Minimum
GIF duration	1 credits / second	—

The example uses the duration shown above. The server measures uploaded media for billing; this duration is only supplied to the estimate.

Duration × rate is rounded up to whole credits; the applicable minimum charge is enforced.

Use the Playground or the MCP credit estimator for your exact inputs. Credits and billing.

Integration guides

Authentication · File uploads · Task lifecycle · Error recovery · MCP