Build · Virtual Try-On

Implementa una funzionalità di virtual try-on per la tua applicazione

In sintesi

Ricevi la foto del prodotto nel tuo backend, invia una richiesta POST a /api/v1/tryon/apparel con un mannequin ID, esegui il polling dell'ID di generazione restituito tramite un worker in background (mai nel thread della richiesta HTTP) finché lo stato non diventa completed, quindi salva output_url nel tuo object storage e renderizzalo nella UI.

Ottieni una chiave APIVedi l'API di virtual try-on
  • Credits: 5 credits a 2K · 6 credits a 4K
  • Tempo tipico: 1.5–4 min
  • Elaborazione: asincrono, polling

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

Una ricetta pronta per la produzione: il cliente carica una foto del prodotto, il tuo backend accoda un job di try-on su Photta, un worker esegue il polling fino al completamento e il frontend mostra il risultato indossato dal modello. Niente richieste bloccanti, nessuna API key esposta, nessun finto SDK.

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

Come funziona

Dall'upload all'immagine con modello

Sei passaggi concreti. La prima volta prevedi dai dieci ai quindici minuti di lavoro di integrazione.

  1. Passaggio 1

    Definisci il flusso dei dati

    Dispositivo del cliente → tuo backend (upload) → Photta API (submit) → Photta API (poll) → tuo database (mirror di stato) → dispositivo del cliente (render). Traccia questo schema su carta prima di scrivere la prima riga di codice — il confine tra il tuo backend e quello di Photta è l'unico aspetto cruciale.

  2. Passaggio 2

    Genera e memorizza una API key

    Le chiavi di produzione iniziano con photta_live_. Salvala in una variabile d'ambiente. Non inviarla mai al browser. Una singola chiave copre tutte le funzionalità di Photta, quindi non hai bisogno di chiavi separate per try-on, jewelry o ghost mannequin.

  3. Passaggio 3

    Configura l'endpoint di upload

    Salva prima di tutto la foto del prodotto inviata dal cliente nel tuo object storage. Fornire a Photta un URL pubblico è più semplice rispetto a base64 e garantisce un tracciamento completo per ogni richiesta.

  4. Passaggio 4

    Invia il job dal server

    Esegui una POST su /api/v1/tryon/apparel specificando URL del prodotto, mannequin_id, resolution e aspect_ratio. L'API risponde con 202 Accepted + un ID di generazione. Salva questo ID nel tuo database in modo che il tuo client possa effettuare il polling sul tuo endpoint, non su quello di Photta.

  5. Passaggio 5

    Esegui il polling da un worker in background

    Non effettuare il polling all'interno della richiesta HTTP: il job richiede da 1.5 a 4 minuti, superando i timeout della maggior parte delle architetture serverless. Utilizza Trigger.dev, Inngest, BullMQ, Vercel Cron o una tua coda per ripianificare una chiamata di polling ogni 3 secondi fino al completamento del job.

  6. Passaggio 6

    Effettua il rendering del risultato

    Quando lo stato passa a completed, copia data.output_url nel tuo database ed emetti un evento in tempo reale (websocket, SSE o long-poll) verso il dispositivo del cliente. La UI sostituisce lo skeleton di caricamento con l'immagine finale. Fatto.

Tre esempi di codice, end-to-end

Gestore di upload, dispatcher dei job, poller lato worker — ogni componente necessario per rilasciare la funzionalità in produzione.

// POST /app/try-on → your backend upload handler
import { put } from "@vercel/blob";

export async function uploadProduct(file: File) {
  const { url } = await put(`products/${crypto.randomUUID()}.jpg`, file, {
    access: "public",
  });
  return url;
}
const res = await fetch("https://api.photta.app/api/v1/tryon/apparel", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "product_type": "top",
    "product_images": [
      "https://cdn.yourstore.com/products/shirt-front.jpg"
    ],
    "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
    "product_category": "t_shirt",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
    "lock_background": true,
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "body_size": "M",
    "expression": "neutral",
    "user_instruction": "Keep the collar pattern crisp and centered."
  }),
});
const { data } = await res.json(); // data.id, data.status
// Trigger.dev / Inngest / BullMQ task
const BASE = "https://api.photta.app/api/v1";

export const pollTryOnTask = task({
  id: "poll-try-on",
  run: async ({ generationId, attempt = 0 }) => {
    const res = await fetch(`${BASE}/tryon/apparel/${generationId}`, {
      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);
    if (attempt >= 120) throw new Error("try-on timed out");
    // Re-schedule this same task after 3 seconds.
    return ctx.retry.after(3000, { generationId, attempt: attempt + 1 });
  },
});

Domande frequenti degli sviluppatori

Domande prima del rilascio

Posso farlo senza un backend?

No. La tua API key di Photta deve rimanere lato server. Anche un semplice route handler di Next.js o un Cloudflare Worker conta come backend a questo scopo — la chiave deve solo risiedere dove uno user-agent non possa leggerla.

Come posso evitare richieste HTTP bloccate?

Non effettuare mai il polling all'interno di un request handler. Invia il job in modo sincrono, restituisci l'ID di generazione al client ed effettua il polling da un worker in background. Il client effettua il polling sul TUO status endpoint, non su quello di Photta — in questo modo i rate limit sono un problema che gestisci tu, non ogni singolo utente.

Cosa succede se un job fallisce durante l'elaborazione?

Photta rimborsa automaticamente i credits in caso di errore, e la risposta include data.error_code + data.error_message. Mostra un messaggio chiaro all'utente e fornisci un pulsante di retry per avviare un nuovo job.

Posso mostrare un avanzamento reale?

Photta non emette uno stato di avanzamento intermedio — lo status è processing, completed o failed. La soluzione ideale è una progress bar temporizzata calibrata sulla finestra di 1.5–4 minuti, o un semplice skeleton loader. Non mostrare percentuali fittizie.

L'URL del risultato è permanente?

L'URL del CDN è stabile, ma il tuo prodotto non dovrebbe dipendere da esso per il rendering a lungo termine. Scarica i byte una volta e salvali nel tuo bucket S3/GCS/R2 — così la tua PDP continua a funzionare anche se il CDN di Photta cambia.

Pagine correlate

Riferimento

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

Implementa il virtual try-on in un pomeriggio

Ogni esempio di codice su questa pagina corrisponde alla documentazione ufficiale di Photta. Richiedi una API key e avrai un prototipo funzionante prima che il caffè sia pronto.

Ottieni una chiave APILeggi la guida rapida