PhotoFig API

API raktus galite sukurti skiltyje Nustatymai. Visas slaptasis raktas parodomas tik vieną kartą – iškart jį sukūrus.

Authorization: Bearer pf_live_...

API raktai veikia tik su šiame puslapyje aprašytais galiniais taškais; visi kiti PhotoFig maršrutai juos atmeta. Raktas veikia jį sukūrusio žmogaus vardu, toje darbo erdvėje, kurioje buvo sukurtas.

API prieiga įtraukta į Pro ir Studio planus. GET /v1/account rodo jūsų plano limitus, įskaitant valandinį užklausų limitą lauke limits.rateLimitPerHour.

Kiekviena autentifikuota užklausa, įskaitant užduoties būsenos tikrinimą, skaičiuojama į valandinį limitą. Atsakymuose yra X-RateLimit-Limit ir X-RateLimit-Remaining. Išnaudojus limitą, API atsako 429 rate_limit_exceeded su Retry-After antrašte.

mask naudoja fono pašalinimus, ai-bg ir ai-shadows po vieną DI kreditą, o resize nenaudoja nei vieno, nei kito. Kreditai nuskaičiuojami tik užbaigus užduotį.

Laukiančios ir vykdomos užduotys skaičiuojamos į jūsų plano vienu metu vykdomų užduočių limitą. Jį viršijus, nauji redagavimai gauna 429 too_many_jobs, kol ankstesnės užduotys baigsis.

POST /v1/uploads ir POST /v1/tools/{tool_id}/edit priima neprivalomą X-Idempotency-Key antraštę. Pakartojus užklausą su tuo pačiu raktu grąžinamas pirmasis atsakymas, o ne paleidžiama antra užduotis, todėl kiekvienai naujai užklausai naudokite naują raktą.

Šiuo maršrutu galite patikrinti API raktą ir sužinoti plano limitus, likusius kreditus bei prieinamus įrankius.

{
  "accountId": "uuid",
  "workspaceId": "uuid",
  "plan": "pro",
  "apiEnabled": true,
  "credits": {
    "remaining": 2000,
    "bonusRemaining": 0,
    "periodEndsAt": "2026-11-01T00:00:00Z"
  },
  "limits": {
    "maxFileSizeBytes": 10485760,
    "rateLimitPerHour": 60,
    "concurrentJobs": 3,
    "maxApiKeys": 1,
    "freeBgRemovals": 0,
    "bgRemovalsUsed": 0,
    "aiCredits": 2000
  },
  "tools": [
    "mask",
    "ai-bg",
    "ai-shadows",
    "resize"
  ]
}

Kiekvienas įrankis priima įprastą prekės nuotrauką per imageUrl, uploadSessionId arba multipart įkėlimą. mask iš anksto kviesti nereikia: ai-bg ir ai-shadows fono pašalinimą atlieka patys.

mask

Pašalina foną ir grąžina PNG failą su iškirptu produktu skaidriame fone. Naudokite, kai produktą norite komponuoti patys arba naudoti savo prekybos platformoje.

ai-shadows

Prideda tikrovišką produkto šešėlį ir grąžina vaizdą, paruoštą dėti ant švaraus fono. Geriausiai veikia, kai produktas aiškiai matomas ir jo neužgožia margas fonas.

ai-bg

Sukuria naują produkto foną pagal trumpą scenos aprašymą, pvz., šiltas ąžuolinis stalviršis arba minimalistinė balta studija. Pateikite prekės nuotrauką tiesiogiai; atskiro fono pašalinimo veiksmo atlikti nereikia.

resize

Pritaiko nuotrauką tiksliam drobės dydžiui ir išlaiko jos foną, kaip nuotraukų dydžio keitimas programėlėje. Pasirinkite talpinimą arba užpildymą, vietą ir tuščios erdvės užpildą. Nenaudoja DI kreditų.

Tai paprasčiausias būdas. Jei pradinė nuotrauka jau pasiekiama internete, pateikite „imageUrl“. Vietinį failą galite išsiųsti multipart lauke „image“. Šis būdas tinkamiausias, kai vienai nuotraukai norite pritaikyti vieną įrankį.

Rinkitės šį būdą vienai nuotraukai ir vienam redagavimui, kai pradinio failo vėliau naudoti nebereikės.

curl -X POST https://api.photofig.com/v1/tools/ai-shadows/edit \
  -H "Authorization: Bearer pf_live_..." \
  -F "image=@product.jpg" \
  -F "seed=128742"

Sukurkite įkėlimo seansą, kad nuotraukos duomenys keliautų tiesiai į saugyklą, tada paleiskite redagavimą su grąžintu uploadSessionId. Dydžio limitas toks pat kaip multipart užklausos, o kiekvienas seansas naudojamas vienam redagavimui.

Rinkitės šį būdą, kai jūsų klientas neturėtų siųsti nuotraukos per redagavimo užklausą, pavyzdžiui, naršyklė kelia tiesiai į saugyklą.

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 }
  }"

Siųskite redagavimus su imageUrl, uploadSessionId arba multipart lauku image. Atsakyme grąžinamas užduoties ID būsenai tikrinti, atšaukti, ištrinti ir „webhook“ įvykiams susieti. Parametrai, kurių įrankis nenaudoja, ignoruojami.

DI fonas

DI fono API metodas geriausiai veikia gavęs trumpą scenos aprašymą: keliais žodžiais nurodykite aplinką, paviršių, apšvietimą ar nuotaiką. Pavyzdžiui: šiltas ąžuolinis stalviršis,minimalistinė balta studija, and švelni ryto šviesa virtuvėje.

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 }
  }'

Kaukė

mask neturi parametrų ir grąžina PNG iškarpą su skaidrumu.

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"
  }'

Dydžio keitimas

width ir height nustato išvesties dydį pikseliais, nuo 100 iki 4096. mode gali būti fit (visa nuotrauka, numatytasis), fill (užpildo drobę ir apkerpa perteklių), width arba height. horizontal ir vertical nustato nuotraukos vietą, o background užpildo laisvą erdvę: transparent, #RRGGBB spalva arba gradiento objektas. Rezultatas yra PNG.

curl -X POST https://api.photofig.com/v1/tools/resize/edit \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://cdn.example.com/product.jpg",
    "parameters": {
      "width": 1000,
      "height": 1000,
      "mode": "fit",
      "background": "#ffffff"
    }
  }'

Peržiūrėkite, tikrinkite, atšaukite arba ištrinkite API užduotis. Jos nerodomos programos skiltyse „Įkėlimai“ ar „Dizainai“, tačiau ištrynus užduotį pašalinami ir jai priklausantys API failai.

GET /v1/jobs/{job_id} grąžina užduoties būseną. Kai ji užbaigta, atsisiųskite nuotrauką iš resultUrl iki expiresAt. Kiekvienas būsenos tikrinimas skaičiuojamas į valandinį limitą; pranešimams apie užbaigimą naudokite „webhook“.

{
  "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
}

Šablonas yra stilius, kurį taikote daugeliui nuotraukų: fono pašalinimas, išdėstymas, fonas ir šešėlis, paraštės ir eksporto dydžiai. Per API sukurti šablonai atsidaro ir redaguojami PhotoFig programėlėje, ir atvirkščiai. Sisteminiai šablonai paruošti naudoti ir tik skaitomi.

mask ir resize privalomi; kiti žingsniai neprivalomi ir vykdomi nustatyta tvarka. Nežinomi žingsniai ar laukai atmetami, o reikšmės turi būti redaktoriaus siūlomose ribose. OpenAPI schema aprašo kiekvieną lauką.

curl -X POST https://api.photofig.com/v1/templates \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cream catalog",
    "steps": {
      "mask": {},
      "reposition": { "horizontal": "center", "vertical": "center", "scale": 0.85 },
      "background": { "backgroundType": "solid", "color": "#f6f1ea" },
      "ai-shadows": { "opacity": 0.8 },
      "resize": { "mode": "fit", "targets": [{ "width": 2000, "height": 2000 }] }
    },
    "export": { "format": "jpg", "background": "#ffffff" }
  }'

creditsPerPhoto nurodo, kiek šablonas kainuoja už kiekvieną nuotrauką, pavyzdžiui, vienas DI kreditas už ai-shadows.

Rinkinys taiko vieną šabloną daugeliui nuotraukų. Sukurkite jį, pridėkite nuotraukas, tada apdorokite su šablonu. Nuotraukos išlaiko jūsų nurodytą poziciją.

Kiekviena nuotrauka keliama tiesiai į saugyklą: paprašykite įkėlimo, PUT užklausa nusiųskite baitus į uploadUrl, tada jį užbaikite.

BATCH_ID=$(curl -s -X POST https://api.photofig.com/v1/batches \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring arrivals" }' | jq -r '.id')

# For each photo: ask for an upload, PUT the bytes, complete it.
UPLOAD=$(curl -s -X POST "https://api.photofig.com/v1/batches/$BATCH_ID/uploads" \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "filename": "boots.jpg", "contentType": "image/jpeg", "sizeBytes": 1842031, "position": 0 }')
curl -X PUT "$(echo "$UPLOAD" | jq -r '.uploadUrl')" \
  -H "Content-Type: image/jpeg" --data-binary @boots.jpg
curl -X POST "https://api.photofig.com/v1/batches/$BATCH_ID/uploads/$(echo "$UPLOAD" | jq -r '.uploadId')/complete" \
  -H "Authorization: Bearer pf_live_..."

curl -X POST "https://api.photofig.com/v1/batches/$BATCH_ID/process" \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "templateId": "TEMPLATE_ID" }'

Sužinokite, kada rinkinys baigtas

Užuot tikrinę, vieną kartą užregistruokite webhook įvykiui batch.completed. PhotoFig jį iškviečia, kai baigiamas kiekvienas rinkinys, ir nurodo rinkinio ID bei kiek nuotraukų pavyko ar nepavyko.

curl -X POST https://api.photofig.com/v1/webhooks \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/photofig/webhooks",
    "events": ["batch.completed"]
  }'

{
  "event": "batch.completed",
  "eventId": "uuid",
  "createdAt": "2026-10-06T12:00:00Z",
  "data": {
    "batchId": "uuid",
    "status": "completed",
    "totalItems": 12,
    "completedItems": 12,
    "failedItems": 0
  }
}

Kai gaunate batch.completed, perskaitykite rinkinį. Kiekviena baigta nuotrauka turi peržiūros nuorodą iki 1024 pikselių. Fono pašalinimai ir DI kreditai skaičiuojami kaip programėlėje.

{
  "id": "uuid",
  "name": "Spring arrivals",
  "status": "completed",
  "templateName": "Cream catalog",
  "totalItems": 2,
  "completedItems": 2,
  "failedItems": 0,
  "resultsAvailableUntil": "2026-10-20T12:00:00Z",
  "items": [
    {
      "id": "uuid",
      "position": 0,
      "filename": "boots.jpg",
      "status": "completed",
      "width": 3024,
      "height": 4032,
      "preview": {
        "url": "https://...",
        "width": 1024,
        "height": 1024
      }
    }
  ]
}

Rezultatų atsisiuntimas

Atsisiųskite kiekvieną pilno dydžio rezultatą šablono eksporto formatu arba visą rinkinį ZIP archyvu. Kiekvienas rezultatas vieną kartą skaičiuojamas kaip eksportas, kaip ir programėlėje; pakartotinai atsisiųsti nemokama.

Rezultatų bendrinimas

Bendrinimo nuoroda yra viešas puslapis su peržiūromis prieš ir po bei ZIP atsisiuntimu, be prisijungimo. Rinkinys turi vieną nuorodą: paprašius dar kartą grąžinama ta pati, o atšaukus ji iškart nebeveikia. Atsisiuntimai iš puslapio skaičiuojami kaip jūsų eksportai, o puslapis veikia iki availableUntil. Bendrinimui reikia mokamo plano.

curl -X POST "https://api.photofig.com/v1/batches/$BATCH_ID/share" \
  -H "Authorization: Bearer pf_live_..."

{
  "url": "https://photofig.com/share/TOKEN",
  "availableUntil": "2026-10-20T12:00:00Z",
  "createdAt": "2026-10-06T12:05:00Z",
  "downloadCount": 0
}

Webhook leidžia PhotoFig pranešti jūsų serveriui, kai API užduotis baigiasi, nepavyksta ar atšaukiama, ir kai rinkinys baigtas, todėl jūsų sistemai nereikia nuolat tikrinti. Užregistruokite HTTPS URL viešame serveryje. Galinis taškas gauna įvykius apie užduotis ir rinkinius, sukurtus jo savininko API raktais.

Palaikomi įvykiai: webhook.test,job.completed,job.failed,job.cancelled, ir batch.completed. Užduočių įvykiai naudoja užduoties ID, grąžintą sukuriant redagavimą; batch.completed perduoda rinkinio ID.

{
  "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",
    "expiresAt": "2026-07-15T11:15:23Z"
  }
}

Patikrinkite kiekvieną pristatymą

Kiekvienoje užklausoje yra PhotoFig-Webhook-Timestamp ir PhotoFig-Webhook-Signature. Su galinio taško slaptu raktu apskaičiuokite laiko žymos, taško ir neapdoroto užklausos turinio HMAC-SHA256 ir palyginkite jį su reikšme po v1=. Atmeskite senesnes nei kelių minučių laiko žymas. Slaptas raktas parodomas tik sukuriant galinį tašką.

import crypto from 'node:crypto';

// rawBody is the request body exactly as received, before JSON parsing.
export function verifyPhotoFigWebhook(headers, rawBody, secret) {
  const timestamp = headers['photofig-webhook-timestamp'];
  const signature = headers['photofig-webhook-signature'] ?? '';
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = 'v1=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  return signature.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Atsakykite bet kuriuo 2xx būsenos kodu per 10 sekundžių. Kiti atsakymai kartojami po 1 minutės, 5 minučių, 30 minučių, 2 valandų ir 12 valandų. PhotoFig-Webhook-Id nesikeičia tarp bandymų, todėl naudokite jį pasikartojimams praleisti. Atsisiuntimo nuorodos turinyje pasirašomos kiekvienam bandymui ir nustoja veikti, kai rezultato galiojimas baigiasi.

Klaidos atsakyme pateikiamas nekintantis programinis kodas ir žmogui suprantamas pranešimas. Programos logikoje sprendimus priimkite pagal kodą.

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

Dažni kodai

invalid_request

Trūksta parametro arba jis netinkamas; pranešime nurodoma kuris.

api_key_not_allowed

API raktas panaudotas maršrute už viešosios API ribų.

api_access_disabled

Darbo erdvės planas neapima API prieigos.

insufficient_funds

Šiam įrankiui neliko DI kreditų ar fono pašalinimų.

rate_limit_exceeded

Valandinis užklausų limitas išnaudotas; palaukite Retry-After.

too_many_jobs

Per daug užduočių laukia ar vykdoma; bandykite dar kartą, kai ankstesnės baigsis.

tool_unavailable

Įrankio apdorojimo serveriai trumpam nepasiekiami; netrukus bandykite dar kartą.

webhook_limit_reached

Rakto savininkas pasiekė „webhook“ galinių taškų limitą šioje darbo erdvėje.

Užbaigtos API užduotys lieka matomos per GET /v1/jobs ir GET /v1/jobs/{job_id}. Būsenos atsakyme yra pasirašytos resultUrl ir thumbnailUrl nuorodos, kol rezultatai pasiekiami.

API failai saugomi atskirai nuo programoje įkeltų nuotraukų ir dizainų, todėl bibliotekoje jų nematysite.

API užduočių įrašai ir joms priklausantys įvesties, rezultatų bei miniatiūrų failai saugomi 1 valandą po to, kai užduotis baigta, nepavyko arba buvo atšaukta. Lauke „expiresAt“ nurodytas numatytas užbaigtų užduočių išvalymo laikas.

Atsisiuntę nebereikalingus rezultatus, naudokite DELETE /v1/jobs/{job_id}. Taip, jei įmanoma, atšaukiamas nebaigtas darbas ir ištrinamas užduoties įrašas bei API failai dar prieš automatinį išvalymą.