Päätepiste /v1/images/generations: Aloitusopas
Tällä sivulla
Oppitunti suoritettu 3. marraskuuta 2026 perustuen Image Generation -sivuun ja xAI Images API -viitteeseen: oletusarvot (
aspect_ratioasetettu arvoonauto,resolutionarvoon1k),quality-parametri Imagine 2.0:lle ja JPEG oletusmuotona. Lähteet: Image Generation · Images API.
Luo ensimmäinen kuvasi Grok API:n avulla
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.
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-imagetaigrok-imagine-image-2.0, katso oppitunti 2)prompt: halutun kuvan tekstikuvausn: luotavien kuvien määrä (1–10, oletus: 1)aspect_ratio: kuvan kuvasuhde (oletusauto: malli valitsee suhteen kehotteen perusteella)resolution: resoluutio (oletus1ktai2k)quality:low,mediumtaiauto(oletus) Imagine 2.0:ssa, katso oppitunti 12response_format:url(oletus) taib64_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 (josresponse_formatonurl)b64_json: kuvan Base64-data (josresponse_formatonb64_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:
modeljaprompt - 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) ja2k