Kyvykkyys · Yksityiskohtakuvat

Tuotteen yksityiskohtakuva-API lähikuville

Yhdellä lauseella

Phottan yksityiskohtakuva-API renderöi lähikuvan yhdestä tuotteen nimetystä alueesta. Ilmainen analyze-kutsu ehdottaa kuvaamisen arvoisia yksityiskohtia; generate-kutsu maksaa kiinteästi 3 credits ilman resoluutiotasoja.

  • Tyypillinen kesto: 20–60 sec
  • Credits: 3 credits
  • Käsittely: asynkroninen, polling
  • Rajoitukset: 600 pyyntöä/min
  • Autentikointi: Bearer-avain

Jokainen luku tällä sivulla on peräisin Photta-rajapinnan dokumentaatiosta · tarkistettu

POST/api/v1/detail-photos
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
  "detail_label": "collar stitching",
  "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
  "framing": "extreme-closeup",
  "source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

Lyhyesti

Lyhyesti

Endpoint
POST /api/v1/detail-photos
Autentikointi
Bearer-API-avain
Käsittely
Asynkroninen — tee polling-kyselyitä status-endpointiin
Tyypillinen kesto
20–60 sec
Credits
3 credits
Syöterajoitukset
Enintään 10 MB per kuva; JPEG, PNG, WebP
Idempotentti
Ei

Pyyntö ja vastaus

Pyyntö

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
  "detail_label": "collar stitching",
  "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
  "framing": "extreme-closeup",
  "source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / Completed

{
  "data": {
    "id": "dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10",
    "status": "processing",
    "detail_label": "collar stitching",
    "framing": "extreme-closeup",
    "credits_used": 3,
    "created_at": "2026-07-30T14:20:00Z"
  },
  "request_id": "req_dtl001"
}

Pyyntöparametrit

product_image

Tyyppi: stringPakollinen

The source image — a completed generation's output_url or any product photo. https URL or base64 data URI. JPEG, PNG, WebP; max 10 MB.

detail_label

Tyyppi: stringPakollinen

The area to zoom into, e.g. "collar stitching", "cuff detail", "fabric weave on the chest", "pendant clasp". Max 100 characters.

detail_description

Tyyppi: string

Extra guidance for the close-up. Max 400 characters.

framing

Tyyppi: string

How tight the crop is: "extreme-closeup" — the detail fills ~90% of the frame (near-macro); "closeup" — ~70% with some surrounding context; "medium-closeup" — ~50% with body/outfit visible.

= medium-closeup

Arvot: extreme-closeupcloseupmedium-closeup
source_type

Tyyppi: string

Tunes what is preserved in the close-up.

= apparel

Arvot: appareljewelry

Virheet

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.

Rajoitukset

  • 600 pyyntöä minuutissa per API-avain (Kiinteä aikaikkuna; rajoitus on sama kaikissa tilauksissa)
  • Vastaus 429 sisältää otsakkeen Retry-After: 30 sekuntia
  • Enintään 10 MB per kuva
  • Formaatit: JPEG, PNG, WebP
  • Rinnakkaiset eräajot per tilaus: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Vain polling — API ei lähetä webhookeja.

Kysy, mikä kannattaa kuvata, ja kuvaa se sitten

Analysoi ilmaiseksi, valitse yksityiskohta, lähetä, pollaa, lataa.

  1. Vaihe 1

    Luo API-avain

    Yksityiskohtakuvat käyttävät samoja tunnistetietoja ja samaa credit-saldoa kuin kaikki muutkin Phottan kyvykkyydet.

  2. Vaihe 2

    Kysy, mitkä yksityiskohdat kannattaa kuvata

    Tee POST `/api/v1/detail-photos/analyze` parametrilla `product_image`. Se palauttaa synkronisesti ehdotetut `detail_label`-, `detail_description`- ja `framing`-arvot kyseiselle tuotteelle eikä veloita mitään.

  3. Vaihe 3

    Tee POST lähikuvalle

    Tee POST osoitteeseen `/api/v1/detail-photos` parametreilla `product_image` ja `detail_label`. Aseta `framing`-arvoksi `extreme-closeup`, `closeup` tai `medium-closeup`, `source_type`-arvoksi `apparel` tai `jewelry`, ja lisää enintään 400 merkkiä kenttään `detail_description`.

  4. Vaihe 4

    Pollaa, kunnes työ valmistuu

    Tee GET `/api/v1/detail-photos/:id` 3 sekunnin välein, kunnes `data.status` on `completed` tai `failed`; tyypillinen valmistumisaika on 20–60 sekuntia.

  5. Vaihe 5

    Lataa ja tallenna

    Valmis vastausrunko sisältää arvon `output_url`. Yksityiskohtakuvat sopivat suoraan PDP-galleriaan pääkuvan viereen.

Kysymyksiä, joita kehittäjät kysyvät ennen yksityiskohtakuvien julkaisua tuotantoon

Mikä on yksityiskohtakuva-API?

Endpoint, joka renderöi lähikuvan yhdestä tuotteen nimetystä alueesta — kauluksen tikkauksesta, lukosta, rinnan kudoksesta — yhdestä laajemmasta valokuvasta sen sijaan, että tarvittaisiin toinen studiosessio makro-objektiivilla.

Paljonko yksityiskohtakuva maksaa?

Kiinteät 3 credits. Tässä endpointissa ei ole resoluutiotasoja, ja yksityiskohtia ehdottava analyze-kutsu on ilmainen.

Mitä analyze-endpoint palauttaa?

Listan ehdotuksia, joista jokainen sisältää kentät `detail_label`, `detail_description` (joka selittää, miksi alue kannattaa näyttää) sekä suositellun `framing`-arvon. Voit syöttää minkä tahansa ehdotuksen suoraan generate-kutsuun.

Kuinka tiukka kukin rajausvaihtoehto on?

`extreme-closeup` täyttää lähes koko kuva-alan yksityiskohdalla, `closeup` jättää sen ympärille hieman kontekstia ja `medium-closeup` näyttää yksityiskohdan ympäröivässä vaatteessa tai tuotteessa. Valitse yksityiskohdan, älä tuotteen mukaan.

Voiko lähdekuva olla tekoälyllä luotu kuva?

Kyllä. `product_image` hyväksyy valmistuneen generoinnin `output_url`-arvon sekä minkä tahansa oman tuotekuvasi joko https-URL-osoitteena tai base64 data URI -muodossa.

Miten kyselen tulosta polling-menetelmällä?

Tee GET-kutsu osoitteeseen `/api/v1/detail-photos/:id` 3 sekunnin välein, kunnes `data.status` on `completed` tai `failed`. Analyze-kutsu on synkroninen eikä vaadi pollingia.

Liittyvät kyvykkyydet

Jokainen luku tällä sivulla on peräisin Photta-rajapinnan dokumentaatiosta · tarkistettu

Kokeile APIa viidessä minuutissa

Luo Photta-API-avain, liitä yllä oleva cURL-koodinpätkä, ja sinulla on ensimmäinen mallikuva ennen kuin kahvi ehtii tippua.

  • 20–60 sec
  • 3 credits
  • asynkroninen, polling
  • 600 pyyntöä/min
  • Bearer-avain