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

POST/api/v1/workflows/{workflow_id}
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')

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')

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"
}

Pyyntöparametrit

workflow_id

Tyyppi: stringPakollinen

The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.

images

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

options

Tyyppi: 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_text

Tyyppi: 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_images

Tyyppi: integer

Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.

= 1

aspect_ratio

Tyyppi: 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:9
resolution

Tyyppi: string

Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.

= 2K

Arvot: 2K4K

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.

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.

  1. Vaihe 1

    Luo API-avain

    Työnkulut käyttävät samoja tunnistetietoja ja samaa credits-saldoa kuin kaikki muutkin Phottan ominaisuudet.

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

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

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

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

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

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