Build · Shopify

Shopify-Try-on-App erstellen

In aller Kürze

Eine Shopify-Try-on-App liest das Produktbild aus der Admin-API, überträgt es per POST an Photta, pollt den Job in einem Hintergrund-Worker und übergibt die fertige URL über productCreateMedia an Shopify.

API-Key anfordernDokumentation zum Try-on-Endpoint lesen
  • Credits: 5 Credits bei 2K · 6 Credits bei 4K
  • Typische Dauer: 1.5–4 min
  • Verarbeitung: asynchron, Polling

Jeder Zahlenwert auf dieser Seite stammt aus der Photta-API-Dokumentation · geprüft

Produktfoto über die Admin-API einlesen, Try-on mit Photta rendern und das Ergebnis als Produkt-Media zurückschreiben. Vier Calls, kein eigenes Bild-Handling.

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

Funktionsweise

Von der Produktseite zum Try-on-Bild

App-Scopes festlegen, Foto auslesen, übermitteln, außerhalb des Request-Pfads pollen, Media anhängen.

  1. Schritt 1

    App-Scopes festlegen

    Eine Try-on-App muss Produkte lesen und Media schreiben. Fordere nur die Scopes an, die deine App wirklich nutzt, nicht mehr — Händler prüfen den Zustimmungsbildschirm.

  2. Schritt 2

    Photta-API-Key anfordern

    Ein Key pro Umgebung, sicher in der Server-Konfiguration deiner App hinterlegt. Er wird niemals an die Storefront oder den Browser des Händlers übertragen.

  3. Schritt 3

    Produktbild einlesen

    Erstes Produktbild abfragen. Diese URL ist öffentlich zugänglich — genau das, was der Photta-Endpoint erwartet: kein erneuter Upload, keine signierten URLs zur Verwaltung.

  4. Schritt 4

    Try-on übermitteln

    Sende das Bild zusammen mit mannequin und pose per POST. Die Antwort erfolgt sofort und enthält die generation id; gerendert ist zu diesem Zeitpunkt noch nichts.

  5. Schritt 5

    In einem Hintergrund-Job pollen

    Shopify erwartet, dass Webhook-Handler innerhalb von Sekunden antworten, während die Generierung länger dauert. Sofort bestätigen, in die Warteschlange einreihen und alle 3 Sekunden über den Worker pollen.

  6. Schritt 6

    Media anhängen

    Übergib die fertige URL an Shopify; der Dienst lädt die Datei selbst herunter. Speichere das Bild zusätzlich auf deiner Seite, damit die Galerie unabhängig erhalten bleibt.

Die vier Calls, End-to-End

Die Photta-Requests und das Polling stammen direkt aus der API-Dokumentation; die Shopify-Calls gehören zur Admin-API selbst.

// 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" }],
  },
});

Häufige Fragen von Entwicklern

Häufige Fragen von Shopify-Entwicklern

Wo wird der Photta-Key in einer Shopify-App hinterlegt?

Im Environment deines App-Servers, niemals im Theme, in einem App-Block oder in einer App-Proxy-Response. Alles, was die Storefront einsehen kann, ist auch für Käufer sichtbar.

Welche Shopify-Scopes werden hierfür benötigt?

Lesen des Produktbilds und Schreiben von Produkt-Media. Photta benötigt keinerlei Zugriff auf Shopify — deine App ist die einzige Schnittstelle, die mit beiden Seiten kommuniziert.

Wie sorge ich für einen schnellen Webhook-Handler?

Sofort bestätigen, den Task in die Warteschlange einreihen und über den Worker pollen. Da die Generierung länger dauert, als ein Webhook-Handler laufen sollte, gehört kein blockierender Code in den Handler.

Kann ich Händlern die Kosten pro Bild in Rechnung stellen?

Das liegt vollständig bei deinem Preismodell. Photta rechnet über deinen Account in credits pro Call ab, sodass die Kosten pro Bild bereits vor dem Rendern feststehen. Was du darüber hinaus verlangst, entscheidest du.

Was passiert, wenn ein Produkt kein Foto hat?

Überspringe es, anstatt einen Platzhalter zu senden. Der Endpoint benötigt eine echte Aufnahme des Kleidungsstücks; ein Platzhalter verbraucht unnötig credits für ein Bild, das niemand veröffentlicht.

Verwandte Seiten

Weiterführende Artikel

Jeder Zahlenwert auf dieser Seite stammt aus der Photta-API-Dokumentation · geprüft

App ausliefern statt Infrastruktur bauen

Die Photta-Calls auf dieser Seite stammen direkt aus der API-Dokumentation. Key anfordern und das erste Rendering ist in wenigen Minuten fertig.

API-Key anfordernQuickstart lesen