Node.js · Takı try-on API'si

Takı try-on API'si Node.js içinde

Tek cümlede

Ortam değişkenlerinde PHOTTA_API_KEY tanımlayın, Bearer anahtarıyla https://api.photta.app/api/v1 için ufak bir fetch yardımcısı yazın, /api/v1/tryon/jewelry adresine POST atın, ardından durum completed olana kadar her 3 saniyede bir /api/v1/tryon/jewelry/{id} adresini poll edin.

  • Tipik süre: 1.5–4 min
  • Credits: 2K'da 5 credits · 4K'da 6 credits
  • İşleme: asenkron, polling
  • Sınırlar: 600 istek/dk
  • Kimlik doğrulama: Bearer anahtarı

Bu sayfadaki her veri şuradan alınmıştır: Photta API dokümantasyonu · kontrol edildi

POST/api/v1/tryon/jewelry
const res = await fetch("https://api.photta.app/api/v1/tryon/jewelry", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
    "jewelry_type": "necklace",
    "mannequin_id": "mnk_j9k1l2",
    "background": "soft window light on dark velvet",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "user_instruction": "Make the pendant 10% smaller."
  }),
});
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/jewelry/${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");
}

Genel bakış

Genel bakış

Endpoint
POST /api/v1/tryon/jewelry
Kimlik doğrulama
Bearer API anahtarı
İşleme
Asenkron — durum endpoint'ini sorgulayın (poll)
Tipik süre
1.5–4 min
Credits
2K'da 5 credits · 4K'da 6 credits
En-boy oranları
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Girdi sınırları
Görsel başına en fazla 10 MB; JPEG, PNG, WebP
Idempotent
Hayır

Nasıl çalışır

Beş adım, kayıttan ilk görsele yaklaşık beş dakika.

  1. Adım 1

    Kayıt olun ve bir anahtar oluşturun

    ai.photta.app adresinde bir hesap oluşturun. Panonun Developers bölümünü açın, Generate API key'e tıklayın ve canlı anahtarı alın. `photta_live_` ile başlar ve ardından 32 onaltılık (hex) karakter gelir.

  2. Adım 2

    Anahtarı kaynak kodda değil, ortam değişkenlerinde saklayın

    `.env` dosyasına (veya platformunuzun gizli bilgi deposuna) `PHOTTA_API_KEY=...` ekleyin ve bunu `process.env` üzerinden yükleyin. Anahtarı asla commit'lemeyin; asla `'use client'` ile işaretlenmiş bir dosyaya import etmeyin — paketleyici bunu tarayıcıya dahil eder.

    node --version   # 18 or later ships fetch
    echo "PHOTTA_API_KEY=photta_live_xxxxx" >> .env
  3. Adım 3

    Küçük bir fetch yardımcısı yazın

    `fetch()` etrafındaki 20 satırlık tek bir sarmalayıcı temel URL'yi, Authorization başlığını, JSON gövdesini ve hata normalizasyonunu halleder. Resmi bir SDK çıkana kadar ihtiyacınız olan tek soyutlama budur.

    // photta.js — one helper for every endpoint
    const BASE = "https://api.photta.app/api/v1";
    export async function photta(path, init = {}) {
      const res = await fetch(BASE + path, { ...init, headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json", ...(init.headers ?? {}) } });
      const body = await res.json();
      if (!res.ok) throw Object.assign(new Error(body.error?.message ?? res.statusText), { status: res.status, retryAfter: res.headers.get("Retry-After"), body });
      return body;
    }
  4. Adım 4

    Bir try-on gönderin ve polling yapın

    Belgelenen örnek gövdeyle `/api/v1/tryon/jewelry` adresine POST isteği atın — aşağıdaki kod her alanı içerir. API anında bir oluşturma kimliği döndürür. `status === 'completed'` olana kadar her 3 saniyede bir `/api/v1/tryon/jewelry/{id}` adresini poll edin.

    const res = await fetch("https://api.photta.app/api/v1/tryon/jewelry", {
      method: "POST",
      headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
      body: JSON.stringify({
        "jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
        "jewelry_type": "necklace",
        "mannequin_id": "mnk_j9k1l2",
        "background": "soft window light on dark velvet",
        "resolution": "2K",
        "aspect_ratio": "3:4",
        "user_instruction": "Make the pendant 10% smaller."
      }),
    });
    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/jewelry/${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");
    }
  5. Adım 5

    Sonucu kalıcı hale getirin

    Tamamlanan payload `output_url` ve `thumbnail_url` içerir. Baytları bir kez fetch edin ve kendi nesne depolama alanınızda saklayın — URL'ler kararlıdır ancak ürününüz render için Photta'nın CDN'ine bağımlı olmamalıdır.

Hatalar

400invalid_request_error
The request is malformed or contains invalid parameters.
401authentication_error
The API key is missing, invalid, or expired.
402insufficient_credits_error
Your account does not have enough credits.
404not_found_error
The requested resource does not exist.
409conflict_error
The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error
Too many requests. Slow down and retry.Retry-After: 30
500api_error
An internal server error occurred. Retry later.
try {
  await photta("/tryon/jewelry", { method: "POST", body: JSON.stringify({
    "jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
    "jewelry_type": "necklace",
    "mannequin_id": "mnk_j9k1l2",
    "background": "soft window light on dark velvet",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "user_instruction": "Make the pendant 10% smaller."
  }) });
} catch (err) {
  if (err.status === 402) console.error("insufficient_credits_error: top up before retrying");
  else if (err.status === 429) await new Promise((r) => setTimeout(r, Number(err.retryAfter ?? 30) * 1000));
  else throw err;
}

Sınırlar

  • API anahtarı başına dakikada 600 istek (Sabit pencere; limit her planda aynıdır)
  • 429 yanıtı Retry-After: 30 saniye içerir
  • Görsel başına en fazla 10 MB
  • Formatlar: JPEG, PNG, WebP
  • Plan başına eşzamanlı toplu işlem: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Yalnızca polling — API webhook göndermez.

Bir yardımcı fonksiyon neden şimdilik istemci kütüphanesinden daha iyidir?

  • Node 18+ yerel fetch ile gelir — çalışma zamanı bağımlılığı yoktur
  • Aynı yardımcı fonksiyon Next.js route handler'ları, server action'ları ve herhangi bir worker içinde çalışır
  • API anahtarını env içinde tutun; yardımcı fonksiyonu asla bir 'use client' modülünden import etmeyin, aksi takdirde paketleyici bunu sızdırır
  • Herhangi bir kuyruk veya cron ile çalışır: BullMQ, Inngest, Trigger.dev, Vercel Cron, Cloudflare Queues

Neleri yapmaz

  • Henüz resmi bir @photta/node paketi yok — şu an için tek yol REST
  • Tamamlanma sinyali yalnızca polling iledir; API webhook göndermez
  • Yalnızca Bearer anahtarı; OAuth client-credentials akışı yoktur

Geliştiricilerin sıkça sorduğu sorular

Resmi bir Photta Node.js SDK'sı var mı?

Henüz yok. Belgelenen yöntem, Node'un yerel fetch'i üzerinden doğrudan REST'tir — bu sayfadaki yardımcı fonksiyon tüm entegrasyon yüzeyini oluşturur ve her yetenek için aynı şekilde çalışır.

Hangi Node.js sürümleri destekleniyor?

Yerel `fetch` destekleyen her sürüm — yani Node 18 ve sonrası. Node 16'da ya `node-fetch` ile polyfill uygularsınız ya da sürüm yükseltirsiniz. Kodun geri kalanı yalın ECMAScript 2020'dir (async/await, template literal'lar, dinamik import'lar), bu nedenle başka bir çalışma zamanı gereksinimi yoktur.

Node üzerinden kimlik doğrulamasını nasıl yaparım?

Her istekte `Authorization: Bearer photta_live_xxx` gönderin. Anahtarı bir ortam değişkenine koyun ve `process.env` aracılığıyla yükleyin; tarayıcıda çalışan bir dosyadan asla import etmeyin.

Oluşturma penceresini nasıl yönetirim?

Oluşturma endpoint'i tamamen asenkrondur. POST işlemi anında `status: 'processing'` ile bir oluşturma kimliği döndürür. `status` değeri `completed` veya `failed` durumuna geçene kadar her 3–5 saniyede bir `GET /api/v1/tryon/jewelry/{id}` adresini poll edin ve takılan bir işin isteği askıda bırakmaması için deneme sayısını sınırlandırın.

API'yi Next.js içinde çağırabilir miyim?

Evet — bir route handler (`app/**/route.ts`), bir server action (`'use server'`) veya middleware içinden çağırabilirsiniz. API anahtarını sunucuda tutun; yardımcı fonksiyonu asla bir `'use client'` dosyasından import etmeyin. Vercel'in fonksiyon zaman aşımını aşan uzun süreli işler için polling işlemini bir kuyruğa (Inngest, Trigger.dev, BullMQ) devredin ve oluşturma kimliğini tarayıcıya döndürerek kendi durum endpoint'inizi poll etmesini sağlayın.

API hataları nasıl bildirir?

2xx dışındaki yanıtlar bir `error` nesnesi içeren JSON gövdesi taşır: `type`, `code`, `message` ve destek için bir istek kimliği. Yaygın durumlar: Hatalı alana işaret eden `param` ile 400 invalid_request_error; `required` ve `available` sayılarıyla 402 insufficient_credits; saniye cinsinden `retry_after` ve eşleşen bir Retry-After başlığı ile 429 rate_limit_exceeded. 5xx hatalarını üstel geri çekilme (exponential backoff) ile yeniden denemek güvenlidir.

İlgili sayfalar

Bu sayfadaki her veri şuradan alınmıştır: Photta API dokümantasyonu · kontrol edildi

API'yi beş dakikada deneyin

Bir Photta API key oluşturun, yukarıdaki cURL kod parçacığını yapıştırın; kahveniz demlenmeden önce model üzerindeki ilk görselinizi alın.

  • 1.5–4 min
  • 2K'da 5 credits · 4K'da 6 credits
  • asenkron, polling
  • 600 istek/dk
  • Bearer anahtarı