cURL · API Ghost mannequin
API Ghost mannequin con cURL
In sintesi
Esporta PHOTTA_API_KEY, invia una POST a https://api.photta.app/api/v1/api/v1/ghost-mannequin con il body JSON documentato, acquisisci l'ID di generazione, quindi esegui ciclicamente una GET su /api/v1/ghost-mannequin/{id} ogni 3 secondi finché data.status non è completed. Abbinalo a jq per estrarre l'URL di output.
- Tempo tipico: 1.5–4 min
- Credits: 4 credits a 2K · 5 credits a 4K
- Elaborazione: asincrono, polling
- Limiti: 600 richieste/min
- Autenticazione: Chiave Bearer
Ogni dato in questa pagina proviene da la documentazione dell'API di Photta · verificato
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
"back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
"image_side": "front",
"angle": "side",
"style": "3d",
"background_color": "white",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "closed front, cream interior lining",
"brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')
# $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed".
for i in $(seq 1 120); do
RESULT=$(curl -s "https://api.photta.app/api/v1/ghost-mannequin/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY")
STATUS=$(echo "$RESULT" | jq -r '.data.status')
[ "$STATUS" = "completed" ] && break
[ "$STATUS" = "failed" ] && echo "generation failed" && exit 1
sleep 3
done
echo "$RESULT" | jq -r '.data.output_url'const res = await fetch("https://api.photta.app/api/v1/ghost-mannequin", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
"back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
"image_side": "front",
"angle": "side",
"style": "3d",
"background_color": "white",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "closed front, cream interior lining",
"brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}),
});
const { data } = await res.json(); // data.id, data.status
async function waitFor(id) {
for (let attempt = 0; attempt < 120; attempt++) {
const res = await fetch(`https://api.photta.app/api/v1/ghost-mannequin/${id}`, { headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}` } });
const { data } = await res.json();
if (data.status === "completed") return data.output_url;
if (data.status === "failed") throw new Error(data.error_message ?? "generation failed");
await new Promise((r) => setTimeout(r, 3000));
}
throw new Error("timed out after 6 minutes");
}import os, requests
res = requests.post(
"https://api.photta.app/api/v1/ghost-mannequin",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
"back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
"image_side": "front",
"angle": "side",
"style": "3d",
"background_color": "white",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "closed front, cream interior lining",
"brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
},
)
data = res.json()["data"] # data["id"], data["status"]
import time
def wait_for(job_id):
for _ in range(120):
res = requests.get(f"https://api.photta.app/api/v1/ghost-mannequin/{job_id}", headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"})
data = res.json()["data"]
if data["status"] == "completed":
return data["output_url"]
if data["status"] == "failed":
raise RuntimeError(data.get("error_message", "generation failed"))
time.sleep(3)
raise TimeoutError("timed out after 6 minutes")Panoramica
Panoramica
- Endpoint
- POST /api/v1/ghost-mannequin
- Autenticazione
- API key Bearer
- Elaborazione
- Asincrona — effettua il polling dell'endpoint di stato
- Tempo tipico
- 1.5–4 min
- Credits
- 4 credits a 2K · 5 credits a 4K
- Rapporti d'aspetto
- 3:4 · 1:1 · 4:3 · 9:16 · 16:9
- Limiti di input
- Fino a 10 MB per immagine; JPEG, PNG, WebP
- Idempotente
- No
Come funziona
Cinque passaggi da shell, zero dipendenze oltre a curl e jq.
Passaggio 1
Registrati e genera una chiave
Vai su ai.photta.app, apri la scheda Developers, fai clic su Generate API key. Le chiavi live iniziano con `photta_live_`.
Passaggio 2
Esporta la chiave
Inserisci `export PHOTTA_API_KEY="photta_live_xxx"` nel profilo della tua shell o in un file `.envrc` in modo che ogni successiva chiamata curl la rilevi automaticamente.
curl --version # macOS, Linux, WSL and Windows 10+ ship it export PHOTTA_API_KEY="photta_live_xxxxx"Passaggio 3
Fissa l'URL di base
`export PHOTTA_BASE_URL="https://api.photta.app/api/v1"` mantiene brevi i comandi curl.
export PHOTTA_BASE_URL="https://api.photta.app/api/v1" export AUTH_HEADER="Authorization: Bearer $PHOTTA_API_KEY"Passaggio 4
Invia ed esegui il polling
Invia una POST a `$PHOTTA_BASE_URL/api/v1/ghost-mannequin` per ottenere un ID, quindi esegui un ciclo con `curl $PHOTTA_BASE_URL/api/v1/ghost-mannequin/{id}` ogni 3 secondi. Passa la risposta a jq tramite pipe per estrarre `.data.status` in modo pulito.
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \ -H "Authorization: Bearer $PHOTTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg", "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg", "image_side": "front", "angle": "side", "style": "3d", "background_color": "white", "resolution": "2K", "aspect_ratio": "3:4", "user_instruction": "closed front, cream interior lining", "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67" }') ID=$(echo "$RESPONSE" | jq -r '.data.id') # $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed". for i in $(seq 1 120); do RESULT=$(curl -s "https://api.photta.app/api/v1/ghost-mannequin/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY") STATUS=$(echo "$RESULT" | jq -r '.data.status') [ "$STATUS" = "completed" ] && break [ "$STATUS" = "failed" ] && echo "generation failed" && exit 1 sleep 3 done echo "$RESULT" | jq -r '.data.output_url'Passaggio 5
Salva il risultato
Quando il job viene completato, estrai `.data.output_url` con jq e usa `curl -o` per salvare i byte nello storage locale — pronto per il passaggio successivo della pipeline.
Errori
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_error - An internal server error occurred. Retry later.
case "$STATUS_CODE" in
402) echo "insufficient_credits_error — top up before retrying" ;;
429) echo "rate_limit_error — wait the Retry-After seconds (30 by default)" ;;
4??) echo "$BODY" | jq '.error.type, .error.message' ;;
5??) echo "api_error — retry with backoff" ;;
esacLimiti
- 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.
Perché cURL è ancora il modo più rapido per verificare un'API
- Nessuna installazione — cURL è incluso in tutti i principali sistemi operativi
- Si integra perfettamente con jq per pipeline basate su script (CI, cron, shell hook)
- Il modo più rapido per fare smoke testing su un endpoint prima di integrarlo nel codice
- Ogni comando in questa pagina può essere incollato in qualsiasi shell POSIX
Cosa non fa
- Il ciclo di polling blocca il terminale — passa a Node o Python per worker paralleli
- Il polling è l'unico segnale di completamento; l'API non invia webhook
- Gli utenti del Prompt dei comandi di Windows dovrebbero usare WSL o curl.exe di PowerShell
Domande frequenti degli sviluppatori
Esiste uno strumento CLI di Photta?
Non ancora — ma cURL combinato con uno script bash di quindici righe risolve gran parte delle esigenze. La documentazione dà priorità a esempi basati su cURL perché ogni linguaggio può eseguire un sottoprocesso, e la shell è il denominatore comune nelle pipeline CI.
Serve jq per usare l'API?
Non strettamente — ma le pipeline basate su script risultano molto più semplici. jq consente di estrarre `.data.id`, `.data.status` e `.data.output_url` dalla risposta JSON senza doverne fare il parsing a mano. Installalo con `brew install jq` su macOS o `apt install jq` su Debian/Ubuntu.
Come si effettua l'autenticazione con curl?
Aggiungi `-H "Authorization: Bearer $PHOTTA_API_KEY"` a ogni richiesta. Mantieni la chiave in una variabile d'ambiente, senza mai inserirla inline in uno script sottoposto a commit. Funziona anche `curl --oauth2-bearer`, ma la forma con header esplicito è più chiara nella documentazione e nei log.
Posso usare script basati su curl in produzione?
Per backfill batch una tantum e job cron, sì — migliaia di team gestiscono il backfill dei cataloghi in questo modo. Per un'applicazione a lungo termine, un vero linguaggio di programmazione è generalmente preferibile per disporre di corretta gestione degli errori, retry e osservabilità. Gli esempi curl su questa pagina rimangono validi anche dopo il porting su Node o Python; la struttura della richiesta è identica.
Come si esegue il polling da un ciclo bash?
Usa `for i in $(seq 1 120); do … ; sleep 3; done` con il controllo dello stato nel corpo del ciclo. Interrompi quando `.data.status` è `completed` o `failed`. Il frammento di codice in questa pagina mostra il pattern esatto, incluso un limite massimo rigido affinché un job bloccato non mantenga lo script in sospeso all'infinito.
Come si leggono le risposte di errore in curl?
Usa `curl -w "\n%{http_code}"` per catturare il codice di stato HTTP insieme al body JSON. Gestisci i diversi rami in base allo stato: 402 per crediti insufficienti, 429 per rate limit (rispetta il valore di Retry-After), 5xx per errori temporanei del server. Il body dell'errore include sempre i campi `error.code` e `error.message`.
Pagine correlate
Node.js
API Ghost mannequin in Node.js
Chiama aPI Ghost mannequin di Photta da un backend Node.js con fetch nativo. Nessun SDK richiesto: salva la chiave, invia il job, esegui il polling per il risultato.
LeggiPython
API Ghost mannequin in Python
Chiama la aPI Ghost mannequin di Photta in Python con la libreria requests. Wrapper di trenta righe, compatibile con async tramite httpx, funziona in Django, FastAPI e Celery.
LeggiFunzionalità
API Ghost mannequin per foto prodotto con manichino invisibile
Endpoint AI per ghost mannequin. Rimuovi il manichino dalla foto di un capo e preserva i dettagli interni. 3D o flat-lay, elaborazione in batch, 4 credits a 2K.
LeggiSviluppa
Automatizza l'estrazione ghost mannequin per il tuo catalogo
Ricetta per l'automazione notturna del catalogo: estrai gli aggiornamenti prodotto di ieri, invia la richiesta in batch all'API ghost-mannequin di Photta, esegui il polling sul batch genitore, salva i dati nel tuo database.
LeggiGuida rapida
La prima immagine con Photta in meno di cinque minuti.
Registrati, genera una chiave API, esegui la tua prima chiamata cURL, fai polling fino al completamento, salva il risultato. Cinque passaggi, interamente documentati.
LeggiRiferimento
Prezzi dell'API Photta
Il costo in crediti di ogni endpoint delle API di Photta a 2K e 4K, il funzionamento di addebiti e rimborsi, e quali endpoint sono gratuiti. Nessun prezzo monetario per immagine.
Leggi
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.
- 1.5–4 min
- 4 credits a 2K · 5 credits a 4K
- asincrono, polling
- 600 richieste/min
- Chiave Bearer