Beta — the platform and this API are in beta. The rules on this page are binding; we may add features and tighten validation without notice.

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; another format 415 unsupported_media_type; a larger one 413 payload_too_large.

Limits

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 — retry.

When photos lock

Once her listing is live, photos can no longer change: upload, change and delete answer 409 photos_locked. Ask us if a photo must go.

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