Agent instructions for safe API use

# AIFaceSwap API Face Swap Skill

Use this skill when the user asks you to create an AI face swap with AIFaceSwap.

## Inputs to collect from the user

Ask for these if missing:

- `source_url`: a public HTTPS image URL containing the face to swap in.
- `target_url`: a public HTTPS image or GIF URL to transform.
- Optional `target_face_index`: integer face index when the target contains multiple faces.
- Optional `enable_face_enhancer`: boolean; use only if the user asks for face enhancement.
- Optional `webhook_url`: public HTTPS callback URL for completion events.
- Optional `metadata`: small object to echo back on the swap for the user's own tracking.

Never ask the user to paste their API key into a public chat. Use the server-side secret `AIFACESWAP_API_KEY` from your runtime environment.

## API base URL

`https://aifacesswap.com/api/v1`

## Authentication

Send every request with:

`Authorization: Bearer $AIFACESWAP_API_KEY`

The key must stay server-side. Never expose it in browser code, mobile apps, logs, or generated user-visible messages.

## Step 1 — Optional identity check

Use `GET /api/v1/me` to verify the key and inspect available credits:

```bash
curl -sS "https://aifacesswap.com/api/v1/me" \
  -H "Authorization: Bearer $AIFACESWAP_API_KEY"
```

## Step 2 — Create the swap

Make a JSON request. Always include an `Idempotency-Key` for safe retries.

```bash
curl -sS -X POST "https://aifacesswap.com/api/v1/swaps" \
  -H "Authorization: Bearer $AIFACESWAP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: face-swap-$(date +%s)-$(openssl rand -hex 4)" \
  -d @- <<'JSON'
{
  "type": "image",
  "source_url": "https://example.com/source-face.jpg",
  "target_url": "https://example.com/target-image.jpg"
}
JSON
```

For GIF targets, set `type` to `gif` and use a public HTTPS GIF URL as `target_url`. The v1 API accepts URL-based `image` and `gif` swaps only; do not send multipart uploads, base64 payloads, video swaps, or multi-face image swaps.

## Step 3 — Read the task id

A successful create response returns a `PublicSwap` object:

```json
{
  "id": "task_id_here",
  "type": "image",
  "status": "queued",
  "credit_cost": 0,
  "progress": 0,
  "created_at": "2026-01-01T00:00:00.000Z",
  "result_url": null,
  "error": null,
  "metadata": null,
  "webhook_url": null
}
```

Save `id` as `taskId`.

## Step 4 — Poll status

Poll `GET /api/v1/swaps/{taskId}` until `status` is one of `done`, `failed`, or `canceled`:

```bash
curl -sS "https://aifacesswap.com/api/v1/swaps/$TASK_ID" \
  -H "Authorization: Bearer $AIFACESWAP_API_KEY"
```

Recommended polling: every 5 seconds for up to 2 minutes for image swaps. GIFs can take longer. If the task is still running after your polling budget, return the `taskId` and tell the user to check again later.

You can also create with `POST /api/v1/swaps?wait=true` to let the create request long-poll until a terminal state or the server poll budget expires.

## Step 5 — Return the result

- If `status = done`, return `result_url` to the user.
- If `status = failed`, explain the `error` field and suggest using clearer face images.
- If `status = canceled`, tell the user the task was canceled.
- If the task is still running, return the current status and `taskId`.

## Optional — List previous swaps

Use `GET /api/v1/swaps?limit=25` to list swaps created by this API key. Lists are scoped per key; two keys on the same account do not see each other's swaps.

## Optional — Cancel a swap

Use `DELETE /api/v1/swaps/{taskId}` only when the user asks to cancel. Cancel works for queued or preparing tasks; processing or completed tasks are returned unchanged.

## Webhooks

If `webhook_url` is supplied on create, AIFaceSwap sends a JSON webhook when the task reaches a terminal state. Verify the `x-aifaceswap-signature` header:

`x-aifaceswap-signature: t=<unix-seconds>,v1=<hex-sha256-hmac>`

The signed input is exactly `${timestamp}.${rawBody}`. Verify against the raw request body bytes, not re-serialized JSON. In v1, the API key is also the webhook signing secret.

## Error handling

Common API errors:

- `400 validation_error`: malformed JSON, missing URL, unsupported `type`, non-HTTPS URL, or invalid parameter.
- `400 source_unreachable`: the media URL cannot be fetched or resolves to a private/non-public address.
- `401 unauthorized`: missing or malformed Authorization header.
- `401 invalid_api_key`: invalid or revoked API key.
- `402 insufficient_credits`: the account does not have enough credits.
- `413 payload_too_large`: fetched media exceeds the size limit.
- `415 unsupported_media_type`: request is not JSON or fetched media type is unsupported.
- `422 nsfw_content_detected`: input content was blocked by the content safety scan.
- `429 rate_limited`: wait and retry with backoff.
- `429 rate_limited_concurrent`: too many in-flight swaps for this key; wait for existing swaps to finish.
- `503 api_temporarily_disabled`: API disabled or input scan still pending; retry if a `Retry-After` header is present.

## Safety and privacy rules

- Only use public HTTPS image/GIF URLs supplied by the user or by your own trusted storage.
- Do not attempt to fetch localhost, private IPs, intranet URLs, or cloud metadata URLs.
- Do not log the API key.
- Do not store user image URLs longer than necessary for the task.
- Do not promise completion time; tell users image swaps usually finish faster than GIF swaps.

## Idempotency rule

Always send an `Idempotency-Key` for create requests. Reusing the same key for the same create retry should return the same task instead of creating duplicate work or duplicate charges.