PhotoFig-API

API-Routen akzeptieren API-Schlüssel aus den Einstellungen. Das vollständige Geheimnis wird nur einmal angezeigt, wenn der Schlüssel erstellt wird.

Authorization: Bearer pf_live_...

Verwenden Sie diese Route als schnellen Funktionstest für Ihre Zugangsdaten und um Planlimits, verbleibende Credits und verfügbare Tools zu prüfen.

{
  "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 mehrteiligen Upload. Sie müssen mask nicht zuerst aufrufen, es sei denn, Sie möchten ausdrücklich einen transparenten Ausschnitt.

Dies ist der einfachste Weg: Senden Sie eine Bearbeitung mit einer imageUrl, wenn das Quellbild bereits über die URL erreichbar ist, oder senden Sie ein mehrteiliges Bildfeld für eine schnelle lokale Dateianforderung. Am besten ist es, wenn Sie nur ein Tool für eine Eingabe ausführen müssen.

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 mehr als ein Tool für dieselbe Eingabe ausführen 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, wenn die Upload-Größe wichtig ist oder wenn dasselbe Quellbild mehrere Tools oder Wiederholungsversuche speist.

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 Änderungen mit imageUrl, uploadSessionId oder einem mehrteiligen Feldbild. Die Antwort gibt eine Job-ID zurück, die Sie zum Abfragen, Abbrechen, Löschen und zur Webhook-Korrelation verwenden können.

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: warme Tischplatte aus Eiche,minimalistisches weißes Studio, and Sanftes Morgenlicht in der Küche.

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

Maske

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 in angemeldeten Uploads oder Designs angezeigt, durch das Löschen werden jedoch API-eigene Artefakte 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 sind Rückrufe von PhotoFig an Ihren Server. Registrieren Sie eine HTTPS-URL und PhotoFig sendet eine Anfrage, wenn ein API-Job abgeschlossen wird, fehlschlägt oder abgebrochen wird. Dadurch kann Ihr Backend sofort reagieren, anstatt GET /v1/jobs/{id} abzufragen, bis sich der Status ändert.

Unterstützte Ereignisse sind webhook.test,job.completed,job.failed, und job.cancelled. Ereignisnutzlasten verwenden 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 verwenden einen stabilen maschinenlesbaren Code und eine für Menschen lesbare Nachricht. Behandeln Sie den Code als den Wert, auf den in der Clientlogik verzweigt werden soll.

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

Abgeschlossene API-Jobs bleiben über GET /v1/jobs und GET /v1/jobs/{id} sichtbar. Die Statusantwort enthält signierte ResultUrl- und ThumbnailUrl-Links, wenn Ausgaben verfügbar sind.

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

API-Auftragsdatensätze und API-eigene Eingabe-, Ergebnis- und Miniaturbilddateien werden eine Stunde lang aufbewahrt, nachdem der Auftrag abgeschlossen, fehlgeschlagen oder abgebrochen wurde. Das Feld „expiresAt“ zeigt die geplante Bereinigungszeit für abgeschlossene Jobs an.

Verwenden Sie DELETE /v1/jobs/{id}, nachdem Sie Ergebnisse heruntergeladen haben, die Sie nicht mehr benötigen. Es bricht nach Möglichkeit nicht abgeschlossene Arbeiten ab und löscht den Auftragsdatensatz sowie API-eigene Artefakte vor dem automatischen Bereinigungsfenster.