# Photos

A lead needs **three photos** before review (`photos_missing` in `next_actions.blockers`). Upload them with the API or in the portal; both end up in the same place.

## Upload

`POST /v1/leads/{id}/photos` with `multipart/form-data` (scope `photos:write`):

| Part | Required | Value |
|---|---|---|
| `file` | yes | JPEG, PNG or WebP; at most **40 MB** and 50 megapixels; exactly one file |
| `kind` | no | `portrait` (default), `body`, `content_sample`, `non_nude`, `lingerie` or `professional` |
| `is_primary` | no | `true` makes it her primary photo; her first photo always is |

```bash
curl -X POST https://api.creator-guard.com/v1/leads/lead_hz5ikyc3pnhkrhlb6p7elkx2qy/photos \
  -H "Authorization: Bearer $CG_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@portrait.jpg" \
  -F "kind=portrait"
```

```js
// Node.js 20+: fetch, FormData and Blob are built in.
import { readFile } from 'node:fs/promises';

const form = new FormData();
form.append('file', new Blob([await readFile('portrait.jpg')], { type: 'image/jpeg' }), 'portrait.jpg');
form.append('kind', 'portrait');
const res = await fetch('https://api.creator-guard.com/v1/leads/lead_hz5ikyc3pnhkrhlb6p7elkx2qy/photos', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CG_API_KEY}`, 'Idempotency-Key': crypto.randomUUID() },
  body: form, // fetch sets the multipart Content-Type with its boundary
});
```

```python
import os, uuid, requests

with open("portrait.jpg", "rb") as f:
    res = requests.post(
        "https://api.creator-guard.com/v1/leads/lead_hz5ikyc3pnhkrhlb6p7elkx2qy/photos",
        headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
        files={"file": ("portrait.jpg", f, "image/jpeg")},
        data={"kind": "portrait"},
        timeout=60,
    )
```

The answer (`201`) is the photo: `id`, `lead`, `kind`, `is_primary`, `consent_status`, a signed `url` (valid one hour, until `url_expires_at`), `created_at` and `version`. A replay of the same `Idempotency-Key` answers the same photo with `url` and `url_expires_at` as `null` — list the photos for a fresh URL.

## What we do with every file

Before anything is stored we read the format from the bytes, decode the image, **bake in its orientation**, scale it to at most 3000 px on the long edge and re-encode it **without any metadata** — no EXIF, no GPS position, no XMP, no IPTC. A second check rejects the result if any metadata block survived. Neither your original bytes nor the file name are stored. A file we cannot decode answers [`422 image_unreadable`](https://docs.creator-guard.com/errors/#image_unreadable); another format [`415 unsupported_media_type`](https://docs.creator-guard.com/errors/#unsupported_media_type); a larger one [`413 payload_too_large`](https://docs.creator-guard.com/errors/#payload_too_large).

## Limits

- At most **20 photos per lead** ([`409 limit_reached`](https://docs.creator-guard.com/errors/#limit_reached)).
- Uploads (photos and logos together) count **60 per minute and 3,000 per day per account**, on top of the [request limits](https://docs.creator-guard.com/rate-limits/) and halved in [test mode](https://docs.creator-guard.com/test-mode/); over it: [`429 rate_limited`](https://docs.creator-guard.com/errors/#rate_limited).

## List, change, delete

- `GET /v1/leads/{id}/photos` — primary first, then oldest first, all on one page; each `url` works for one hour, so read the list again rather than storing URLs.
- `PATCH /v1/leads/{id}/photos/{photo}` — `{"kind": "professional"}` or `{"is_primary": true}` (the previous primary photo stops being primary). Accepts `If-Match`.
- `DELETE /v1/leads/{id}/photos/{photo}` — removes the file, then the photo, and answers `204` without a body. If it was her primary photo, the oldest remaining one becomes primary. If the file cannot be removed, nothing changes and you get [`502 upstream_failed`](https://docs.creator-guard.com/errors/#upstream_failed) — retry.

## When photos lock

Once her listing is **live**, photos can no longer change: upload, change and delete answer [`409 photos_locked`](https://docs.creator-guard.com/errors/#photos_locked). Ask us if a photo must go.

## Consent

`consent_status` follows her consent: `pending` until she grants it, `granted` afterwards, `revoked` if she withdraws it.
