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

Päätepiste /v1/images/edits: Muokkaa kuviasi

Oppitunti 5 / 14 Päivitetty 2. marraskuuta 2026 Aloittelija
Tällä sivulla
  1. Kuvien muokkaus Grok API:n avulla
  2. Muokkauspyynnön rakenne
  3. Miksi käyttää kirjastoa requests OpenAI SDK:n sijaan?
  4. Muokkauspäätepisteen parametrit
  5. Mahdolliset muokkaustyypit
  6. Käytännön harjoitus
  7. Keskeiset asiat

Päivitetty 2. marraskuuta 2026 — Imagine. grok-imagine-image-quality poistettiin 2. marraskuuta 2026 (sen pyynnöt käsitellään nyt Imagine 2.0:lla laadulla low): esimerkit käyttävät nyt malleja grok-imagine-image (Imagine 1.0) ja grok-imagine-image-2.0 (Imagine 2.0, laadut low, medium tai auto). OpenAI SDK:n kanssa parametrit aspect_ratio, resolution ja quality välitetään kentän extra_body kautta, 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.

5
Lähdekuvien enimmäismäärä
2
Syötemuodot
JSON
Vaadittu Content-Type
∞
Muokkauskierrokset

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) tai grok-imagine-image-2.0 (Imagine 2.0, joka hyväksyy myös parametrin quality)
  • prompt (vaadittu): kuvaus tehtävästä muutoksesta
  • image: objekti, joka sisältää yhden lähdekuvan URL-osoitteen
  • images: objektien taulukko useille lähdekuville (poissulkee toisensa parametrin image kanssa)
  • mask: objekti, joka sisältää muokattavan alueen peitemaskin URL-osoitteen
  • n: luotavien variaatioiden määrä (1–10)
  • response_format: url tai b64_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öä