Funktion · Detailfotos

Produktdetailfoto-API für Nahaufnahmen

In aller Kürze

Die Detailfoto-API von Photta rendert eine Nahaufnahme eines bestimmten Produktbereichs. Ein kostenloser Analyze-Aufruf schlägt lohnende Details vor; der Generate-Aufruf kostet pauschal 3 credits, ohne Auflösungsstufen.

  • Typische Dauer: 20–60 sec
  • Credits: 3 Credits
  • Verarbeitung: asynchron, Polling
  • Limits: 600 Anfragen/Min.
  • Authentifizierung: Bearer-Key

Jeder Zahlenwert auf dieser Seite stammt aus der Photta-API-Dokumentation · geprüft

POST/api/v1/detail-photos
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
  "detail_label": "collar stitching",
  "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
  "framing": "extreme-closeup",
  "source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

Auf einen Blick

Auf einen Blick

Endpoint
POST /api/v1/detail-photos
Authentifizierung
Bearer-API-Schlüssel
Verarbeitung
Asynchron — Polling über den Status-Endpoint
Typische Dauer
20–60 sec
Credits
3 Credits
Eingabelimits
Bis zu 10 MB pro Bild; JPEG, PNG, WebP
Idempotent
Nein

Request und Response

Request

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
  "detail_label": "collar stitching",
  "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
  "framing": "extreme-closeup",
  "source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / Abgeschlossen

{
  "data": {
    "id": "dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10",
    "status": "processing",
    "detail_label": "collar stitching",
    "framing": "extreme-closeup",
    "credits_used": 3,
    "created_at": "2026-07-30T14:20:00Z"
  },
  "request_id": "req_dtl001"
}

Request-Parameter

product_image

Typ: stringErforderlich

The source image — a completed generation's output_url or any product photo. https URL or base64 data URI. JPEG, PNG, WebP; max 10 MB.

detail_label

Typ: stringErforderlich

The area to zoom into, e.g. "collar stitching", "cuff detail", "fabric weave on the chest", "pendant clasp". Max 100 characters.

detail_description

Typ: string

Extra guidance for the close-up. Max 400 characters.

framing

Typ: string

How tight the crop is: "extreme-closeup" — the detail fills ~90% of the frame (near-macro); "closeup" — ~70% with some surrounding context; "medium-closeup" — ~50% with body/outfit visible.

= medium-closeup

Werte: extreme-closeupcloseupmedium-closeup
source_type

Typ: string

Tunes what is preserved in the close-up.

= apparel

Werte: appareljewelry

Fehler

400invalid_request_error
The request is malformed or contains invalid parameters.
401authentication_error
The API key is missing, invalid, or expired.
402insufficient_credits_error
Your account does not have enough credits.
404not_found_error
The requested resource does not exist.
409conflict_error
The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error
Too many requests. Slow down and retry.Retry-After: 30
500api_error
An internal server error occurred. Retry later.

Limits

  • 600 Anfragen pro Minute pro API-Schlüssel (Festes Zeitfenster; das Limit ist in jedem Tarif identisch)
  • Ein 429 enthält Retry-After: 30 Sekunden
  • Bis zu 10 MB pro Bild
  • Formate: JPEG, PNG, WebP
  • Gleichzeitige Batches pro Tarif: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Nur Polling — die API sendet keine Webhooks.

Fragen Sie, was sich lohnt, und nehmen Sie es auf

Kostenlos analysieren, Detail auswählen, senden, abfragen, herunterladen.

  1. Schritt 1

    API-Key generieren

    Detailfotos nutzen dieselben Zugangsdaten und dasselbe Guthaben an credits wie jede andere Funktion von Photta.

  2. Schritt 2

    Fragen Sie, welche Details aufgenommen werden sollen

    POST `/api/v1/detail-photos/analyze` mit `product_image`. Gibt synchron vorgeschlagene Werte für `detail_label`, `detail_description` und `framing` für dieses Produkt zurück und berechnet nichts.

  3. Schritt 3

    Nahaufnahme per POST senden

    POST an `/api/v1/detail-photos` mit `product_image` und `detail_label`. Setzen Sie `framing` auf `extreme-closeup`, `closeup` oder `medium-closeup`, `source_type` auf `apparel` oder `jewelry`, und fügen Sie bis zu 400 Zeichen `detail_description` hinzu.

  4. Schritt 4

    Per Polling abfragen, bis der Job abgeschlossen ist

    GET `/api/v1/detail-photos/:id` alle 3 Sekunden aufrufen, bis `data.status` auf `completed` oder `failed` steht; typische Verarbeitungszeit liegt bei 20 bis 60 Sekunden.

  5. Schritt 5

    Herunterladen und persistieren

    Der Body des abgeschlossenen Jobs enthält `output_url`. Detailfotos fügen sich direkt neben dem Hauptbild in eine PDP-Galerie ein.

Häufige Entwicklerfragen vor dem Produktivgang mit Detailfotos

Was ist eine Detailfoto-API?

Ein Endpoint, der eine Nahaufnahme eines benannten Produktbereichs rendert — die Kragennaht, ein Verschluss, die Webstruktur auf der Brust — basierend auf einer einzigen Übersichtsaufnahme statt eines zweiten Studio-Shootings mit Makroobjektiv.

Wie viel kostet ein Detailfoto?

Pauschal 3 credits. Dieser Endpoint bietet keine gestaffelten Auflösungen, und der Analyze-Aufruf für Detailvorschläge ist kostenlos.

Was gibt der Analyze-Endpoint zurück?

Eine Liste von Vorschlägen, jeweils mit einem `detail_label`, einer `detail_description` mit der Begründung, warum dieser Bereich sehenswert ist, und einem empfohlenen `framing`. Übergeben Sie jeden Vorschlag direkt an den Generate-Aufruf.

Wie eng ist jede Framing-Option gefasst?

`extreme-closeup` füllt nahezu den gesamten Frame mit dem Detail, `closeup` belässt etwas Kontext darum herum, und `medium-closeup` zeigt das Detail im Kontext des umliegenden Kleidungsstücks oder Objekts. Wählen Sie dies pro Detail, nicht pro Produkt.

Kann das Ausgangsbild ein generiertes Bild sein?

Ja. `product_image` akzeptiert die `output_url` einer abgeschlossenen Generierung sowie jedes eigene Produktfoto als https-URL oder base64-Data-URI.

Wie führe ich das Polling für das Ergebnis durch?

GET `/api/v1/detail-photos/:id` alle 3 Sekunden ausführen, bis `data.status` `completed` oder `failed` ist. Der analyze-Aufruf ist synchron und erfordert kein Polling.

Verwandte Funktionen

Jeder Zahlenwert auf dieser Seite stammt aus der Photta-API-Dokumentation · geprüft

Testen Sie die API in fünf Minuten

Generieren Sie einen Photta-API-Schlüssel, fügen Sie das obige cURL-Snippet ein, und Sie erhalten Ihr erstes Bild am Model, noch bevor der Kaffee fertig gebrüht ist.

  • 20–60 sec
  • 3 Credits
  • asynchron, Polling
  • 600 Anfragen/Min.
  • Bearer-Key