cURL · Workflows API
Workflows API cURLilla
Yhdellä lauseella
Vie PHOTTA_API_KEY ympäristömuuttujaksi, tee POST osoitteeseen https://api.photta.app/api/v1/api/v1/workflows/{workflow_id} dokumentoidulla JSON-rungolla, ota luontitunnus talteen ja suorita sitten GET-silmukkaa osoitteeseen /api/v1/workflows/generations/{id} 3 sekunnin välein, kunnes data.status on completed. Poimi tuloksen URL yhdessä jq:n kanssa.
- Tyypillinen kesto: 20–60 sec / image
- 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
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/workflows/jewelry-studio-shot \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}')
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/workflows/generations/$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/workflows/jewelry-studio-shot", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}),
});
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/workflows/generations/${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/workflows/jewelry-studio-shot",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
},
)
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/workflows/generations/{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/workflows/{workflow_id}
- Autentikointi
- Bearer-API-avain
- Käsittely
- Asynkroninen — tee polling-kyselyitä status-endpointiin
- Tyypillinen kesto
- 20–60 sec / image
- 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.
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/workflows/{workflow_id}` saadaksesi ID:n, ja suorita sitten silmukassa `curl $PHOTTA_BASE_URL/api/v1/workflows/generations/{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/workflows/jewelry-studio-shot \ -H "Authorization: Bearer $PHOTTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "images": { "jewelry": [ "https://cdn.yourstore.com/products/gold-ring.jpg" ] }, "options": { "jewelryLighting": "dramatic", "backdrop": "dark" }, "user_text": "hero shot, ring angled slightly toward the camera", "num_images": 2, "aspect_ratio": "3:4", "resolution": "2K" }') 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/workflows/generations/$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
Workflows API ympäristössä Node.js
Kutsu Phottan ominaisuutta workflows API Node.js-taustajärjestelmästä natiivilla fetchillä. SDK:ta ei tarvita: tallenna avaimesi, lähetä työ, pollaa tulosta.
LuePython
Workflows API Pythonissa
Kutsu Phottan workflows API -ominaisuutta Pythonissa requests-kirjaston avulla. Kolmenkymmenen rivin kääre, async-yhteensopiva httpx:n kautta, toimii Djangossa, FastAPIssa ja Celeryssä.
LueOminaisuudet
Workflows API yksi kutsu, yksi esiasetus
Aja valmiita kuvauspohjia tuotekuvillesi. Luettelo määrittää omat kuvaslotit ja valintansa, joten yksi integraatio kattaa jokaisen esiasetuksen.
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.
- 20–60 sec / image
- 4 credits resoluutiolla 2K · 5 credits resoluutiolla 4K
- asynkroninen, polling
- 600 pyyntöä/min
- Bearer-avain