API PhotoFig

I percorsi API accettano chiavi API generate da Impostazioni. La chiave segreta completa viene visualizzata una sola volta al momento della creazione della chiave.

Authorization: Bearer pf_live_...

Utilizza questo percorso per eseguire un test di verifica delle credenziali e per controllare i limiti del piano, i crediti rimanenti e gli strumenti disponibili.

{
  "accountId": "uuid",
  "workspaceId": "uuid",
  "plan": "pro",
  "apiEnabled": true,
  "credits": {
    "remaining": 1200,
    "periodEndsAt": "2026-08-01T00:00:00Z"
  },
  "limits": {
    "maxFileSizeBytes": 25000000,
    "rateLimitPerHour": 500,
    "concurrentJobs": 5,
    "maxApiKeys": 3
  },
  "tools": ["mask", "ai-bg", "ai-shadows"]
}

Ogni strumento accetta una foto prodotto tramite imageUrl, uploadSessionId o invio multipart. Non è necessario chiamare prima lo strumento mask, a meno che non serva uno scontorno trasparente.

Questo è il metodo più semplice: invia una modifica con un `imageUrl` quando l’immagine di origine è già raggiungibile tramite URL, oppure invia un campo immagine multipart per una rapida richiesta di file locale. È l’opzione migliore quando devi eseguire un solo strumento su un unico input.

Scegli questa opzione quando hai una sola immagine, una sola modifica e non hai bisogno di riutilizzare la fonte caricata.

curl -X POST https://api.photofig.com/v1/tools/ai-shadows/edit \
  -H "Authorization: Bearer pf_live_..." \
  -F "[email protected]" \
  -F "seed=128742"

Crea una sessione di caricamento quando la fonte è un file locale di grandi dimensioni o quando desideri eseguire più di uno strumento sullo stesso input. I byte dell'immagine vengono inviati direttamente all'archivio una sola volta; le successive richieste di modifica inviano solo l'uploadSessionId restituito.

Scegli questa opzione quando le dimensioni del file da caricare sono importanti o quando la stessa immagine sorgente verrà utilizzata da più strumenti o per più tentativi.

UPLOAD_JSON=$(curl -s -X POST https://api.photofig.com/v1/uploads \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "image/jpeg",
    "filename": "product.jpg",
    "sizeBytes": 1842031
  }')

curl -X PUT "$(echo "$UPLOAD_JSON" | jq -r '.uploadUrl')" \
  -H "Content-Type: image/jpeg" \
  --data-binary @product.jpg

curl -X POST https://api.photofig.com/v1/tools/ai-shadows/edit \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d "{
    \"uploadSessionId\": \"$(echo "$UPLOAD_JSON" | jq -r '.uploadSessionId')\",
    \"parameters\": { \"seed\": 128742 }
  }"

Invia le modifiche utilizzando imageUrl, uploadSessionId o il campo multipart image. La risposta restituisce un ID del processo che puoi utilizzare per il polling, l'annullamento, l'eliminazione e la correlazione dei webhook.

Contesto dell'IA

L'endpoint di sfondo basato sull'IA funziona al meglio con un tema conciso della scena: un'ambientazione, una superficie, un'indicazione di illuminazione o un'atmosfera descritta in poche parole. Alcuni buoni esempi includono warm oak tabletop,minimal white studio, and soft morning kitchen light.

curl -X POST https://api.photofig.com/v1/tools/ai-bg/edit \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://cdn.example.com/product.png",
    "parameters": {
      "theme": "warm oak tabletop",
      "seed": 128742
    }
  }'

Product Shadow

curl -X POST https://api.photofig.com/v1/tools/ai-shadows/edit \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://cdn.example.com/product.png",
    "parameters": { "seed": 128742 }
  }'

Maschera

curl -X POST https://api.photofig.com/v1/tools/mask/edit \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://cdn.example.com/product.png",
    "parameters": { "mode": "standard" }
  }'

Elenca, verifica, annulla o elimina le attività API. Le attività API non compaiono nelle sezioni «Caricamenti» o «Progetti» dopo l’accesso; eliminandole vengono rimossi anche i relativi file.

GET /v1/jobs/{id} restituisce metadati di stato in formato JSON. Al termine dell'elaborazione, scarica l'immagine da resultUrl. Il polling è il metodo di integrazione più semplice; i webhook sono preferibili quando il tuo backend deve essere notificato automaticamente.

{
  "id": "api_edit_uuid",
  "tool": "ai-shadows",
  "status": "completed",
  "createdAt": "2026-07-15T10:15:00Z",
  "startedAt": "2026-07-15T10:15:04Z",
  "finishedAt": "2026-07-15T10:15:23Z",
  "statusUrl": "https://api.photofig.com/v1/jobs/api_edit_uuid",
  "resultUrl": "https://storage.example.com/signed-result-url",
  "thumbnailUrl": "https://storage.example.com/signed-thumbnail-url",
  "expiresAt": "2026-07-15T11:15:23Z",
  "error": null
}

I webhook sono callback inviati da PhotoFig al tuo server. Registra un URL HTTPS e PhotoFig invierà una richiesta quando un'operazione API viene completata, fallisce o viene annullata. Ciò consente al tuo backend di reagire immediatamente, invece di eseguire il polling di GET /v1/jobs/{id} fino a quando lo stato non cambia.

Gli eventi supportati sono webhook.test,job.completed,job.failed, e job.cancelled. I payload degli eventi utilizzano lo stesso ID attività restituito al momento della creazione della modifica.

{
  "event": "job.completed",
  "eventId": "uuid",
  "createdAt": "2026-07-15T10:15:23Z",
  "data": {
    "id": "api_edit_uuid",
    "tool": "ai-shadows",
    "status": "completed",
    "resultUrl": "https://storage.example.com/signed-result-url",
    "thumbnailUrl": "https://storage.example.com/signed-thumbnail-url"
  }
}

Le risposte di errore includono un codice stabile leggibile dal software e un messaggio per l’utente. Usa il codice per gestire i diversi casi nella logica del client.

{
  "code": "invalid_request",
  "message": "imageUrl or uploadSessionId is required"
}

Le attività API completate rimangono visibili tramite GET /v1/jobs e GET /v1/jobs/{id}. La risposta di stato contiene i link firmati resultUrl e thumbnailUrl quando i risultati sono disponibili.

I file delle attività API vengono archiviati separatamente dai caricamenti e dai progetti creati nell’editor. Non vengono visualizzati nella libreria dell'app.

I record delle attività API e i relativi file di input, risultato e anteprima vengono conservati per 1 ora dopo il completamento, l'errore o l'annullamento dell'attività. Il campo expiresAt indica l’ora prevista per la pulizia.

Utilizza DELETE /v1/jobs/{id} dopo aver scaricato i risultati che non ti servono più. Questo comando annulla l’attività non completata, ove possibile, ed elimina il relativo record e i file gestiti dall'API prima della pulizia automatica.