Python · Ghost mannequin API

Ghost mannequin 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/ghost-mannequin ja pollaa /api/v1/ghost-mannequin/{id} 3 sekunnin välein, kunnes status on completed.

  • Tyypillinen kesto: 1.5–4 min
  • 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/ghost-mannequin
import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/ghost-mannequin",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
      "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
      "image_side": "front",
      "angle": "side",
      "style": "3d",
      "background_color": "white",
      "resolution": "2K",
      "aspect_ratio": "3:4",
      "user_instruction": "closed front, cream interior lining",
      "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
    },
)
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/ghost-mannequin/{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/ghost-mannequin
Autentikointi
Bearer-API-avain
Käsittely
Asynkroninen — tee polling-kyselyitä status-endpointiin
Tyypillinen kesto
1.5–4 min
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 vaihetta, nolla Photta-spesifistä riippuvuutta — requests kattaa kaiken.

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

  2. 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"
  3. 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 body
  4. Vaihe 4

    Lähetä ja pollaa

    Tee POST-pyyntö osoitteeseen `/api/v1/ghost-mannequin` saadaksesi luontitunnuksen (generation ID) ja pollaa sitten osoitetta `/api/v1/ghost-mannequin/{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/ghost-mannequin",
        headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
        json={
          "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
          "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
          "image_side": "front",
          "angle": "side",
          "style": "3d",
          "background_color": "white",
          "resolution": "2K",
          "aspect_ratio": "3:4",
          "user_instruction": "closed front, cream interior lining",
          "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
        },
    )
    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/ghost-mannequin/{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")
  5. 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

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.
try:
    photta("POST", "/ghost-mannequin", json={
      "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
      "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
      "image_side": "front",
      "angle": "side",
      "style": "3d",
      "background_color": "white",
      "resolution": "2K",
      "aspect_ratio": "3:4",
      "user_instruction": "closed front, cream interior lining",
      "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
    })
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:
        raise

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.

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

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
  • 4 credits resoluutiolla 2K · 5 credits resoluutiolla 4K
  • asynkroninen, polling
  • 600 pyyntöä/min
  • Bearer-avain