Ominaisuus · Työnkulut
Workflows API yksi kutsu, yksi esiasetus
Yhdellä lauseella
Phottan workflows API ajaa valmiita kuvauspohjia tuotekuvillesi. Hae luettelo, täytä työnkulun kuvaslotit ja valinnat, tee POST ja kysele kunkin palautetun kohteen tilaa, kunnes se valmistuu.
- 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')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.statusimport 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"]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
Pyyntö ja vastaus
Pyyntö
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')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.statusimport 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"]202 Accepted / Completed
{
"data": {
"items": [
{
"id": "wfl_1f7c03a9e5b2486dd90c4b17ae62f508",
"workflow_id": "jewelry-studio-shot",
"status": "processing",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z"
},
{
"id": "wfl_8b2d64f0a1c9573ee4082d6cb95a3f17",
"workflow_id": "jewelry-studio-shot",
"status": "processing",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z"
}
],
"workflow_id": "jewelry-studio-shot",
"workflow_version": 1,
"credits_used": 8
},
"request_id": "req_wfl002"
}{
"data": {
"id": "wfl_1f7c03a9e5b2486dd90c4b17ae62f508",
"workflow_id": "jewelry-studio-shot",
"status": "completed",
"output_url": "https://cdn.photta.app/generated/wfl_1f7c03a9e5b2486dd90c4b17ae62f508.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/wfl_1f7c03a9e5b2486dd90c4b17ae62f508-thumb.jpg",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z",
"completed_at": "2026-08-03T10:20:41Z",
"error_code": null,
"error_message": null
},
"request_id": "req_wfl003"
}Pyyntöparametrit
workflow_idTyyppi: stringPakollinen
The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.
imagesTyyppi: objectPakollinen
Map of image slot id → array of images (https URL or base64 data URI). Slot ids, required flags, and min/max image counts come from the workflow's image_slots in the catalog. Missing entirely, missing a required slot, using an unknown slot, or exceeding a slot's max_images returns 400.
optionsTyyppi: object
Map of option id → choice id, both from the workflow's options in the catalog. Omitted options use their default_choice. Unknown option ids or choice ids return 400, as does sending an option that a filled image slot replaces (see replaces_options).
user_textTyyppi: string
Free-text styling/framing request (e.g. "hero shot, slightly angled"). Max 500 characters — excess is silently truncated. It never overrides product fidelity: the product always stays true to your images.
num_imagesTyyppi: integer
Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.
= 1
aspect_ratioTyyppi: string
Output aspect ratio. Defaults to the workflow's default_aspect_ratio from the catalog (3:4 for every current workflow).
= 3:4
Arvot:3:41:14:39:1616:9resolutionTyyppi: string
Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.
= 2K
Arvot:2K4K
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.
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.
Hae luettelo, täytä slotit, aja
Listaa työnkulut, täytä niiden ilmoittamat slotit, lähetä, kysele kunkin kohteen tilaa ja lataa.
Vaihe 1
Luo API-avain
Työnkulut käyttävät samoja tunnistetietoja ja samaa credits-saldoa kuin kaikki muutkin Phottan ominaisuudet.
Vaihe 2
Listaa työnkulkuluettelo
GET `/api/v1/workflows` palauttaa 53 mallipohjaa 7 kategoriassa, joista jokainen ilmoittaa omat kuvaslottinsa, optio-enuminsa ja oletuskuvasuhteensa. Suodata parametrilla `category` — tuntematon kategoria palauttaa 400 sen sijaan, että se jätettäisiin huomiotta.
Vaihe 3
Tee POST ajolle
Tee POST `/api/v1/workflows/:workflow_id` sisältäen `images` (slotti-id kuviin) ja `options` (optio-id valinta-id:hen), molemmat poimittu luettelomerkinnästä. `user_text` hyväksyy vapaamuotoisen tyylipyynnön, ja `num_images` ajaa 1–4 kuvaa yhdellä kutsulla.
Vaihe 4
Kysele jokaisen kohteen tilaa
202-vastaus sisältää yhden kohteen pyydettyä kuvaa kohden. Tee GET `/api/v1/workflows/generations/:id` 3 sekunnin välein kullekin id:lle, kunnes `data.status` on `completed` tai `failed`; tyypillinen valmistumisaika on 20–60 sekuntia per kuva.
Vaihe 5
Lataa ja tallenna pysyvästi
Jokainen valmistunut kohde sisältää oman `output_url`-osoitteensa. Kohteet valmistuvat toisistaan riippumatta, joten voit julkaista ensimmäisen samalla kun muita renderöidään vielä.
Sama endpoint kielillä Node.js, Python ja cURL
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ä.
LuecURL
Workflows API cURLillä
Kutsu Phottan workflows API-rajapintaa suoraan komentoriviltä cURLin avulla. Lähetä, pollaa, lataa — jokainen koodinpätkä toimii yhdessä jq:n kanssa skriptatuissa putkissa.
Lue
Kysymykset, joita kehittäjät kysyvät ennen työnkulkujen ajamista
Mikä on workflows API?
Luettelo valmiita kuvauspohjia, joita ajat omia tuotevalokuviasi vasten. Promptin kokoamisen sijaan valitset työnkulun ja täytät sen ilmoittamat kuvaslotit ja valinnat.
Kuinka paljon työnkulun ajaminen maksaa?
4 credits per kuva resoluutiolla 2K ja 5 per kuva resoluutiolla 4K, kerrottuna arvolla `num_images`. Luettelo sisältää kunkin työnkulun ajantasaisen hinnan — lue se sieltä olettamisen sijaan.
Miten löydän työnkulun id:n?
GET `/api/v1/workflows`. Jokainen merkintä sisältää id:nsä, kategoriansa, kuvaslottinsa ja valintansa. Suodata listaa parametrilla `category`: `jewelry`, `product`, `shoe`, `cosmetics`, `food`, `bag` tai `watch`.
Mitä images- ja options-kenttiin syötetään?
`images` yhdistää luettelomerkinnän slotti-id:n kuvataulukkoon (https-URL-osoitteina tai base64-data-URI-muodossa). `options` yhdistää optio-id:n johonkin kyseisen option valinta-id:istä. Molemmat rakenteet tulevat luettelosta, minkä ansiosta integraatio toimii sellaisenaan myös uusien työnkulkujen kanssa.
Kuinka monta kuvaa yksi ajo voi tuottaa?
`num_images` hyväksyy arvot 1–4. Jokainen kuva generoidaan itsenäisesti ja se saa vastauksessa oman kohde-id:nsä, joten yksi voi epäonnistua vaikuttamatta muihin.
Miten kyselen tuloksia (polling)?
Pollaa jokaista kohdetta erikseen: GET `/api/v1/workflows/generations/:id` 3 sekunnin välein. GET `/api/v1/workflows/generations/list` antaa sivutetun näkymän, joka on suodatettu parametreilla `workflow_id` tai `status`.
Liittyvät ominaisuudet
Ominaisuudet
Virtuaalinen try-on API vaatteille
REST API, joka asettaa vaatteet tekoälymallinukkejen päälle. Asynkroninen, 1.5–4 minuutin generointi, 5 credits resoluutiolla 2K, 6 resoluutiolla 4K. cURL-, Node.js- ja Python-esimerkit.
Katso endpointOminaisuudet
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.
Katso endpointRakenna
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.
Katso endpointVertailu
Photta vs Ayna — kehittäjä-API vai Shopify-lähtöinen studio
Photta vs Ayna -vertailu: kolme REST-endpointia vastaan Shopify-lähtöinen studio + API. Molemmilla on vahvuutensa. Tiedot kerätty kummankin sivustolta 2026-04-19.
Katso endpointPikaopas
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.
Katso endpointReferenssi
Photta API -virheet
Täydellinen luettelo Photta API -virhetyypeistä statuskoodeineen, virheen rungon rakenne ja tiedot siitä, mitkä virheet kannattaa yrittää uudelleen.
Katso endpointReferenssi
Photta API:n rate limitit
Photta API:n rate limit, sen aikaikkuna, Retry-After-otsake, pollausväli ja tilauskohtaiset rinnakkaisuusrajat, kaikki API-dokumentaatiosta luettuna.
Katso endpoint
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