Python · Korujen try-on-API
Korujen try-on-API Pythonilla
Yhdellä lauseella
Asenna requests, lue PHOTTA_API_KEY ympäristömuuttujista, kirjoita photta()-kääre, joka lähettää Bearer-avaimen ja nostaa tyypitetyn PhottaError-virheen muilla kuin 2xx-vastauksilla, tee sitten POST kohteeseen /api/v1/tryon/jewelry ja pollaa /api/v1/tryon/jewelry/{id} 3 sekunnin välein, kunnes status on completed.
- 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 vaihetta, nolla Photta-spesifistä riippuvuutta — requests kattaa kaiken.
Vaihe 1
Rekisteröidy ja luo avain
Sama polku kuin kaikilla muillakin kielillä: ai.photta.app → Developers → Generate API key. Avaimet alkavat merkkijonolla `photta_live_` ja toimivat kaikissa Phottan kyvykkyyksissä.
Vaihe 2
Lue avain ympäristömuuttujista
Aseta `PHOTTA_API_KEY` ympäristöön ja lue se koodissa `os.environ`-kautta. FastAPIssa tai Djangossa lue se kerran käynnistyksen yhteydessä asetusten moduuliin. Älä upota avainta lähdekoodiin tai julkiseen Git-historiaan.
python3 -m pip install requests export PHOTTA_API_KEY="photta_live_xxxxx"Vaihe 3
Kirjoita requests-kääre
Kolmikymmentärivinen `photta_request()`-funktio hoitaa perus-URL:n, Authorization-otsakkeen, JSON-sarjallistamisen ja virheiden kääntämisen. Se on ainoa tarvitsemasi abstraktio, kunnes Python SDK julkaistaan.
# photta.py — one helper for every endpoint import os, requests BASE = "https://api.photta.app/api/v1" class PhottaError(Exception): def __init__(self, status, error, retry_after=None): super().__init__(error.get("message", "request failed")) self.status, self.type, self.retry_after = status, error.get("type"), retry_after def photta(method, path, **kwargs): res = requests.request(method, BASE + path, headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"}, timeout=30, **kwargs) body = res.json() if not res.ok: raise PhottaError(res.status_code, body.get("error", {}), res.headers.get("Retry-After")) return bodyVaihe 4
Lähetä ja pollaa
Tee POST-pyyntö osoitteeseen `/api/v1/tryon/jewelry` saadaksesi luontitunnuksen (generation ID) ja pollaa sitten osoitetta `/api/v1/tryon/jewelry/{id}` 3 sekunnin välein. Celeryssä tai RQ:ssa jaa pollaussilmukka erillisiin tehtäviin, jotta useita minuutteja kestävä ajo ei varaa worker-prosessia.
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")Vaihe 5
Tallenna tulos pysyvästi
Valmis payload sisältää kentät `output_url` ja `thumbnail_url`. Lataa tavut omaan objektitallennustilaasi — S3, GCS, Cloudflare R2 — jotta tuotteesi ei ole sidottu Phottan CDN:ään pitkäaikaista renderöintiä 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.
try:
photta("POST", "/tryon/jewelry", 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."
})
except PhottaError as e:
if e.status == 402:
print("insufficient_credits_error: top up before retrying")
elif e.status == 429:
time.sleep(int(e.retry_after or 30))
else:
raiseRajoitukset
- 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 requests on oikea valinta tänään
- Ei Photta-spesifejä riippuvuuksia — requests löytyy jo useimmista Python-projekteista
- Toimii kaikkialla missä Pythonkin: Django, FastAPI, Flask, Celery-workerit, Lambda, skriptit
- Asiakaskääre on noin kolmekymmentä riviä — liitä se tiedostoon photta.py ja jatka eteenpäin
- Toimii yhdessä asynkio-koodin kanssa httpx:n kautta, kun tarvitset rinnakkaista lähetystä
Mitä se ei tee
- Ei vielä virallista Photta Python -pakettia — REST ja requests on dokumentoitu malli
- Pollaus on ainoa signaali valmistumisesta; rajapinta ei lähetä webhookeja
- Vain Bearer-avain; OAuth-asiakastunnistetietojen työnkulkua (client-credentials) ei ole
Kehittäjien usein kysymää
Onko olemassa virallista Photta Python SDK:ta?
Ei vielä. Tuettu integraatiotapa on requests-kirjasto (synkroninen) tai httpx (asynkroninen) — molemmat vaativat vain ohuen kääreen, ja tällä sivulla oleva kääre toimii jokaiselle kyvykkyydelle.
Mitä Python-versioita tuetaan?
Python 3.9 ja uudemmat. Kääre käyttää tyyppivihjeitä, f-merkkijonoja ja `str | None` -syntaksia, mikä toimii versiossa 3.10+. Versiossa 3.9 korvaa `str | None` muodolla `Optional[str]`. requests itse tukee virallisesti versiota 3.8+, mutta 3.9+ on käytännön minimi moderneissa Photta-projekteissa.
Pitäisikö minun käyttää requests- vai httpx-kirjastoa?
requests, jos teet muutamia peräkkäisiä kutsuja — se on yksinkertaisempi ja löytyy jo useimmista koodikannoista. httpx, jos tarvitset asynkronista rinnakkaisuutta (rinnakkaiset lähetykset, massatäytöt) tai HTTP/2-tukea. Kääre on minimaalinen kummassakin tapauksessa; vaihda `requests.request` muotoon `httpx.Client().request`, ja muu koodi pysyy identtisenä.
Voinko kutsua sitä Djangosta?
Kyllä. Sijoita kääre tiedostoon `services/photta.py` ja tuo se näkymästä tai Celery-tehtävästä. Älä kutsu rajapintaa synkronisen pyynnönkäsittelijän sisällä, jos työ on pitkäkestoinen — lähetä pyyntö näkymästä, palauta luontitunnus ja pollaa taustatehtävästä tai Channels-kuluttajasta.
Miten pollaan Celery-workerista?
Lähetä työ yhdestä tehtävästä ja ajoita sitten seurantatehtävä (`apply_async(countdown=3)` -kutsulla), joka pollaa kerran ja ajoittaa itsensä uudelleen, kunnes työ valmistuu tai uudelleenyritysten enimmäismäärä saavutetaan. Tämä pitää workerit vapaina ja välttää pitkäkestoisia tehtäviä, jotka sekoittavat automaattisen skaalauksen.
Miten rajapinta ilmoittaa virheistä?
Muut kuin 2xx-vastaukset sisältävät JSON-rungon, jossa on `error`-objekti: `type`, `code`, `message` sekä `param` 400-virheissä ja `retry_after` 429-virheissä. Tällä sivulla oleva kääre nostaa `PhottaError`-virheen, joka sisältää nämä kaikki, joten kutsuva koodi voi haarautua tilakoodin perusteella ilman rungon manuaalista jäsentämistä.
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.
LuecURL
Korujen try-on-API cURLillä
Kutsu Phottan korujen try-on-API-rajapintaa suoraan komentoriviltä cURLin avulla. Lähetä, pollaa, lataa — jokainen koodinpätkä toimii yhdessä jq:n kanssa skriptatuissa putkissa.
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