cURL · Sanal try-on API'si

Sanal try-on API'si cURL ile

Tek cümlede

PHOTTA_API_KEY değişkenini dışa aktarın, belgelenen JSON gövdesiyle https://api.photta.app/api/v1/api/v1/tryon/apparel adresine POST isteği atın, üretim ID'sini yakalayın, ardından data.status değeri completed olana kadar her 3 saniyede bir /api/v1/tryon/apparel/{id} üzerinde bir GET döngüsü çalıştırın. Çıktı URL'sini ayıklamak için jq ile birleştirin.

  • 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/apparel
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')

# $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed".
for i in $(seq 1 120); do
  RESULT=$(curl -s "https://api.photta.app/api/v1/tryon/apparel/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && echo "generation failed" && exit 1
  sleep 3
done
echo "$RESULT" | jq -r '.data.output_url'

Genel bakış

Genel bakış

Endpoint
POST /api/v1/tryon/apparel
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

curl ve jq haricinde sıfır bağımlılıkla beş kabuk adımı.

  1. Adım 1

    Kaydolun ve bir anahtar oluşturun

    ai.photta.app adresine gidin, Geliştiriciler sekmesini açın, API anahtarı oluştur'a tıklayın. Canlı anahtarlar `photta_live_` ile başlar.

  2. Adım 2

    Anahtarı dışa aktarın

    Sonraki tüm curl çağrılarının bunu otomatik olarak alması için kabuk profilinize veya bir `.envrc` dosyasına `export PHOTTA_API_KEY="photta_live_xxx"` satırını ekleyin.

    curl --version   # macOS, Linux, WSL and Windows 10+ ship it
    export PHOTTA_API_KEY="photta_live_xxxxx"
  3. Adım 3

    Temel URL'yi sabitleyin

    `export PHOTTA_BASE_URL="https://api.photta.app/api/v1"` komutu curl komutlarını kısa tutar.

    export PHOTTA_BASE_URL="https://api.photta.app/api/v1"
    export AUTH_HEADER="Authorization: Bearer $PHOTTA_API_KEY"
  4. Adım 4

    Gönder ve yokla

    Bir ID almak için `$PHOTTA_BASE_URL/api/v1/tryon/apparel` adresine POST isteği atın, ardından her 3 saniyede bir `curl $PHOTTA_BASE_URL/api/v1/tryon/apparel/{id}` döngüsü çalıştırın. `.data.status` değerini temiz bir şekilde ayıklamak için yanıtı jq'ya aktarın.

    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')
    
    # $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed".
    for i in $(seq 1 120); do
      RESULT=$(curl -s "https://api.photta.app/api/v1/tryon/apparel/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY")
      STATUS=$(echo "$RESULT" | jq -r '.data.status')
      [ "$STATUS" = "completed" ] && break
      [ "$STATUS" = "failed" ] && echo "generation failed" && exit 1
      sleep 3
    done
    echo "$RESULT" | jq -r '.data.output_url'
  5. Adım 5

    Sonucu kalıcı hale getir

    İş tamamlandığında, `.data.output_url` değerini jq ile çekin ve baytları yerel depolama alanına aktarmak için `curl -o` kullanın — bir sonraki pipeline adımınız için hazı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.
case "$STATUS_CODE" in
  402) echo "insufficient_credits_error — top up before retrying" ;;
  429) echo "rate_limit_error — wait the Retry-After seconds (30 by default)" ;;
  4??) echo "$BODY" | jq '.error.type, .error.message' ;;
  5??) echo "api_error — retry with backoff" ;;
esac

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.

cURL neden hâlâ bir API'yi doğrulamanın en hızlı yoludur

  • Sıfır kurulum — cURL tüm büyük işletim sistemleriyle birlikte gelir
  • Komut dosyalı pipeline'lar için jq ile mükemmel uyum sağlar (CI, cron, kabuk kancaları)
  • Bir endpoint'i koda bağlamadan önce duman testine (smoke test) tabi tutmanın en hızlı yolu
  • Bu sayfadaki her komut herhangi bir POSIX kabuğuna doğrudan yapıştırılabilir

Neleri yapmaz

  • Yoklama döngüsü terminali bloke eder — paralel çalışanlar için Node veya Python'a geçin
  • Yoklama (polling) tek tamamlanma sinyalidir; API webhook göndermez
  • Windows Komut İstemi kullanıcıları WSL veya PowerShell'in curl.exe aracını çalıştırmalıdır

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

Photta için bir CLI aracı var mı?

Henüz yok — ancak cURL ve on beş satırlık bir bash sarmalayıcısı (wrapper) işinizi büyük ölçüde görür. Dokümanlar cURL öncelikli örneklere odaklanır; çünkü her dil bir alt süreç (subprocess) çalıştırabilir ve kabuk, CI pipeline'larında ortak paydadır.

API'yi kullanmak için jq'ya ihtiyacım var mı?

Kesinlikle şart değil — ancak komut dosyalı pipeline'lar bununla çok daha kolaydır. jq, JSON yanıtını elle ayrıştırmanıza gerek kalmadan içinden `.data.id`, `.data.status` ve `.data.output_url` alanlarını çekmenizi sağlar. macOS'te `brew install jq` veya Debian/Ubuntu'da `apt install jq` ile kurabilirsiniz.

curl ile kimlik doğrulamasını nasıl yaparım?

Her isteğe `-H "Authorization: Bearer $PHOTTA_API_KEY"` ekleyin. Anahtarı bir ortam değişkeninde tutun, commit ettiğiniz bir betiğin içine asla doğrudan yazmayın. `curl --oauth2-bearer` da çalışır ancak açık başlık (header) biçimi dokümanlarda ve loglarda daha nettir.

curl tabanlı betikleri prodüksiyonda kullanabilir miyim?

Tek seferlik toplu doldurmalar (batch backfills) ve cron işleri için evet — binlerce ekip katalog güncellemelerini bu şekilde dağıtıyor. Uzun ömürlü bir uygulama için gerçek bir dil genellikle daha iyidir; çünkü düzgün hata yönetimi, yeniden denemeler ve gözlemlenebilirlik elde edersiniz. Bu sayfadaki curl örnekleri, Node veya Python'a geçtikten sonra bile geçerliliğini korur; istek yapısı aynıdır.

Bir bash döngüsüyle nasıl yoklama (poll) yapabilirim?

Döngü gövdesinde durum kontrolü olacak şekilde `for i in $(seq 1 120); do … ; sleep 3; done` kullanın. `.data.status` değeri `completed` veya `failed` olduğunda döngüden çıkın. Bu sayfadaki kod örneği, takılan bir işin betiği sonsuza kadar askıda tutmasını önleyen kesin bir üst sınır da dahil olmak üzere tam deseni gösterir.

curl'de hata yanıtlarını nasıl okurum?

JSON gövdesinin yanında HTTP durum kodunu da yakalamak için `curl -w "\n%{http_code}"` kullanın. Duruma göre dallara ayırın: Yetersiz credits için 402, rate limit için 429 (Retry-After değerini dikkate alın), geçici sunucu hataları için 5xx. Hata gövdesinde her zaman bir `error.code` ve `error.message` alanı bulunur.

İ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ı