Rakenna · Virtuaalinen try-on

Rakenna virtuaalinen try-on -ominaisuus sovellukseesi

Yhdellä lauseella

Vastaanota tuotekuva backendissäsi, tee POST-pyyntö osoitteeseen /api/v1/tryon/apparel mannekiini-ID:n kanssa, tee palautetulle generointi-ID:lle pollingia taustaworkerista (älä koskaan HTTP-pyyntösäikeestä), kunnes tilaksi vaihtuu completed, tallenna sitten output_url omaan objektitallennustilaasi ja renderöi se käyttöliittymässä.

Hanki API-avainKatso virtuaalisen try-on -ominaisuuden API
  • Credits: 5 credits resoluutiolla 2K · 6 credits resoluutiolla 4K
  • Tyypillinen kesto: 1.5–4 min
  • Käsittely: asynkroninen, polling

Jokainen luku tällä sivulla on peräisin Photta-rajapinnan dokumentaatiosta · tarkistettu

Tuotantovalmis toteutusmalli: asiakas lataa tuotekuvan, backendisi asettaa Photta-try-on-työn jonoon, worker tekee pollingia kunnes työ valmistuu, frontend näyttää on-model-lopputuloksen. Ei blokkaavia pyyntöjä, ei vuotaneita API-avaimia, ei feikkiä SDK:ta.

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

Miten se toimii

Latauksesta on-model-kuvaksi

Kuusi konkreettista vaihetta. Varaa kymmenestä viiteentoista minuuttia integraatiotyöhön ensimmäisellä kerralla.

  1. Vaihe 1

    Hahmottele datavirta

    Asiakkaan laite → backendisi (lataus) → Photta API (lähetys) → Photta API (polling) → tietokantasi (tilapeilaus) → asiakkaan laite (renderöinti). Piirrä tämä paperille ennen ensimmäisen rivin kirjoittamista — rajapinta backendisi ja Photta:n välillä on ainoa asia, jolla on merkitystä.

  2. Vaihe 2

    Luo ja tallenna API-avain

    Tuotantoavaimet alkavat etuliitteellä photta_live_. Tallenna se ympäristömuuttujaan. Älä koskaan lähetä sitä selaimeen. Yksi avain kattaa kaikki Photta:n toiminnot, joten et tarvitse erillisiä avaimia try-on-, koru- tai ghost mannequin -toiminnoille.

  3. Vaihe 3

    Kytke lataus-endpoint toimintaan

    Vastaanota asiakkaan tuotekuva ensin objektitallennustilaan. Julkisen URL-osoitteen antaminen Photta:lle on yksinkertaisempaa kuin base64 ja tarjoaa lokitiedot jokaisesta pyynnöstä.

  4. Vaihe 4

    Lähetä työ palvelimelta

    Tee POST-pyyntö osoitteeseen /api/v1/tryon/apparel sisältäen tuotteen URL:n, mannequin_id:n, resoluution ja kuvasuhteen. API palauttaa 202 Accepted + generointi-ID:n. Tallenna ID tietokantaasi, jotta asiakasohjelmasi voi pollailla omaa endpointiasi, ei Photta:n.

  5. Vaihe 5

    Tee polling taustaworkerista

    Älä tee pollingia HTTP-pyynnön sisällä — työ kestää 1.5–4 minuuttia, mikä ylittää useimmat serverless-aikakatkaisut. Käytä Trigger.dev-, Inngest-, BullMQ-, Vercel Cron -ratkaisua tai omaa jonoasi ajastamaan uusi poll 3 sekunnin välein, kunnes työ on valmis.

  6. Vaihe 6

    Renderöi lopputulos

    Kun tilaksi vaihtuu completed, kopioi data.output_url tietokantaasi ja lähetä reaaliaikainen tapahtuma (websocket, SSE tai long-poll) asiakkaan laitteelle. Käyttöliittymä korvaa latausluurangon kuvalla. Valmista.

Kolme koodiesimerkkiä, päästä päähän

Latauksen käsittelijä, työn välittäjä, worker-puolen pollaaja — jokainen osa, jonka tarvitset ominaisuuden julkaisemiseen.

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

Kehittäjien usein kysymää

Kysymyksiä ennen julkaisua

Voinko tehdä tämän ilman backendia?

Et. Photta API -avaimesi on pysyttävä palvelinpuolella. Jopa kevyt Next.js-reittikäsittelijä tai Cloudflare Worker lasketaan tähän tarkoitukseen backendiksi — avaimen on vain sijaittava paikassa, josta user-agent ei pääse lukemaan sitä.

Miten vältän roikkumaan jäävät HTTP-pyynnöt?

Älä koskaan tee pollingia pyyntökäsittelijän sisällä. Lähetä työ synkronisesti, palauta generation ID asiakkaalle ja hoida polling taustatyöntekijästä (background worker). Asiakas tekee pollingia SINUN status endpointiisi, ei Phottan — näin rate limitit ovat sinun hallinnoitavissasi, eivät yksittäisten käyttäjien vastuulla.

Mitä tapahtuu, jos työ epäonnistuu kesken suorituksen?

Photta palauttaa credits-yksiköt automaattisesti virhetilanteessa, ja vastaus sisältää kentät data.error_code + data.error_message. Näytä käyttäjälle selkeä virheilmoitus ja tarjoa uudelleenyrityspainike, joka käynnistää uuden työn.

Voinko näyttää todellisen edistymisen?

Photta ei lähetä väliaikatietoja edistymisestä — status on joko processing, completed tai failed. Hyvä ratkaisu on ajastettu edistymispalkki, joka on kalibroitu 1.5–4 minuutin aikaikkunaan, tai yksinkertainen skeleton loader. Älä valehtele prosenttilukuja.

Onko tuloksen URL pysyvä?

CDN-URL on vakaa, mutta tuotteesi ei pitäisi nojata siihen pitkäaikaisessa renderöinnissä. Lataa tavut kerran ja tallenna ne omaan S3/GCS/R2-bucketiisi — tällöin tuotesivusi (PDP) toimii edelleen, vaikka Phottan CDN muuttuisi.

Liittyvät sivut

Referenssi

Jokainen luku tällä sivulla on peräisin Photta-rajapinnan dokumentaatiosta · tarkistettu

Toteuta virtuaalinen try-on yhdessä iltapäivässä

Jokainen tämän sivun koodiesimerkki vastaa Phottan virallista dokumentaatiota. Hanki API-avain, niin sinulla on toimiva prototyyppi ennen kuin kahvi ehtii tippua.

Hanki API-avainLue pikaopas