cURL · API wirtualnego try-on

API wirtualnego try-on z użyciem cURL

W jednym zdaniu

Wyeksportuj PHOTTA_API_KEY, wyślij POST na https://api.photta.app/api/v1/api/v1/tryon/apparel z udokumentowanym body JSON, przechwyć ID generowania, a następnie odpytuj w pętli GET na /api/v1/tryon/apparel/{id} co 3 sekundy, dopóki data.status nie przyjmie wartości completed. Połącz z jq, aby wyodrębnić docelowy URL.

  • Typowy czas: 1.5–4 min
  • Credits: 5 credits w 2K · 6 credits w 4K
  • Przetwarzanie: asynchroniczne, polling
  • Limity: 600 requests/min
  • Uwierzytelnianie: Klucz Bearer

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

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'

W skrócie

W skrócie

Endpoint
POST /api/v1/tryon/apparel
Uwierzytelnianie
Klucz API Bearer
Przetwarzanie
Asynchroniczne — odpytuj endpoint statusu
Typowy czas
1.5–4 min
Credits
5 credits w 2K · 6 credits w 4K
Proporcje obrazu
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limity wejściowe
Do 10 MB na obraz; JPEG, PNG, WebP
Idempotentne
Nie

Jak to działa

Pięć kroków w powłoce, zero zależności poza curl i jq.

  1. Krok 1

    Zarejestruj się i wygeneruj klucz

    Przejdź do ai.photta.app, otwórz zakładkę Developers i kliknij Generate API key. Klucze produkcyjne zaczynają się od `photta_live_`.

  2. Krok 2

    Wyeksportuj klucz

    Dodaj `export PHOTTA_API_KEY="photta_live_xxx"` do profilu powłoki lub pliku `.envrc`, aby każde kolejne wywołanie curl automatycznie z niego korzystało.

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

    Przypnij bazowy URL

    `export PHOTTA_BASE_URL="https://api.photta.app/api/v1"` pozwala zachować zwięzłość poleceń curl.

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

    Wyślij i odpytuj

    Wyślij POST do `$PHOTTA_BASE_URL/api/v1/tryon/apparel`, aby uzyskać ID, a następnie wykonuj w pętli `curl $PHOTTA_BASE_URL/api/v1/tryon/apparel/{id}` co 3 sekundy. Przekaż odpowiedź potokiem do jq, aby czysto wyodrębnić `.data.status`.

    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. Krok 5

    Zapisz wynik

    Gdy zadanie się zakończy, wyciągnij `.data.output_url` za pomocą jq i pobierz bajty przez `curl -o` do lokalnego magazynu — gotowe do następnego kroku w pipeline.

Błędy

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

Limity

  • 600 żądań na minutę na klucz API (Stałe okno czasowe; limit jest taki sam w każdym planie)
  • Odpowiedź 429 zawiera nagłówek Retry-After: 30 s
  • Do 10 MB na obraz
  • Formaty: JPEG, PNG, WebP
  • Jednoczesne zadania wsadowe w zależności od planu: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Tylko polling — API nie wysyła webhooków.

Dlaczego cURL to wciąż najszybszy sposób na weryfikację API

  • Zero instalacji — cURL jest dostarczany z każdym głównym systemem operacyjnym
  • Świetnie współpracuje z jq w oskryptowanych pipeline'ach (CI, cron, hooki powłoki)
  • Najszybszy sposób na smoke-test endpointu przed zaimplementowaniem go w kodzie
  • Każde polecenie na tej stronie można wkleić do dowolnej powłoki POSIX

Czego to rozwiązanie nie robi

  • Pętla pollingu blokuje terminal — przejdź na Node lub Pythona, aby zyskać równoległe procesy robocze
  • Polling jest jedynym sygnałem ukończenia; API nie wysyła webhooków
  • Użytkownicy wiersza poleceń Windows powinni uruchomić WSL lub curl.exe w PowerShellu

Pytania zadawane przez programistów

Czy istnieje narzędzie Photta CLI?

Jeszcze nie — ale cURL w połączeniu z piętnastoliniowym wrapperem bash załatwia większość sprawy. Dokumentacja stawia na przykłady oparte na cURL, ponieważ każdy język potrafi uruchomić podproces, a powłoka jest wspólnym mianownikiem w pipeline'ach CI.

Czy do korzystania z API potrzebuję jq?

Nie bezwzględnie — ale oskryptowane pipeline'y są z nim znacznie prostsze. jq pozwala wyciągnąć `.data.id`, `.data.status` i `.data.output_url` z odpowiedzi JSON bez ręcznego parsowania. Zainstaluj za pomocą `brew install jq` na macOS lub `apt install jq` na Debianie/Ubuntu.

Jak uwierzytelnić się za pomocą curl?

Dodaj `-H "Authorization: Bearer $PHOTTA_API_KEY"` do każdego żądania. Trzymaj klucz w zmiennej środowiskowej, nigdy nie umieszczaj go bezpośrednio w skrypcie, który commitujesz. `curl --oauth2-bearer` również działa, ale jawny nagłówek jest bardziej czytelny w dokumentacji i logach.

Czy mogę używać skryptów opartych na curl na produkcji?

W przypadku jednorazowych zadań wsadowych i crona — tak, tysiące zespołów aktualizuje katalogi w ten sposób. W długo działającej aplikacji prawdziwy język programowania sprawdza się zazwyczaj lepiej ze względu na poprawną obsługę błędów, ponawianie żądań i obserwowalność. Przykłady curl na tej stronie pozostają aktualne nawet po przeniesieniu do Node lub Pythona; struktura żądania jest identyczna.

Jak odpytywać API w pętli bash?

Użyj `for i in $(seq 1 120); do … ; sleep 3; done` ze sprawdzeniem statusu wewnątrz pętli. Przerwij działanie, gdy `.data.status` przyjmie wartość `completed` lub `failed`. Przykład kodu na tej stronie pokazuje dokładny wzorzec, w tym sztywny limit górny, dzięki czemu zawieszone zadanie nie zablokuje skryptu w nieskończoność.

Jak odczytywać odpowiedzi błędów w curl?

Użyj `curl -w "\n%{http_code}"`, aby przechwycić kod statusu HTTP wraz z treścią JSON. Zastosuj warunki na podstawie statusu: 402 w przypadku braku credits, 429 przy rate limitach (uwzględnij wartość Retry-After), 5xx przy przejściowych błędach serwera. Treść błędu zawsze zawiera pola `error.code` i `error.message`.

Powiązane strony

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

Wypróbuj API w 5 minut

Wygeneruj klucz Photta API, wklej powyższy snippet cURL, a otrzymasz swoje pierwsze zdjęcie na modelu, zanim zaparzy się kawa.

  • 1.5–4 min
  • 5 credits w 2K · 6 credits w 4K
  • asynchroniczne, polling
  • 600 requests/min
  • Klucz Bearer