API_DOC_FIREBASE.txt

Smile Changer API (with Firebase Authentication)

Base URL
- https://logicgoinfotechspaces-smile-changer.hf.space

Authentication
- Scheme: Bearer ID token (Firebase Authentication)
- Header: Authorization: Bearer <ID_TOKEN>
- How to obtain ID token:
  1) Sign-in REST (replace YOUR_WEB_API_KEY and credentials):
     curl -X POST "https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=YOUR_WEB_API_KEY" \
       -H "Content-Type: application/json" \
       -d '{"email":"you@example.com","password":"yourPassword","returnSecureToken":true}'
     Copy the value of "idToken" from the JSON response and use as the Bearer token.
  2) Or sign-in from your Firebase web/app and call currentUser.getIdToken().
- Notes: idToken expires in ~1 hour; sign in again to refresh. Service account JSON is configured in the server via FIREBASE_CREDENTIALS_JSON.

Health (public)
- GET /api/health
- Curl:
  curl https://logicgoinfotechspaces-smile-changer.hf.space/api/health
- Response: {"status":"ok"}

Auth check & user info
- GET /api/me
- Headers: Authorization: Bearer <ID_TOKEN>
- Curl:
  curl -H "Authorization: Bearer <ID_TOKEN>" \
    https://logicgoinfotechspaces-smile-changer.hf.space/api/me
- Response (example): {"mode":"firebase","uid":"...","claims":{"email":"..."}}

List supported attributes
- GET /api/attributes
- Headers: Authorization: Bearer <ID_TOKEN>
- Curl:
  curl -H "Authorization: Bearer <ID_TOKEN>" \
    https://logicgoinfotechspaces-smile-changer.hf.space/api/attributes
- Response example: {"Smile":{"internal":"fs_smiling","min":-10.0,"max":10.0}, ...}

Generic image edit
- POST /api/image-edit
- Headers: Authorization: Bearer <ID_TOKEN>
- Body (multipart/form-data):
  - file: (File) input image (jpg/png)
  - attribute: string (e.g., Smile, Age, Beard, Glasses, Makeup, Curly hair, Afro, Orange hair (text), Blonde hair (text))
  - strength: float (see ranges from /api/attributes)
  - align_face: boolean (true/false)
  - use_bg_mask: boolean (true/false)
  - custom_text_edit: string (optional, for text-based attributes)
- Curl (Windows path example):
  curl -X POST "https://logicgoinfotechspaces-smile-changer.hf.space/api/image-edit" \
    -H "Authorization: Bearer <ID_TOKEN>" \
    -F "file=@C:\\projects\\smile_api\\selfi_4.jpeg" \
    -F "attribute=Smile" \
    -F "strength=8" \
    -F "align_face=true" \
    -F "use_bg_mask=false" \
    --output result_smile.png

Attribute shortcut endpoints (same body as above, omit attribute field)
- POST /api/smile
- POST /api/age
- POST /api/beard
- POST /api/mustache-goatee
- POST /api/glasses
- POST /api/makeup
- POST /api/curly-hair
- POST /api/afro
- POST /api/orange-hair-text
- POST /api/blonde-hair-text
- Curl (Age example):
  curl -X POST "https://logicgoinfotechspaces-smile-changer.hf.space/api/age" \
    -H "Authorization: Bearer <ID_TOKEN>" \
    -F "file=@C:\\projects\\smile_api\\selfi_4.jpeg" \
    -F "strength=8" \
    --output result_age.png

HTTP status codes
- 200: Success (image or JSON returned)
- 400: Bad request (missing/invalid params)
- 401: Unauthorized (missing/invalid/expired ID token)
- 404: Not found (wrong endpoint)
- 415: Unsupported media type (file field missing or not an image)
- 500: Internal server error

Troubleshooting
- 401 Invalid token: get a fresh idToken (tokens expire ~1h) and ensure you send it in the Authorization header, not in the URL.
- API key invalid when signing in: ensure you use the Web API key from the same Firebase project as the created user.
- Large images: processing can take longer; keep connection open until response.

Security notes
- Never commit service account JSON to the repo. Provide credentials via Space secret FIREBASE_CREDENTIALS_JSON or a secure env var.
- Prefer HTTPS for all client requests.

Web API key (how to find)
- Firebase Console → Project settings (gear) → General
- If you don’t have a Web app, click “Add app” → Web (</>) and finish
- Copy Web API key from:
  - Project settings → General → Your project → Web API key, or
  - Project settings → General → Your apps → select Web app → SDK setup and configuration → apiKey

Authentication cURL quick reference
- Sign up a user (optional; returns idToken too):
  curl -X POST "https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=YOUR_WEB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"email":"you@example.com","password":"yourPassword","returnSecureToken":true}'

- Sign in (recommended; get idToken):
  curl -X POST "https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=YOUR_WEB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"email":"you@example.com","password":"yourPassword","returnSecureToken":true}'
  → Copy "idToken" and use:
  curl -H "Authorization: Bearer <ID_TOKEN>" https://logicgoinfotechspaces-smile-changer.hf.space/api/me

Windows PowerShell line breaks
- Use backticks (`) instead of backslashes for multiline commands, or paste as a single line.

CURL CHEAT-SHEET (Firebase + all endpoints)

1) Sign in (get idToken)
   Replace YOUR_WEB_API_KEY and credentials; copy the idToken from response.
   curl -X POST "https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=YOUR_WEB_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"email":"you@example.com","password":"yourPassword","returnSecureToken":true}'

2) Use YOUR_ID_TOKEN below; change file path as needed.

- Health (public)
  curl https://logicgoinfotechspaces-smile-changer.hf.space/api/health

- Me (auth check)
  curl -H "Authorization: Bearer YOUR_ID_TOKEN" \
    https://logicgoinfotechspaces-smile-changer.hf.space/api/me

- List attributes
  curl -H "Authorization: Bearer YOUR_ID_TOKEN" \
    https://logicgoinfotechspaces-smile-changer.hf.space/api/attributes

- Generic image edit
  curl -X POST "https://logicgoinfotechspaces-smile-changer.hf.space/api/image-edit" \
    -H "Authorization: Bearer YOUR_ID_TOKEN" \
    -F "file=@C:\\projects\\smile_api\\selfi_4.jpeg" \
    -F "attribute=Smile" \
    -F "strength=8" \
    -F "align_face=true" \
    -F "use_bg_mask=false" \
    --output result_generic.png

Shortcut endpoints (omit attribute field)

- Smile
  curl -X POST "https://logicgoinfotechspaces-smile-changer.hf.space/api/smile" \
    -H "Authorization: Bearer YOUR_ID_TOKEN" \
    -F "file=@C:\\projects\\smile_api\\selfi_4.jpeg" \
    -F "strength=8" \
    --output result_smile.png

- Age
  curl -X POST "https://logicgoinfotechspaces-smile-changer.hf.space/api/age" \
    -H "Authorization: Bearer YOUR_ID_TOKEN" \
    -F "file=@C:\\projects\\smile_api\\selfi_4.jpeg" \
    -F "strength=8" \
    --output result_age.png

- Beard (negative adds)
  curl -X POST "https://logicgoinfotechspaces-smile-changer.hf.space/api/beard" \
    -H "Authorization: Bearer YOUR_ID_TOKEN" \
    -F "file=@C:\\projects\\smile_api\\selfi_4.jpeg" \
    -F "strength=-15" \
    --output result_beard.png

- Mustache/Goatee (negative adds)
  curl -X POST "https://logicgoinfotechspaces-smile-changer.hf.space/api/mustache-goatee" \
    -H "Authorization: Bearer YOUR_ID_TOKEN" \
    -F "file=@C:\\projects\\smile_api\\selfi_4.jpeg" \
    -F "strength=-5" \
    --output result_goatee.png

- Glasses
  curl -X POST "https://logicgoinfotechspaces-smile-changer.hf.space/api/glasses" \
    -H "Authorization: Bearer YOUR_ID_TOKEN" \
    -F "file=@C:\\projects\\smile_api\\selfi_4.jpeg" \
    -F "strength=20" \
    --output result_glasses.png

- Makeup
  curl -X POST "https://logicgoinfotechspaces-smile-changer.hf.space/api/makeup" \
    -H "Authorization: Bearer YOUR_ID_TOKEN" \
    -F "file=@C:\\projects\\smile_api\\selfi_4.jpeg" \
    -F "strength=5" \
    --output result_makeup.png

- Curly hair
  curl -X POST "https://logicgoinfotechspaces-smile-changer.hf.space/api/curly-hair" \
    -H "Authorization: Bearer YOUR_ID_TOKEN" \
    -F "file=@C:\\projects\\smile_api\\selfi_4.jpeg" \
    -F "strength=0.10" \
    --output result_curly.png

- Afro
  curl -X POST "https://logicgoinfotechspaces-smile-changer.hf.space/api/afro" \
    -H "Authorization: Bearer YOUR_ID_TOKEN" \
    -F "file=@C:\\projects\\smile_api\\selfi_4.jpeg" \
    -F "strength=0.12" \
    --output result_afro.png

- Orange hair (text)
  curl -X POST "https://logicgoinfotechspaces-smile-changer.hf.space/api/orange-hair-text" \
    -H "Authorization: Bearer YOUR_ID_TOKEN" \
    -F "file=@C:\\projects\\smile_api\\selfi_4.jpeg" \
    -F "strength=0.18" \
    -F "custom_text_edit=styleclip_global_a face_a face with orange hair_0.18" \
    --output result_orange_hair.png

- Blonde hair (text)
  curl -X POST "https://logicgoinfotechspaces-smile-changer.hf.space/api/blonde-hair-text" \
    -H "Authorization: Bearer YOUR_ID_TOKEN" \
    -F "file=@C:\\projects\\smile_api\\selfi_4.jpeg" \
    -F "strength=0.18" \
    -F "custom_text_edit=styleclip_global_a face_a face with blonde hair_0.18" \
    --output result_blonde_hair.png