PhotoFig API

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

Authorization: Bearer pf_live_...

Š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": 1200,
    "periodEndsAt": "2026-08-01T00:00:00Z"
  },
  "limits": {
    "maxFileSizeBytes": 25000000,
    "rateLimitPerHour": 500,
    "concurrentJobs": 5,
    "maxApiKeys": 3
  },
  "tools": ["mask", "ai-bg", "ai-shadows"]
}

Kiekvienam įrankiui galite pateikti įprastą prekės nuotrauką per „imageUrl“, „uploadSessionId“ arba multipart įkėlimą. Atskirai kviesti „mask“ reikia tik tada, kai norite gauti iškirptą produktą skaidriame fone.

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 "[email protected]" \
  -F "seed=128742"

Įkėlimo sesiją kurkite didesniam vietiniam failui arba kai tai pačiai nuotraukai norite pritaikyti kelis įrankius. Nuotraukos duomenys į saugyklą siunčiami tik kartą, o vėlesnėse redagavimo užklausose pakanka perduoti gautą „uploadSessionId“.

Rinkitės šį būdą didesniems failams arba kai tą pačią nuotrauką naudos keli įrankiai ar pakartotinės užklausos.

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

Nuotrauką pateikite per „imageUrl“, „uploadSessionId“ arba multipart lauką „image“. Atsakyme gausite užduoties ID, pagal kurį galėsite tikrinti būseną, atšaukti ar ištrinti užduotį ir susieti „webhook“ pranešimus.

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ė

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

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/{id} grąžina užduoties būseną JSON formatu. Kai apdorojimas bus baigtas, rezultatą atsisiųskite iš „resultUrl“. Periodiškai tikrinti būseną paprasčiausia, tačiau „webhook“ pranešimai tinkamesni, kai jūsų serveris apie rezultatą turi sužinoti automatiškai.

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

„Webhook“ pranešimais PhotoFig informuoja jūsų serverį apie užduoties būseną. Užregistruokite HTTPS adresą, ir PhotoFig išsiųs užklausą, kai API užduotis bus baigta, nepavyks arba bus atšaukta. Taip nereikės nuolat tikrinti GET /v1/jobs/{id}.

Palaikomi įvykiai: webhook.test,job.completed,job.failed, ir job.cancelled. Pranešime pateikiamas tas pats užduoties ID, kurį gavote kurdami redagavimą.

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

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

Baigtas API užduotis rasite per GET /v1/jobs ir GET /v1/jobs/{id}. Kai rezultatas paruoštas, būsenos atsakyme pateikiamos pasirašytos „resultUrl“ ir „thumbnailUrl“ nuorodos.

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.

Siųskite DELETE /v1/jobs/{id} užklausą, kai atsisiųsite rezultatus, kurių jau nebereikia. Jei įmanoma, taip bus atšauktos nebaigtos užduotys ir prieš automatinį išvalymą ištrintas užduoties įrašas bei su juo susiję API failai.