PhotoFig-API

API-Routen akzeptieren API-Schlüssel aus den Einstellungen. Der vollständige geheime Schlüssel wird nur einmal bei der Erstellung angezeigt.

Authorization: Bearer pf_live_...

Mit dieser Route können Sie Ihre Zugangsdaten prüfen und Planlimits, verbleibende KI-Credits sowie verfügbare Tools abrufen.

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

Jedes Tool akzeptiert ein normales Produktbild über imageUrl, uploadSessionId oder einen Multipart-Upload. Sie müssen mask nicht zuerst aufrufen, es sei denn, Sie benötigen ausdrücklich einen transparenten Ausschnitt.

Dies ist der einfachste Weg: Senden Sie eine Bearbeitung mit imageUrl, wenn das Quellbild bereits über eine URL erreichbar ist, oder übertragen Sie eine lokale Datei als Multipart-Feld image. Diese Variante eignet sich, wenn Sie genau ein Tool auf ein Bild anwenden möchten.

Wählen Sie diese Option, wenn Sie ein Bild haben, es nur einmal bearbeiten müssen und die hochgeladene Quelle nicht wiederverwendet werden muss.

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

Erstellen Sie eine Upload-Sitzung, wenn die Quelle eine größere lokale Datei ist oder wenn Sie mehrere Tools auf dasselbe Bild anwenden möchten. Die Bilddaten werden einmal direkt in den Speicher übertragen; spätere Bearbeitungsanfragen senden nur die zurückgegebene uploadSessionId.

Wählen Sie diese Option für größere Dateien oder wenn dasselbe Quellbild für mehrere Tools oder Wiederholungsversuche verwendet wird.

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

Senden Sie Bearbeitungen mit imageUrl, uploadSessionId oder dem Multipart-Feld image. Die Antwort enthält eine Job-ID zum Abfragen, Abbrechen, Löschen und Zuordnen von Webhook-Ereignissen.

KI-Hintergrund

Der Endpunkt für KI-Hintergründe funktioniert am besten mit einem prägnanten Szenenthema: einer Umgebung, Oberfläche, Lichtstimmung oder Atmosphäre in wenigen Worten. Gute Beispiele sind: 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 }
  }'

Hintergrundentfernung

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

API-Jobs auflisten, abfragen, abbrechen oder löschen. API-Jobs werden nicht unter den Uploads oder Designs in der App angezeigt. Beim Löschen werden jedoch alle zugehörigen API-Dateien entfernt.

GET /v1/jobs/{id} gibt JSON-Statusmetadaten zurück. Wenn die Verarbeitung abgeschlossen ist, laden Sie das Bild von resultUrl herunter. Polling ist der einfachste Integrationspfad; Webhooks sind besser, wenn Ihr Backend automatisch benachrichtigt werden soll.

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

Webhooks benachrichtigen Ihren Server über Änderungen. Registrieren Sie eine HTTPS-URL, und PhotoFig sendet eine Anfrage, sobald ein API-Job abgeschlossen wurde, fehlgeschlagen ist oder abgebrochen wurde. So kann Ihr Backend sofort reagieren, statt GET /v1/jobs/{id} wiederholt abzufragen.

Unterstützte Ereignisse sind webhook.test,job.completed,job.failed, und job.cancelled. Die Ereignisdaten enthalten dieselbe Job-ID, die beim Erstellen der Bearbeitung zurückgegeben wurde.

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

Fehlerantworten enthalten einen stabilen maschinenlesbaren Code und eine verständliche Meldung. Verwenden Sie den Code für Verzweigungen in Ihrer Client-Logik.

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

Abgeschlossene API-Jobs bleiben über GET /v1/jobs und GET /v1/jobs/{id} sichtbar. Sobald Ergebnisse verfügbar sind, enthält die Statusantwort signierte resultUrl- und thumbnailUrl-Links.

API-Dateien werden getrennt von interaktiven Uploads und Designs gespeichert. Sie werden nicht in der App-Bibliothek angezeigt.

API-Jobdaten sowie zugehörige Eingabe-, Ergebnis- und Vorschaudateien werden nach Abschluss, Fehlschlag oder Abbruch eine Stunde lang aufbewahrt. Das Feld „expiresAt“ zeigt bei abgeschlossenen Jobs den geplanten Löschzeitpunkt an.

Verwenden Sie DELETE /v1/jobs/{id}, sobald Sie nicht mehr benötigte Ergebnisse heruntergeladen haben. Der Aufruf bricht laufende Arbeiten nach Möglichkeit ab und löscht den Job sowie die zugehörigen API-Dateien vor Ablauf der automatischen Aufbewahrungsfrist.