Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Päätepiste /v1/images/generations: Aloitusopas

Oppitunti 1 / 14 Päivitetty 3. marraskuuta 2026 Aloittelija
Tällä sivulla
  1. Luo ensimmäinen kuvasi Grok API:n avulla
  2. Luontipyynnön rakenne
  3. Pyynnön parametrit
  4. Vastausformaatti
  5. Käytännön harjoitus
  6. Keskeiset asiat

Oppitunti suoritettu 3. marraskuuta 2026 perustuen Image Generation -sivuun ja xAI Images API -viitteeseen: oletusarvot (aspect_ratio asetettu arvoon auto, resolution arvoon 1k), quality-parametri Imagine 2.0:lle ja JPEG oletusmuotona. Lähteet: Image Generation · Images API.

Luo ensimmäinen kuvasi Grok API:n avulla

Grokin luoma kuva xAI API tarjoaa erityisen päätepisteen kuvien luomiseen: POST /v1/images/generations. Tämän päätepisteen avulla voit luoda kuvia tekstikuvauksen pohjalta käyttämällä Grok Imagine -malleja. Haluatpa sitten tuottaa kuvituksia, markkinointimateriaaleja tai luovia prototyyppejä, kaikki alkaa tästä päätepisteestä.

Tässä oppitunnissa opit, miten kuvien luontipyyntö rakennetaan ja mitkä ovat keskeisimmät parametrit.

1
Luontipäätepiste
2
Käytettävissä olevat mallit
10
Kuvien enimmäismäärä pyyntöä kohden
2k
Suurin resoluutio

Luontipyynnön rakenne

Kuvan luomiseen riittää kaksi parametria: malli ja kehote (prompt). Kaikilla muilla on oletusarvot, joten saat ensimmäisen tuloksen aikaiseksi kolmella rivillä – ja juuri näin sinun kannattaa toimia ennen kuin luet eteenpäin, jotta sinulla on kuva edessäsi ja voit yhdistää jokaisen parametrin konkreettiseen lopputulokseen.

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1"
)

response = client.images.generate(
    model="grok-imagine-image",
    prompt="A Breton lighthouse under a starry sky, watercolor style"
)

image_url = response.data[0].url
print(image_url)

xAI API yhteensopiva OpenAI SDK:n kanssa kuvien luonnissa: osoita base_url osoitteeseen https://api.x.ai/v1, anna xAI-avaimesi, ja loput koodistasi pysyvät muuttumattomina. Pidä mielessäsi tämän yhteensopivuuden rajat – se koskee luontia, mutta ei muokkausta, joka odottaa erilaista formaattia. Oppitunti 5 käsittelee tätä.

Pyynnön parametrit

Tässä ovat parametrit, jotka voit sisällyttää pyyntöösi:

  • model: käytettävä luontimalli (grok-imagine-image tai grok-imagine-image-2.0, katso oppitunti 2)
  • prompt: halutun kuvan tekstikuvaus
  • n: luotavien kuvien määrä (1–10, oletus: 1)
  • aspect_ratio: kuvan kuvasuhde (oletus auto: malli valitsee suhteen kehotteen perusteella)
  • resolution: resoluutio (oletus 1k tai 2k)
  • quality: low, medium tai auto (oletus) Imagine 2.0:ssa, katso oppitunti 12
  • response_format: url (oletus) tai b64_json, jos haluat vastaanottaa kuvan Base64-muodossa

Esimerkki kaikilla parametreilla

response = client.images.generate(
    model="grok-imagine-image",
    prompt="An enchanted forest with fireflies, digital art style",
    n=2,
    response_format="url",
    extra_body={"aspect_ratio": "16:9", "resolution": "2k"},
)

for image in response.data:
    print(image.url)

Vastausformaatti

Vastaus on aina taulukko, vaikka kyseessä olisi vain yksi kuva – käy se läpi silmukalla äläkä lue suoraan arvoa data[0], muuten koodisi kaatuu sinä päivänä, kun asetat n=4. Jokainen objekti sisältää:

  • url: kuvan väliaikainen URL-osoite (jos response_format on url)
  • b64_json: kuvan Base64-data (jos response_format on b64_json)

Palautettu MIME-tyyppi voi olla image/png, image/jpeg tai image/webp; oletuksena on image/jpeg, ellei laatuasetus tuota PNG-tiedostoa.

Käytännön harjoitus

Kokeile luoda ensimmäinen kuvasi muokkaamalla kehotetta omaan ammattiympäristöösi sopivaksi. Esimerkiksi esityksen visuaaliseksi elementiksi:

response = client.images.generate(
    model="grok-imagine-image",
    prompt="Minimalist chart showing startup growth, "
           "blue and white colors, dark background, flat design style",
    extra_body={"resolution": "2k", "aspect_ratio": "16:9"},
)

Keskeiset asiat

  • Luontipäätepiste on POST /v1/images/generations
  • Aloittamiseen riittää kaksi parametria: model ja prompt
  • API on yhteensopiva OpenAI Python SDK:n kanssa muuttamalla base_url:ää
  • Voit luoda jopa 10 kuvaa yhtä pyyntöä kohden
  • Käytettävissä olevat resoluutiot ovat 1k (oletus) ja 2k