cURL · Korujen try-on-API
Korujen try-on-API cURLilla
Yhdellä lauseella
Vie PHOTTA_API_KEY ympäristömuuttujaksi, tee POST osoitteeseen https://api.photta.app/api/v1/api/v1/tryon/jewelry dokumentoidulla JSON-rungolla, ota luontitunnus talteen ja suorita sitten GET-silmukkaa osoitteeseen /api/v1/tryon/jewelry/{id} 3 sekunnin välein, kunnes data.status on completed. Poimi tuloksen URL yhdessä jq:n kanssa.
- Tyypillinen kesto: 1.5–4 min
- Credits: 5 credits resoluutiolla 2K · 6 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
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/jewelry \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"background": "soft window light on dark velvet",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "Make the pendant 10% smaller."
}')
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/jewelry/$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'const res = await fetch("https://api.photta.app/api/v1/tryon/jewelry", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"background": "soft window light on dark velvet",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "Make the pendant 10% smaller."
}),
});
const { data } = await res.json(); // data.id, data.status
async function waitFor(id) {
for (let attempt = 0; attempt < 120; attempt++) {
const res = await fetch(`https://api.photta.app/api/v1/tryon/jewelry/${id}`, { headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}` } });
const { data } = await res.json();
if (data.status === "completed") return data.output_url;
if (data.status === "failed") throw new Error(data.error_message ?? "generation failed");
await new Promise((r) => setTimeout(r, 3000));
}
throw new Error("timed out after 6 minutes");
}import os, requests
res = requests.post(
"https://api.photta.app/api/v1/tryon/jewelry",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"background": "soft window light on dark velvet",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "Make the pendant 10% smaller."
},
)
data = res.json()["data"] # data["id"], data["status"]
import time
def wait_for(job_id):
for _ in range(120):
res = requests.get(f"https://api.photta.app/api/v1/tryon/jewelry/{job_id}", headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"})
data = res.json()["data"]
if data["status"] == "completed":
return data["output_url"]
if data["status"] == "failed":
raise RuntimeError(data.get("error_message", "generation failed"))
time.sleep(3)
raise TimeoutError("timed out after 6 minutes")Lyhyesti
Lyhyesti
- Endpoint
- POST /api/v1/tryon/jewelry
- Autentikointi
- Bearer-API-avain
- Käsittely
- Asynkroninen — tee polling-kyselyitä status-endpointiin
- Tyypillinen kesto
- 1.5–4 min
- Credits
- 5 credits resoluutiolla 2K · 6 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.
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_`.
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"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"Vaihe 4
Lähetä ja tee pollingia
Tee POST-pyyntö osoitteeseen `$PHOTTA_BASE_URL/api/v1/tryon/jewelry` saadaksesi ID:n, ja suorita sitten silmukassa `curl $PHOTTA_BASE_URL/api/v1/tryon/jewelry/{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/tryon/jewelry \ -H "Authorization: Bearer $PHOTTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg", "jewelry_type": "necklace", "mannequin_id": "mnk_j9k1l2", "background": "soft window light on dark velvet", "resolution": "2K", "aspect_ratio": "3:4", "user_instruction": "Make the pendant 10% smaller." }') 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/jewelry/$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'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
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_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" ;;
esacRajoitukset
- 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`.
Liittyvät sivut
Node.js
Korujen try-on-API ympäristössä Node.js
Kutsu Phottan ominaisuutta korujen try-on-API Node.js-taustajärjestelmästä natiivilla fetchillä. SDK:ta ei tarvita: tallenna avaimesi, lähetä työ, pollaa tulosta.
LuePython
Korujen try-on-API Pythonissa
Kutsu Phottan korujen try-on-API -ominaisuutta Pythonissa requests-kirjaston avulla. Kolmenkymmenen rivin kääre, async-yhteensopiva httpx:n kautta, toimii Djangossa, FastAPIssa ja Celeryssä.
LueOminaisuudet
Korujen try-on-API kaulakoruille, sormuksille, rannekoruille ja korvakoruille
Sovita kaulakoruja, sormuksia, rannekoruja ja korvakoruja AI-malleille RESTin kautta. 5 credits resoluutiolla 2K, sisäänrakennetut lähikuvamallit, heijastukset huomioiva renderöinti Photta-dokumentaation mukaisesti.
LueRakenna
Rakenna AI-tuotekuvauspalvelu
Perustajan opas Phottan virtuaalisen try-on API:n jälleenmyyntiin white-label-SaaS-palveluna: tenant-avaimet, eräajojen hajautus, credit-pohjainen laskutus ja todellinen SLA.
LuePikaopas
Ensimmäinen Photta-kuva alle viidessä minuutissa.
Rekisteröidy, luo API-avain, suorita ensimmäinen cURL-kutsusi, tee pollingia valmistumiseen asti ja tallenna tulos. Viisi vaihetta, dokumentoitu alusta loppuun.
LueReferenssi
Photta API:n hinnoittelu
Mitä kukin Photta API -endpoint maksaa creditseinä resoluutioilla 2K ja 4K, miten veloitus ja palautukset toimivat ja mitkä endpointit ovat ilmaisia. Ei kuvakohtaista rahahintaa.
Lue
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.
- 1.5–4 min
- 5 credits resoluutiolla 2K · 6 credits resoluutiolla 4K
- asynkroninen, polling
- 600 pyyntöä/min
- Bearer-avain