Python · Sanal try-on API'si

Sanal try-on API'si Python ile

Tek cümlede

requests kütüphanesini kurun, PHOTTA_API_KEY değerini env üzerinden yükleyin, Bearer anahtarını gönderen ve 2xx dışı yanıtlarda tiplenmiş bir PhottaError fırlatan bir photta() sarmalayıcısı yazın, ardından /api/v1/tryon/apparel adresine POST isteği atın ve durum completed olana kadar her 3 saniyede bir /api/v1/tryon/apparel/{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/apparel
import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/tryon/apparel",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "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."
    },
)
data = res.json()["data"]  # data["id"], data["status"]

import time

def wait_for(job_id):
    for _ in range(120):
        res = requests.get(f"https://api.photta.app/api/v1/tryon/apparel/{job_id}", headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"})
        data = res.json()["data"]
        if data["status"] == "completed":
            return data["output_url"]
        if data["status"] == "failed":
            raise RuntimeError(data.get("error_message", "generation failed"))
        time.sleep(3)
    raise TimeoutError("timed out after 6 minutes")

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

Beş adım, sıfır Photta'ya özel bağımlılık — requests her şeyi kapsar.

  1. Adım 1

    Kaydolun ve bir anahtar oluşturun

    Diğer tüm dillerle aynı yol: ai.photta.app → Developers → Generate API key. Anahtarlar `photta_live_` ile başlar ve tüm Photta yeteneklerinde çalışır.

  2. Adım 2

    Anahtarı env üzerinden yükleyin

    `PHOTTA_API_KEY` değişkenini ortamda tanımlayın ve `os.environ` üzerinden okuyun. FastAPI veya Django'da, açılış sırasında bunu bir settings modülüne bir kez yükleyin. Anahtarı kaynak koduna veya herkese açık Git geçmişine eklemeyin.

    python3 -m pip install requests
    export PHOTTA_API_KEY="photta_live_xxxxx"
  3. Adım 3

    Bir requests sarmalayıcısı yazın

    Otuz satırlık bir `photta_request()` fonksiyonu temel URL'yi, Authorization başlığını, JSON serileştirmesini ve hata çevrimini halleder. Python SDK çıkana kadar ihtiyacınız olan tek soyutlama budur.

    # photta.py — one helper for every endpoint
    import os, requests
    BASE = "https://api.photta.app/api/v1"
    
    class PhottaError(Exception):
        def __init__(self, status, error, retry_after=None):
            super().__init__(error.get("message", "request failed"))
            self.status, self.type, self.retry_after = status, error.get("type"), retry_after
    
    def photta(method, path, **kwargs):
        res = requests.request(method, BASE + path, headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"}, timeout=30, **kwargs)
        body = res.json()
        if not res.ok:
            raise PhottaError(res.status_code, body.get("error", {}), res.headers.get("Retry-After"))
        return body
  4. Adım 4

    Gönder ve yokla (poll)

    Bir üretim ID'si almak için `/api/v1/tryon/apparel` adresine POST isteği atın, ardından 3 saniyelik aralıklarla `/api/v1/tryon/apparel/{id}` adresini yoklayın. Celery veya RQ kullanırken, dakikalar süren bir işin bir worker'ı meşgul etmemesi için yoklama döngüsünü görevler (tasks) arasına bölün.

    import os, requests
    
    res = requests.post(
        "https://api.photta.app/api/v1/tryon/apparel",
        headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
        json={
          "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."
        },
    )
    data = res.json()["data"]  # data["id"], data["status"]
    
    import time
    
    def wait_for(job_id):
        for _ in range(120):
            res = requests.get(f"https://api.photta.app/api/v1/tryon/apparel/{job_id}", headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"})
            data = res.json()["data"]
            if data["status"] == "completed":
                return data["output_url"]
            if data["status"] == "failed":
                raise RuntimeError(data.get("error_message", "generation failed"))
            time.sleep(3)
        raise TimeoutError("timed out after 6 minutes")
  5. Adım 5

    Sonucu kalıcı hale getirin

    Tamamlanan payload, `output_url` ve `thumbnail_url` içerir. Ürününüzün uzun vadeli görsel sunumu için Photta'nın CDN'ine bağımlı kalmaması adına baytları kendi nesne depolama alanınıza (S3, GCS, Cloudflare R2) indirin.

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:
    photta("POST", "/tryon/apparel", json={
      "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."
    })
except PhottaError as e:
    if e.status == 402:
        print("insufficient_credits_error: top up before retrying")
    elif e.status == 429:
        time.sleep(int(e.retry_after or 30))
    else:
        raise

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.

Bugün requests neden doğru seçim?

  • Photta'ya özel bir bağımlılık yok — requests çoğu Python projesinde zaten mevcuttur
  • Python'ın çalıştığı her yerde çalışır: Django, FastAPI, Flask, Celery worker'ları, Lambda, betikler
  • İstemci sarmalayıcısı (wrapper) yaklaşık otuz satırdır — photta.py içine yapıştırıp devam edin
  • Paralel gönderim gerektiğinde httpx aracılığıyla asyncio ile uyum sağlar

Neleri yapmaz?

  • Henüz resmi bir Photta Python paketi yok — requests ile REST, belgelenmiş standart yaklaşımdır
  • Tamamlanma sinyali yalnızca yoklama (polling) iledir; API webhook göndermez
  • Yalnızca Bearer anahtarı desteklenir; OAuth client-credentials akışı yoktur

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

Resmi bir Photta Python SDK'sı var mı?

Henüz yok. Desteklenen entegrasyon yolu requests kütüphanesi (senkron) veya httpx'tir (asenkron) — her ikisi de ince bir sarmalayıcı uzaklığındadır ve bu sayfadaki sarmalayıcı her yetenek için çalışır.

Hangi Python sürümleri destekleniyor?

Python 3.9 ve sonrası. Sarmalayıcı tip ipuçları, f-string'ler ve 3.10+ üzerinde sorunsuz çalışan `str | None` sözdizimini kullanır. 3.9 üzerinde `str | None` yerine `Optional[str]` kullanın. requests kütüphanesinin kendisi resmi olarak 3.8+ sürümlerini destekler, ancak modern Photta projeleri için pratik minimum sürüm 3.9+'dır.

requests mi yoksa httpx mi kullanmalıyım?

Birkaç sıralı çağrı yapıyorsanız requests — daha basittir ve çoğu kod tabanında zaten vardır. Asenkron eşzamanlılığa (paralel gönderimler, toplu doldurmalar) veya HTTP/2'ye ihtiyacınız varsa httpx. Sarmalayıcı her iki durumda da oldukça küçüktür; `requests.request` yerine `httpx.Client().request` koyun, kodun geri kalanı tamamen aynı kalır.

Django içinden çağırabilir miyim?

Evet. Sarmalayıcıyı `services/photta.py` içine yerleştirin, bir view veya Celery görevinden import edin. İş uzun sürüyorsa API'yi senkron bir istek işleyicisi (request handler) içinde çağırmayın — view içinden gönderin, üretim ID'sini döndürün ve bir arka plan görevinden ya da Channels tüketicisinden yoklayın.

Bir Celery worker'ından nasıl yoklama (poll) yaparım?

İşi bir görevden gönderin, ardından iş tamamlanana veya maksimum yeniden deneme eşiğine ulaşılana kadar bir kez yoklayan ve kendini yeniden planlayan bir takip görevi (`apply_async(countdown=3)` aracılığıyla) planlayın. Bu, worker'ları serbest tutar ve otomatik ölçekleyicileri bozan uzun süreli görevlerin önüne geçer.

API hataları nasıl bildirir?

2xx dışındaki yanıtlar bir `error` nesnesi içeren JSON gövdesi taşır: `type`, `code`, `message`, ayrıca 400 yanıtlarında `param` ve 429 yanıtlarında `retry_after`. Bu sayfadaki sarmalayıcı, çağıranlarınızın gövdeyi kendileri ayrıştırmasına gerek kalmadan durum koduna göre dallanabilmesi için bunların tümünü taşıyan bir `PhottaError` fırlatır.

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