Päätepiste /v1/images/edits: Muokkaa kuviasi
Tällä sivulla
Päivitetty 2. marraskuuta 2026 — Imagine.
grok-imagine-image-qualitypoistettiin 2. marraskuuta 2026 (sen pyynnöt käsitellään nyt Imagine 2.0:lla laadullalow): esimerkit käyttävät nyt mallejagrok-imagine-image(Imagine 1.0) jagrok-imagine-image-2.0(Imagine 2.0, laadutlow,mediumtaiauto). OpenAI SDK:n kanssa parametritaspect_ratio,resolutionjaqualityvälitetään kentänextra_bodykautta, kun taas kuvien muokkaus vaatii xAI SDK:n tai suoran HTTP-pyynnön.
Kuvien muokkaus Grok API:n avulla
Generoinnin lisäksi xAI API tarjoaa erityisen päätepisteen olemassa olevien kuvien muokkaamiseen: POST /v1/images/edits. Tämän päätepisteen avulla voit muuttaa, muuntaa tai parantaa kuvia kuvailemalla halutut muutokset yksinkertaisella tekstikehotteella.
Muokkauspyynnön rakenne
Muokkaus toimii kuten generointi, mutta yhdellä erolla, joka muuttaa kaiken kehotteiden kirjoittamisessa: kehote kuvailee muutosta, ei lopullista kuvaa. Kehote “Nainen aurinkolaseissa” luo koko kuvan uudelleen alusta, kun taas “lisää aurinkolasit” säilyttää alkuperäisen valokuvan ja puuttuu vain kyseiseen kohtaan. Tämä on yleisin virhe ensimmäisellä kerralla, ja se selittää useimmat pettymystä tuottaneet tulokset.
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
payload = {
"model": "grok-imagine-image",
"prompt": "Lisää hahmolle punainen hattu",
"image": {
"url": "https://exemple.com/photo-personnage.jpg"
}
}
response = requests.post(
"https://api.x.ai/v1/images/edits",
headers=headers,
json=payload
)
result = response.json()
edited_url = result["data"][0]["url"]
Miksi käyttää kirjastoa requests OpenAI SDK:n sijaan?
Tässä on tämän oppitunnin tekninen sudenkuoppa, ja sinun kannattaa tietää tämä ennen kuin tuhlaat siihen tunnin: yhteensopivuus OpenAI SDK:n kanssa, joka toimii moitteettomasti generoinnissa, päättyy muokkaukseen. xAI:n muokkauspäätepiste käyttää JSON-muotoa, kun taas SDK:n metodi images.edit() lähettää datan muodossa multipart/form-data. Tämä sisältötyypin yhteensopimattomuus tarkoittaa, että sinun on käytettävä REST API:a suoraan kirjaston requests avulla muokkauksia tehtäessä.
# EI TOIMI xAI API:n kanssa
# client.images.edit(...) # Lähettää multipart-muodossa, ei JSONina
# TOIMII: suora REST-kutsu
requests.post(
"https://api.x.ai/v1/images/edits",
headers=headers,
json=payload
)
Muokkauspäätepisteen parametrit
model(vaadittu):grok-imagine-image(Imagine 1.0) taigrok-imagine-image-2.0(Imagine 2.0, joka hyväksyy myös parametrinquality)prompt(vaadittu): kuvaus tehtävästä muutoksestaimage: objekti, joka sisältää yhden lähdekuvan URL-osoitteenimages: objektien taulukko useille lähdekuville (poissulkee toisensa parametrinimagekanssa)mask: objekti, joka sisältää muokattavan alueen peitemaskin URL-osoitteenn: luotavien variaatioiden määrä (1–10)response_format:urltaib64_json
Mahdolliset muokkaustyypit
Alla olevilla viidellä ryhmällä ei ole samaa onnistumisastetta, ja tämä kannattaa pitää mielessä ennen tulosten lupaamista. Elementtien lisääminen ja tunnelman muuttaminen toimivat erittäin hyvin, koska ne nojaavat olemassa olevaan sisältöön. Poistaminen on hankalampaa – mallin on rekonstruoitava poistetun elementin takana oleva tausta – ja juuri tässä peitemaski tulee välttämättömäksi rajaamalla tarkasti alue, joka tulee uudelleenlaskemaan.
- Elementtien lisääminen: “Lisää hahmolle aurinkolasit”
- Poistaminen: “Poista tausta ja korvaa se valkoisella taustalla”
- Tyylimuunnos: “Muunna tämä valokuva akvarelli-illustraatioksi”
- Tunnelman muuttaminen: “Muuta kohtaus päivästä yöhön”
- Korjaus: “Paranna valaistusta ja lisää kontrastia”
# Esimerkki: kuvan tyylin muuttaminen
payload = {
"model": "grok-imagine-image",
"prompt": "Muunna tämä valokuva ranskalais-belgialaiseen sarjakuvatyyliin",
"image": {
"url": "https://exemple.com/photo-ville.jpg"
}
}
Käytännön harjoitus
Kokeile kuvan muokkaamista useassa vaiheessa. Aloita yksinkertaisella muutoksella ja tarkenna sitä sitten:
# Vaihe 1: muokkaa taustaa
payload_step1 = {
"model": "grok-imagine-image",
"prompt": "Korvaa tausta auringonlaskulla meren yllä",
"image": {"url": "https://exemple.com/portrait.jpg"}
}
Keskeiset asiat
- Muokkauspäätepiste on
POST /v1/images/edits - Käytä Pythonissa kirjastoa
requests, äläkä OpenAI SDK:ta (muotoyhteensopimattomuus) - Voit toimittaa enintään 5 lähdekuvaa pyyntöä kohden
- Kehote kuvailee haluttua muutosta luonnollisella kielellä
- Molemmat mallit (Imagine 1.0 ja Imagine 2.0) ovat käytettävissä muokkaukseen; OpenAI SDK:n metodia
images.edit()xAI ei tue: käytä xAI SDK:ta tai HTTP-pyyntöä