Build · Shopify

Crea un'app di try-on per Shopify

In sintesi

Un'app di try-on per Shopify legge l'immagine del prodotto dalle Admin API, esegue una POST a Photta, fa il polling del job in un worker in background, quindi passa a Shopify l'URL finale tramite productCreateMedia.

Ottieni una chiave APILeggi la documentazione dell'endpoint di 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

Leggi la foto del prodotto dalle Admin API, effettua il rendering del try-on con Photta e reinvia il risultato come media del prodotto. Quattro chiamate, nessuna gestione delle immagini a tuo carico.

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

Da una pagina prodotto a un'immagine di try-on

Definisci gli scope dell'app, leggi la foto, invia la richiesta, fai il polling fuori dal percorso della richiesta, allega il media.

  1. Passaggio 1

    Definisci gli scope dell'app

    Un'app di try-on deve leggere i prodotti e scrivere i media. Richiedi solo gli scope per i prodotti effettivamente usati dall'app e null'altro — i merchant controllano la schermata di consenso.

  2. Passaggio 2

    Ottieni una chiave API di Photta

    Una chiave per ambiente, salvata nella configurazione server-side dell'app. Non viene mai trasmessa allo storefront o al browser del merchant.

  3. Passaggio 3

    Leggi l'immagine del prodotto

    Interroga il prodotto per ottenere la sua prima immagine. Quell'URL è pubblico, esattamente ciò che richiede l'endpoint di Photta — nessun nuovo upload, nessun URL firmato da gestire.

  4. Passaggio 4

    Invia la richiesta di try-on

    Invia l'immagine tramite POST indicando un manichino e una posa. La risposta è immediata e contiene l'id della generazione; al momento non viene renderizzato nulla.

  5. Passaggio 5

    Esegui il polling in un job in background

    Shopify si aspetta che un gestore di webhook risponda in pochi secondi, mentre una generazione richiede più tempo. Invia l'acknowledgement, accoda il job ed esegui il polling ogni 3 secondi dal worker.

  6. Passaggio 6

    Allega il media

    Passa a Shopify l'URL finale e il download del file avverrà in automatico. Conserva l'immagine anche dal tuo lato, così che la galleria rimanga disponibile in modo indipendente.

Le quattro chiamate, end-to-end

La richiesta e il polling di Photta sono ricavati dalla documentazione dell'API; le chiamate Shopify provengono direttamente dalle Admin API.

// Shopify Admin GraphQL — the product's first image is your source photo
const query = `query($id: ID!) {
  product(id: $id) { title images(first: 1) { nodes { url } } }
}`;

const res = await admin.graphql(query, { variables: { id: productGid } });
const { data } = await res.json();
const productImage = data.product.images.nodes[0].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
async function waitFor(id) {
  for (let attempt = 0; attempt < 120; attempt++) {
    const res = await fetch(`https://api.photta.app/api/v1/tryon/apparel/${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");
}
// Shopify downloads the URL itself, so hand it the Photta output_url
const mutation = `mutation($id: ID!, $media: [CreateMediaInput!]!) {
  productCreateMedia(productId: $id, media: $media) {
    mediaUserErrors { field message }
  }
}`;

await admin.graphql(mutation, {
  variables: {
    id: productGid,
    media: [{ originalSource: outputUrl, mediaContentType: "IMAGE", alt: "Virtual try-on" }],
  },
});

Domande frequenti degli sviluppatori

Domande frequenti degli sviluppatori Shopify

Dove risiede la chiave di Photta in un'app Shopify?

Nell'ambiente del server della tua app, mai nel tema, in un app block o nella risposta di un app proxy. Tutto ciò che lo storefront può leggere è visibile anche agli acquirenti.

Di quali scope di Shopify ha bisogno?

Della lettura dell'immagine del prodotto e della scrittura dei media del prodotto. Photta non richiede alcun accesso a Shopify — la tua app è l'unico componente a comunicare con entrambe le parti.

Come mantengo veloce il webhook?

Invia subito l'acknowledgement, accoda il task ed esegui il polling dal worker. Una generazione richiede più tempo di quanto dovrebbe impiegare un gestore di webhook, quindi nessuna operazione di attesa deve risiedere nell'handler.

Posso fatturare ai merchant per singola immagine?

È una tua scelta di pricing. Photta addebita sul tuo account un costo in credits per chiamata, quindi il costo per immagine è noto prima del rendering; il margine da applicare dipende interamente da te.

Cosa succede se un prodotto non ha foto?

Ignoralo anziché inviare un placeholder. L'endpoint richiede una foto reale del capo, e un placeholder consuma credits per un'immagine che nessuno pubblicherà.

Pagine correlate

Letture consigliate

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

Distribuisci l'app, non l'infrastruttura di base

Le chiamate Photta illustrate in questa pagina provengono direttamente dalla documentazione dell'API. Ottieni una chiave e il primo rendering sarà pronto in pochi minuti.

Ottieni una chiave APILeggi la guida introduttiva