Playground
Head Swap
Replace heads in photos for a seamless edit.
POST /api/v1/head-swap/submit → /queryAPI access is available to subscribers only. Your subscription credits are shared across the website and the API.
View plansParameter
4 parametersRequired request parameter. Follow the type and accepted values shown in this table.
minItems 1maxItems 4
Optional request parameter. Follow the type, default, and accepted values shown in this table.(Optional)
Optional request parameter. Follow the type, default, and accepted values shown in this table.(Optional)
Default: 1:1
Request code
#!/usr/bin/env bash
set -euo pipefail
# Set this once per intended task; preserve it and the body for transport retries.
: "${VIDMAGE_IDEMPOTENCY_KEY:?Set a unique key for this task}"
SUBMIT_RESPONSE="$(curl --fail-with-body --silent --show-error -X POST "https://vidmage.ai/api/v1/head-swap/submit" \
-H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
-H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
-H "Content-Type: application/json" \
--data-raw '{
"targetImageUrl": "https://vidmage.ai/assets/images/samples/blue-eyed-woman-sunlight.webp",
"referenceImageUrls": [
"https://vidmage.ai/assets/images/samples/smiling-man-sweater.webp"
],
"aspectRatio": "1:1"
}')"
TASK_ID="$(printf '%s' "$SUBMIT_RESPONSE" | jq -er '.["taskId"]')"
while true; do
QUERY_RESPONSE="$(curl --fail-with-body --silent --show-error -X POST "https://vidmage.ai/api/v1/head-swap/query" \
-H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
-H "Content-Type: application/json" \
--data-raw "{\"taskId\":\"${TASK_ID}\"}")"
STATUS="$(printf '%s' "$QUERY_RESPONSE" | jq -r '(.status // .data.status // "") | ascii_downcase')"
case "$STATUS" in
success|succeeded|completed)
RESULT="$(printf '%s' "$QUERY_RESPONSE" | jq -r '(.result // .["imageUrl"] // .data["imageUrl"] // empty)')"
if [ -z "$RESULT" ]; then
printf '%s' "Result missing; preserve task $TASK_ID and query the same task again. Do not resubmit." >&2
exit 2
fi
printf '%s\n' "$RESULT"
break
;;
needs_input)
printf '%s' "Face selection required; preserve task $TASK_ID" >&2
exit 2
;;
failed|error)
printf '%s' "$QUERY_RESPONSE" | jq -r '(.message // .error // .data.error // "Task failed")' >&2
exit 1
;;
esac
sleep 5
done

