Szybki start

Pierwszy obraz z Photta w mniej niż pięć minut.

W jednym zdaniu

Zarejestruj się na ai.photta.app, kliknij Generate API key, wyeksportuj go jako PHOTTA_API_KEY, wyślij POST do /api/v1/tryon/apparel i odpytuj zwrócony ID generowania co 3 sekundy, aż status zmieni się na completed — zazwyczaj w ciągu od 1.5 do 4 minut.

Pobierz klucz APIPrzeczytaj dokumentację
  • Uwierzytelnianie: Klucz Bearer
  • Przetwarzanie: asynchroniczne, polling
  • Limity: 600 requests/min

Każda liczba na tej stronie pochodzi z dokumentacji API Photta · sprawdzono 

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

Jak to działa

Pięć poleceń od zera do pierwszego obrazu

Wklejaj je kolejno do terminala. Każdy fragment kodu jest samowystarczalny i korzysta wyłącznie z curl + jq.

  1. Krok 1

    Wygeneruj klucz API

    Zarejestruj się na ai.photta.app i otwórz panel Developers. Kliknij Generate API key — aktywne klucze produkcyjne zaczynają się od photta_live_. Wyeksportuj go, aby reszta przewodnika mogła go odczytać z powłoki.

    # https://ai.photta.app → Developers → Generate API key
export PHOTTA_API_KEY="photta_live_xxxxx"
export PHOTTA_BASE_URL="https://api.photta.app/api/v1"

  2. Krok 2

    Wyślij swój pierwszy POST try-on

    Wyślij żądanie do /api/v1/tryon/apparel z adresem URL zdjęcia produktu i mannequin ID. API natychmiast odpowiada 202 Accepted i zwraca ID generowania w data.id.

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

  3. Krok 3

    Odpytuj aż do ukończenia

    Wysyłaj GET /api/v1/tryon/apparel/:id co 3 sekundy. Typowy czas realizacji to 1.5–4 minut. Ustaw górny limit prób, aby zablokowane zadanie nie zawiesiło Twojego skryptu w nieskończoność.

    # $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'

  4. Krok 4

    Zapisz wynik w trwałym magazynie

    Gdy status zmieni się na completed, data.output_url zawiera wyrenderowany obraz. Pobierz bajty do własnego magazynu danych, aby Twój produkt nie był zależny od CDN Photta przy renderowaniu.

    OUTPUT_URL=$(echo "$RESULT" | jq -r '.data.output_url')
curl -sO "$OUTPUT_URL"
echo "Saved $(basename "$OUTPUT_URL")"

  5. Krok 5

    Obsługuj stany błędów bez kompromisów

    Rozgałęziaj logikę na podstawie kodu statusu HTTP: 402 w przypadku niewystarczającej liczby credits, 429 dla rate limitów (respektuj Retry-After), 5xx dla przejściowych błędów serwera. Każde ciało błędu zawiera czytelny maszynowo error.code, na podstawie którego możesz podjąć akcję.

    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

Pytania zadawane przez programistów

Pytania dotyczące rozpoczęcia pracy

Ile czasu zajmuje quickstart?

Pięć minut na rejestrację + wygenerowanie klucza + pierwsze wywołanie cURL. Samo generowanie trwa od 1.5 do 4 minut, więc zaplanuj dziesięć minut czasu rzeczywistego, zanim zobaczysz swój pierwszy obraz na modelu.

Czy potrzebuję karty kredytowej, aby to przetestować?

Nowe konta otrzymują testowe credits, które możesz wykorzystać przed dokonaniem płatności. Gdy będziesz gotowy do wdrożenia na produkcję, wykup subskrypcję planu, aby zyskać większą miesięczną pulę credits i wyższe rate limity.

Który endpoint powinienem wypróbować jako pierwszy?

Apparel try-on (/api/v1/tryon/apparel) — jest najczęściej używany, ma najbardziej kompletną dokumentację i implementuje wzorzec asynchroniczny + polling, który powiela każdy inny endpoint Photta. Gdy go opanujesz, jewelry i ghost mannequin działają dokładnie tak samo.

Czy mogę wywoływać API bezpośrednio z przeglądarki?

Nie. Twój klucz API musi pozostać po stronie serwera — wysłanie go do przeglądarki ujawnia go każdemu użytkownikowi. Kieruj żądania przez lekki backend proxy (Next.js route handler, Express, Flask, Lambda) i pozwól przeglądarce komunikować się z Twoim proxy.

Powiązane strony

Każda liczba na tej stronie pochodzi z dokumentacji API Photta · sprawdzono

Dzieli Cię pięć minut od Twojego pierwszego obrazu

Pobierz klucz APIPoznaj API
  • Klucz Bearer
  • asynchroniczne, polling
  • 600 requests/min