Funkcja · Odzież

API wirtualnego try-on dla odzieży

W jednym zdaniu

API wirtualnego try-on od Photta przyjmuje zdjęcie odzieży typu flat-lay oraz ID manekina i zwraca zdjęcie na modelu w jakości 2K lub 4K. Wyślij zadanie przez POST, odpytuj co 3–5 sekund, pobierz wynik, gdy status to completed.

  • 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",
  "background_color": "#F5F0E8",
  "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')
A garment rendered on an AI model by the apparel try-on API
Przykładowy wynik

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 · 2:3 · 3:2 · 4:5 · 5:4 · 9:16 · 16:9 · 21:9
Limity wejściowe
Do 10 MB na obraz; JPEG, PNG, WebP
Idempotentne
Nie

Żądanie i odpowiedź

Żądanie

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",
  "background_color": "#F5F0E8",
  "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')

202 Accepted / Completed

{
  "data": {
    "id": "try_abc123",
    "status": "processing",
    "product_type": "top",
    "mannequin_id": "mnk_f3a9b1",
    "background_color": "#F5F0E8",
    "lock_background": false,
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 5,
    "created_at": "2026-04-10T12:00:00Z"
  },
  "request_id": "req_xyz789"
}

Parametry żądania

product_type

Typ: stringWymagane

Type of garment.

Wartości: topbottomtop_and_bottomone_piece
product_images

Typ: array[string]Wymagane

Array of image URLs or base64 data URIs. The first entry is the FRONT image and is required. Not used when product_type is "top_and_bottom".

product_back_image

Typ: string

Optional URL or base64 data URI for the BACK of the garment. Sending one IS the request for a back shot: the model is photographed from behind and this image is the reference. Omit it and you get the front. There is deliberately no separate "view" field — two fields that can contradict each other. Not used when product_type is "top_and_bottom".

top_image

Typ: string

Front image of the top garment. Required when product_type is "top_and_bottom".

top_back_image

Typ: string

Optional back image of the top garment. Sending one asks for a back shot, exactly as product_back_image does.

bottom_image

Typ: string

Front image of the bottom garment. Required when product_type is "top_and_bottom".

bottom_back_image

Typ: string

Optional back image of the bottom garment. Sending one asks for a back shot, exactly as product_back_image does.

mannequin_id

Typ: stringWymagane

ID of the mannequin to wear the garment. Use GET /api/v1/mannequins to list available options.

background_color

Typ: string

The backdrop, as a colour. One of white, light_gray, gray, charcoal, black, beige, cream, sand — or any hex value (#F5F0E8, F5F0E8, #fff). It travels to the engine as TEXT; nothing is uploaded, and the same value reproduces exactly on every run. Omit it for the engine's clean studio default. An unrecognised value returns 400 rather than quietly falling back. Echoed back on the response.

Wartości: whitelight_graygraycharcoalblackbeigecreamsand
pose_id

Typ: string

RETIRED 2026-08-10 — accepted and ignored. Poses were removed from apparel try-on; every generation is now a straight, relaxed, camera-facing full-body shot (the old FullBody stance). Sending it returns Deprecation and Sunset headers. Deleted 2027-02-10 — stop sending it.

background

Typ: string

RETIRED 2026-08-11 — accepted and ignored, never downloaded. Backdrop photographs were removed: recreating a room competed with the garment for the engine's attention. Use background_color instead. Sending it returns Deprecation and Sunset headers. Deleted 2027-02-10.

lock_background

Typ: boolean

RETIRED 2026-08-11 — accepted and ignored, and always false on responses. It never worked as previously documented: the prompt engine has always discarded the flag, so the "faithful reproduction" this page used to promise was never delivered. background_color is the first backdrop control that actually holds still. Deleted 2027-02-10.

= false

resolution

Typ: string

Output resolution.

= 2K

Wartości: 2K4K
aspect_ratio

Typ: string

Output aspect ratio.

= 3:4

Wartości: 3:41:14:32:33:24:55:49:1616:921:9
body_size

Typ: string

Body size of the mannequin.

= M

Wartości: XSSMLXLXXL
expression

Typ: string

Facial expression.

= neutral

Wartości: neutralhappyserioussmiling
footwear_url

Typ: string

URL or base64 of a custom footwear image. Every generation is a full-body shot, so supplied footwear is staged and worn.

user_instruction

Typ: string

Free-form refinement, e.g. "preserve the seam pattern across the shoulder", "keep the collar contrast strong". Capped at 500 characters server-side; longer strings are silently truncated. Useful for brand-specific details that need an extra nudge.

product_category

Typ: string

Optional silhouette anchor for the garment (e.g. "t_shirt", "jeans", "blazer", "midi_dress"). Helps disambiguate the structure of the garment when the silhouette is ambiguous from the photo alone. Used for product_type "top", "bottom", and "one_piece".

top_category

Typ: string

Silhouette anchor for the top half. Only valid when product_type is "top_and_bottom".

bottom_category

Typ: string

Silhouette anchor for the bottom half. Only valid when product_type is "top_and_bottom".

length

Typ: string

Garment length key for product_type "top", "bottom", or "one_piece". List available values with GET /api/v1/garment-attributes?type=length&garment_type={product_type}.

fit

Typ: string

Garment fit key for product_type "top", "bottom", or "one_piece". List available values with GET /api/v1/garment-attributes?type=fit&garment_type={product_type}.

top_length

Typ: string

Top length key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=length&garment_type=top.

top_fit

Typ: string

Top fit key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=fit&garment_type=top.

bottom_length

Typ: string

Bottom length key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=length&garment_type=bottom.

bottom_fit

Typ: string

Bottom fit key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=fit&garment_type=bottom.

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 (500), or a check your request needs could not run right now (503, e.g. moderation_unavailable). Retry later with backoff.

Limity

  • 600 żądań na minutę na konto (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.

Pięć kroków, jedno zdjęcie produktu

Wybierz manekina, prześlij zadanie, odpytuj do zakończenia, pobierz wynik.

  1. Krok 1

    Wygeneruj klucz API

    Zarejestruj się na ai.photta.app, otwórz zakładkę Developers, kliknij Generate API key. Klucze produkcyjne zaczynają się od `photta_live_`. Umieść klucz w `PHOTTA_API_KEY` — nigdy go nie commituj.

  2. Krok 2

    Wybierz manekina

    Wykonaj GET `/api/v1/mannequins`, aby wyświetlić listę dostępnych modeli i wybrać żądany identyfikator. Pozy zostały wycofane w dniu 2026-08-10: każde ujęcie przedstawia całą sylwetkę na wprost aparatu, więc nie ma nic więcej do wyboru.

  3. Krok 3

    Wyślij zadanie try-on metodą POST

    Wyślij żądanie POST do `/api/v1/tryon/apparel` z polami `product_type`, `product_images`, `mannequin_id` oraz opcjonalnymi `resolution` i `aspect_ratio`. API zwraca 202 Accepted wraz z identyfikatorem generowania.

  4. Krok 4

    Odpytuj, aż zadanie zostanie ukończone

    Wykonuj GET `/api/v1/tryon/apparel/:id` co 3 sekundy. Gdy `data.status` zmieni się na `completed`, payload zawiera `output_url` i `thumbnail_url`. Ustaw górny limit, aby zawieszone zadanie nie blokowało Twojego żądania.

  5. Krok 5

    Pobierz i utrwal

    Pobierz bajty z `output_url` i zapisz je we własnym magazynie obiektowym (object storage). Adres URL z CDN jest stabilny, ale Twój produkt nie powinien od niego zależeć przy renderowaniu.

Pytania, które programiści zadają przed wdrożeniem try-on dla odzieży

Czym jest API wirtualnego try-on od Photta?

To endpoint REST, który przyjmuje zdjęcie produktu typu flat-lay oraz identyfikator manekina i zwraca fotorealistyczne zdjęcie na modelu. Ten sam potok, co w aplikacji konsumenckiej Photta. Obsługiwane są cztery typy produktów: top, bottom, top+bottom, one-piece.

Ile to kosztuje za wywołanie?

5 credits za wynik w 2K, 6 credits za 4K. Kredyty są dołączone do Twojej subskrypcji i można je doładowywać. Nieudane generowania nie kosztują credits — są zwracane.

Ile trwa generowanie?

Typowy czas realizacji to od 1.5 do 4 minut, mierzony end-to-end. POST zwraca identyfikator generowania w mniej niż sekundę; przetwarzanie na GPU odbywa się w tle podczas odpytywania.

Jakie typy produktów są obsługiwane?

Cztery: `top`, `bottom`, `top_and_bottom`, `one_piece`. Każdy z nich oczekuje innej struktury `product_images` — na przykład `top_and_bottom` wymaga adresów URL zarówno dla `top_image`, jak i `bottom_image`.

Czy mogę użyć własnego manekina?

Tak. Prześlij zdjęcie manekina za pomocą `POST /api/v1/mannequins` lub wygeneruj nowego manekina AI za pomocą `POST /api/v1/mannequins/generate`. Zwrócony identyfikator podłącza się bezpośrednio do żądania try-on.

Jak odpytywać o wynik?

Wykonuj GET `/api/v1/tryon/apparel/:id` co 3 do 5 sekund, aż `data.status` przyjmie wartość `completed` lub `failed`. Ustaw górny limit prób — 120 × 3s z zapasem pokrywa udokumentowane okno czasowe.

Powiązane możliwości

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