Intégration · Shopify

Créer une application de try-on Shopify

En une phrase

Une application de try-on Shopify lit l’image du produit depuis l’Admin API, l’envoie en POST à Photta, effectue le polling du job dans un worker d’arrière-plan, puis transmet l’URL finale à Shopify via productCreateMedia.

Obtenir une clé APIConsulter la documentation de l’endpoint de try-on
  • Crédits: 5 crédits en 2K · 6 crédits en 4K
  • Délai typique: 1.5–4 min
  • Traitement: asynchrone, polling

Chaque chiffre sur cette page provient de la documentation de l'API Photta · vérifié

Récupérez la photo du produit via l’Admin API, générez le try-on avec Photta et renvoyez le résultat sous forme de média produit. Quatre appels, aucun traitement d’image à votre charge.

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

Comment ça fonctionne

D’une page produit à une image de try-on

Définir les scopes, lire la photo, soumettre, gérer le polling hors du cycle de requête, associer le média.

  1. Étape 1

    Définir les scopes de l’application

    Une application de try-on doit lire les produits et écrire des médias. Demandez uniquement les scopes nécessaires à votre application — les marchands vérifient l’écran de consentement.

  2. Étape 2

    Obtenir une clé d’API Photta

    Une clé par environnement, conservée dans la configuration côté serveur de votre application. Elle ne doit jamais transiter par la vitrine (storefront) ni par le navigateur du marchand.

  3. Étape 3

    Lire l’image du produit

    Interrogez le produit pour récupérer sa première image. Cette URL est publique, ce qui correspond exactement à ce qu’attend l’endpoint Photta — aucun réupload, aucune URL signée à gérer.

  4. Étape 4

    Soumettre le try-on

    Envoyez l’image en POST avec un mannequin et une pose. La réponse est immédiate et contient l’ID de génération ; aucun rendu n’est encore effectué.

  5. Étape 5

    Effectuer le polling dans un job d’arrière-plan

    Shopify attend une réponse de votre webhook en quelques secondes, or une génération prend plus de temps. Acquittez la requête, mettez le job en file d’attente et effectuez le polling toutes les 3 secondes depuis le worker.

  6. Étape 6

    Associer le média

    Transmettez l’URL finale à Shopify qui se charge de télécharger le fichier. Conservez également l’image de votre côté pour que la galerie reste disponible de manière autonome.

Les quatre appels, de bout en bout

La requête et le polling Photta sont tirés de la documentation de l’API ; les appels Shopify sont directement ceux de l’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" }],
  },
});

Questions fréquentes des développeurs

Questions fréquentes des développeurs Shopify

Où doit être stockée la clé Photta dans une application Shopify ?

Dans les variables d’environnement de votre serveur d’application, jamais dans le thème, un bloc d’application ou la réponse d’un proxy d’application. Tout ce qui est accessible par la vitrine est accessible par l’acheteur.

Quels scopes Shopify sont nécessaires ?

La lecture des images de produits et l’écriture des médias produits. Photta n’a besoin d’aucun accès à Shopify — votre application est le seul pont entre les deux services.

Comment garantir la rapidité de réponse du webhook ?

Acquittez immédiatement la réception, placez le traitement en file d’attente et effectuez le polling depuis le worker. Une génération prend plus de temps que la durée tolérée pour un webhook ; aucune attente bloquante ne doit s’y trouver.

Puis-je facturer les marchands par image ?

Ce choix tarifaire vous appartient. Photta facture votre compte en credits par appel, le coût unitaire par image est donc connu avant le rendu ; votre marge dépend de vous.

Que faire si un produit ne possède aucune photo ?

Ignorez-le au lieu d’envoyer une image de remplacement (placeholder). L’endpoint nécessite une vraie photo du vêtement, et un placeholder consommerait des credits pour une image qui ne sera jamais publiée.

Pages associées

Lectures complémentaires

Chaque chiffre sur cette page provient de la documentation de l'API Photta · vérifié

Déployez l’application, pas l’infrastructure

Les appels Photta présentés sur cette page proviennent directement de la documentation de l’API. Obtenez une clé et lancez votre premier rendu en quelques minutes.

Obtenir une clé APIConsulter le guide de démarrage rapide