Make your first API request

This walkthrough uses AI Photo Face Swap to show the shared REST flow: authenticate, submit once, and query the returned task ID.

1. Prepare your account and inputs

Use an active subscription and an API key from the Developer Console. Make the key available to your local process as VIDMAGE_API_KEY. See API key setup for credential handling.

The request below uses the two public sample image URLs from the existing AI Photo Face Swap example. For your own inputs, use reachable URLs or complete a local file upload first. A submitted generation uses account credits.

Set VIDMAGE_IDEMPOTENCY_KEY to a fresh unique value for this logical generation request. Reuse that value if the same submission needs a transport retry. Use a new value for a different task. This request identifier is separate from your API credential.

2. Submit the sample request

curl --fail-with-body --silent --show-error \
  -X POST "https://vidmage.ai/api/v1/face-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",
    "referenceFaceImageUrl": "https://vidmage.ai/assets/images/samples/smiling-man-sweater.webp"
  }'

Check the HTTP response and success value. Save taskId before doing anything else. A successful submission means the task was accepted; it does not mean the output is ready.

3. Ask for that task, not a new one

Replace TASK_ID_FROM_SUBMIT with the value returned by the first request.

curl --fail-with-body --silent --show-error \
  -X POST "https://vidmage.ai/api/v1/face-swap/query" \
  -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-raw '{"taskId":"TASK_ID_FROM_SUBMIT"}'

Check the returned status. The published client examples recognize success, succeeded, and completed as completion values, and failed or error as failure values. For this capability, the output field is imageUrl. The task guide covers polling and response nesting.

Continue with your own request

Adjust the image inputs and face indices using the AI Photo Face Swap reference.
Use AI Video Face Swap for an existing video, or Seedance 2.5 for video generation.
If the submission response is lost or unclear, follow task recovery before submitting again.
For a non-success HTTP response, use errorType and recovery instructions rather than repeating the request unchanged.