cURL · Ghost mannequin API

Ghost mannequin API cURLilla

Yhdellä lauseella

Vie PHOTTA_API_KEY ympäristömuuttujaksi, tee POST osoitteeseen https://api.photta.app/api/v1/api/v1/ghost-mannequin dokumentoidulla JSON-rungolla, ota luontitunnus talteen ja suorita sitten GET-silmukkaa osoitteeseen /api/v1/ghost-mannequin/{id} 3 sekunnin välein, kunnes data.status on completed. Poimi tuloksen URL yhdessä jq:n kanssa.

  • Tyypillinen kesto: 1.5–4 min
  • Credits: 4 credits resoluutiolla 2K · 5 credits resoluutiolla 4K
  • 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/ghost-mannequin
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
  "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
  "image_side": "front",
  "angle": "side",
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, cream interior lining",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
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/ghost-mannequin/$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'

Lyhyesti

Lyhyesti

Endpoint
POST /api/v1/ghost-mannequin
Autentikointi
Bearer-API-avain
Käsittely
Asynkroninen — tee polling-kyselyitä status-endpointiin
Tyypillinen kesto
1.5–4 min
Credits
4 credits resoluutiolla 2K · 5 credits resoluutiolla 4K
Kuvasuhteet
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Syöterajoitukset
Enintään 10 MB per kuva; JPEG, PNG, WebP
Idempotentti
Ei

Miten se toimii

Viisi komentorivivaihetta, nolla riippuvuutta curlin ja jq:n lisäksi.

  1. Vaihe 1

    Rekisteröidy ja luo avain

    Siirry osoitteeseen ai.photta.app, avaa Developers-välilehti ja napsauta Generate API key. Tuotantoavaimet alkavat tunnisteella `photta_live_`.

  2. Vaihe 2

    Vie avain ympäristömuuttujaksi

    Lisää `export PHOTTA_API_KEY="photta_live_xxx"` komentotulkkisi profiiliin tai `.envrc`-tiedostoon, jotta jokainen seuraava curl-kutsu lukee sen automaattisesti.

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

    Kiinnitä perus-URL

    `export PHOTTA_BASE_URL="https://api.photta.app/api/v1"` pitää curl-komennot lyhyinä.

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

    Lähetä ja tee pollingia

    Tee POST-pyyntö osoitteeseen `$PHOTTA_BASE_URL/api/v1/ghost-mannequin` saadaksesi ID:n, ja suorita sitten silmukassa `curl $PHOTTA_BASE_URL/api/v1/ghost-mannequin/{id}` 3 sekunnin välein. Putketa vastaus jq:lle erottaaksesi kentän `.data.status` siististi.

    RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
      -H "Authorization: Bearer $PHOTTA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
      "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
      "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
      "image_side": "front",
      "angle": "side",
      "style": "3d",
      "background_color": "white",
      "resolution": "2K",
      "aspect_ratio": "3:4",
      "user_instruction": "closed front, cream interior lining",
      "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
    }')
    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/ghost-mannequin/$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. Vaihe 5

    Tallenna tulos pysyvästi

    Kun työ valmistuu, poimi `.data.output_url` jq:lla ja aja tavut paikalliseen tallennustilaan komennolla `curl -o` — valmiina liukuhihnasi seuraavaa vaihetta varten.

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

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.

Miksi cURL on edelleen nopein tapa todentaa API

  • Ei vaadi asennusta — cURL toimitetaan jokaisen suuren käyttöjärjestelmän mukana
  • Toimii yhdessä jq:n kanssa skriptatuissa liukuhihnoissa (CI, cron, shell hookit)
  • Nopein tapa tehdä endpointille smoke-testaus ennen sen kytkemistä koodiin
  • Jokainen tämän sivun komento voidaan liittää mihin tahansa POSIX-shelliin

Mitä se ei tee

  • Polling-silmukka varaa terminaalin — siirry Nodeen tai Pythoniin rinnakkaisia työntekijöitä varten
  • Polling on ainoa valmistumissignaali; API ei lähetä webhookeja
  • Windowsin komentorivin käyttäjien tulisi ajaa WSL:ää tai PowerShellin curl.exe-ohjelmaa

Kehittäjien usein kysymää

Onko saatavilla Photta-CLI-työkalua?

Ei vielä — mutta cURL yhdistettynä viidentoista rivin bash-wrapperiin vie jo pitkälle. Dokumentaatio suosii cURL-esimerkkejä ensisijaisesti, koska jokainen ohjelmointikieli voi ajaa aliprosessin, ja shell on CI-liukuhihnojen yhteinen nimittäjä.

Tarvitsenko jq-työkalua API:n käyttämiseen?

Et välttämättä — mutta skriptatut liukuhihnat ovat sen avulla huomattavasti helpompia. jq mahdollistaa kenttien `.data.id`, `.data.status` ja `.data.output_url` poimimisen JSON-vastauksesta ilman manuaalista jäsentämistä. Asenna macOS:lle komennolla `brew install jq` tai Debianille/Ubuntulle komennolla `apt install jq`.

Miten autentikoidun curlilla?

Lisää `-H "Authorization: Bearer $PHOTTA_API_KEY"` jokaiseen pyyntöön. Säilytä avainta ympäristömuuttujassa, äläkä koskaan sijoita sitä suoraan skriptiin, jonka commitoit repositorioon. Myös `curl --oauth2-bearer` toimii, mutta eksplisiittinen otsikkomuoto on selkeämpi dokumentaatiossa ja lokeissa.

Voinko käyttää curl-pohjaisia skriptejä tuotannossa?

Kertaluonteisiin eräajopohjaisiin backfilleihin ja cron-töihin kyllä — tuhannet tiimit tekevät katalogien backfillit tällä tavalla. Pitkäikäisessä sovelluksessa oikea kieli on yleensä parempi, koska käytettävissäsi ovat asianmukainen virheidenkäsittely, uudelleenyritykset ja observabiliteetti. Tämän sivun curl-esimerkit pysyvät paikkansapitävinä myös silloin, kun koodi siirretään Nodeen tai Pythoniin; pyynnön rakenne on sama.

Miten teen pollingia bash-silmukasta?

Käytä rakennetta `for i in $(seq 1 120); do … ; sleep 3; done`, jossa tilantarkistus ajetaan silmukan sisällä. Keskeytä suoritus, kun kentän `.data.status` arvo on `completed` tai `failed`. Tämän sivun koodiesimerkki näyttää tarkan mallin sisältäen tiukan ylärajan, jotta jumiutunut työ ei jätä skriptiä roikkumaan ikuisesti.

Miten luen virhevastaukset curlilla?

Käytä komentoa `curl -w "\n%{http_code}"` tallentaaksesi HTTP-tilakoodin JSON-rungon ohella. Haaroita logiikka tilakoodin mukaan: 402 kun credits eivät riitä, 429 rate limiteille (noudata Retry-After-arvoa) ja 5xx ohimeneville palvelinvirheille. Virherungossa on aina kentät `error.code` ja `error.message`.

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.

  • 1.5–4 min
  • 4 credits resoluutiolla 2K · 5 credits resoluutiolla 4K
  • asynkroninen, polling
  • 600 pyyntöä/min
  • Bearer-avain