Funzionalità · Foto di dettagli

API per foto di dettagli prodotto per primi piani

In sintesi

L'API per foto di dettagli di Photta renderizza un primo piano di un'area specifica di un prodotto. Una chiamata di analisi gratuita suggerisce i dettagli che vale la pena fotografare; la chiamata di generazione costa 3 credits fissi, senza scaglioni di risoluzione.

  • Tempo tipico: 20–60 sec
  • Credits: 3 credits
  • Elaborazione: asincrono, polling
  • Limiti: 600 richieste/min
  • Autenticazione: Chiave Bearer

Ogni dato in questa pagina proviene da la documentazione dell'API di Photta · verificato

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

Panoramica

Panoramica

Endpoint
POST /api/v1/detail-photos
Autenticazione
API key Bearer
Elaborazione
Asincrona — effettua il polling dell'endpoint di stato
Tempo tipico
20–60 sec
Credits
3 credits
Limiti di input
Fino a 10 MB per immagine; JPEG, PNG, WebP
Idempotente
No

Richiesta e risposta

Richiesta

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 / Completato

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

Parametri della richiesta

product_image

Tipo: stringObbligatorio

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

Tipo: stringObbligatorio

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

detail_description

Tipo: string

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

framing

Tipo: 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

Valori: extreme-closeupcloseupmedium-closeup
source_type

Tipo: string

Tunes what is preserved in the close-up.

= apparel

Valori: appareljewelry

Errori

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.

Limiti

  • 600 richieste al minuto per API key (Finestra fissa; il limite è lo stesso per ogni piano)
  • Un 429 restituisce Retry-After: 30 secondi
  • Fino a 10 MB per immagine
  • Formati: JPEG, PNG, WebP
  • Batch simultanei per piano: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Solo polling — l'API non invia webhook.

Chiedi cosa vale la pena fotografare, poi scatta

Analizza gratis, scegli un dettaglio, invia, fai polling, scarica.

  1. Passaggio 1

    Genera una chiave API

    Le foto di dettagli usano le stesse credenziali e lo stesso saldo di credits di ogni altra funzionalità Photta.

  2. Passaggio 2

    Chiedi quali dettagli fotografare

    POST `/api/v1/detail-photos/analyze` con `product_image`. Restituisce valori suggeriti per `detail_label`, `detail_description` e `framing` per quel prodotto, in modo sincrono e senza alcun addebito.

  3. Passaggio 3

    Invia il primo piano via POST

    POST su `/api/v1/detail-photos` con `product_image` e `detail_label`. Imposta `framing` su `extreme-closeup`, `closeup` o `medium-closeup`, `source_type` su `apparel` o `jewelry`, e aggiungi fino a 400 caratteri di `detail_description`.

  4. Passaggio 4

    Esegui il polling fino al completamento del job

    GET `/api/v1/detail-photos/:id` ogni 3 secondi finché `data.status` non è `completed` o `failed`; il completamento tipico richiede da 20 a 60 secondi.

  5. Passaggio 5

    Scarica e memorizza

    Il payload completato contiene `output_url`. Le foto di dettagli si inseriscono direttamente nella galleria della PDP accanto allo scatto principale.

Domande che gli sviluppatori si pongono prima di rilasciare le foto di dettagli

Cos'è un'API per foto di dettagli?

Un endpoint che renderizza un primo piano di un'area specifica di un prodotto — le cuciture del colletto, una chiusura, la trama sul petto — a partire da una singola fotografia più ampia, invece di una seconda sessione in studio con un obiettivo macro.

Quanto costa una foto di dettagli?

3 credits fissi. Non ci sono scaglioni di risoluzione su questo endpoint, e la chiamata di analisi che suggerisce i dettagli è gratuita.

Cosa restituisce l'endpoint di analisi?

Un elenco di suggerimenti, ciascuno con un `detail_label`, una `detail_description` che spiega perché vale la pena mostrare quell'area, e un `framing` consigliato. Passa qualsiasi suggerimento direttamente alla chiamata di generazione.

Quanto è stretto ciascun livello di inquadratura?

`extreme-closeup` riempie quasi l'intero fotogramma con il dettaglio, `closeup` mantiene un po' di contesto attorno ad esso, e `medium-closeup` mostra il dettaglio all'interno del capo o dell'articolo circostante. Scegli in base al dettaglio, non per prodotto.

La sorgente può essere un'immagine generata?

Sì. `product_image` accetta sia l' `output_url` di una generazione completata, sia una tua foto del prodotto, come URL https o data URI base64.

Come effettuo il polling per il risultato?

GET `/api/v1/detail-photos/:id` ogni 3 secondi finché `data.status` non diventa `completed` o `failed`. La chiamata di analisi è sincrona e non richiede polling.

Funzionalità correlate

Ogni dato in questa pagina proviene da la documentazione dell'API di Photta · verificato

Prova l'API in 5 minuti

Genera una chiave API di Photta, incolla lo snippet cURL qui sopra e otterrai la tua prima immagine con modello prima ancora che il caffè sia pronto.

  • 20–60 sec
  • 3 credits
  • asincrono, polling
  • 600 richieste/min
  • Chiave Bearer