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

Moderointi, SDK-yhteensopimattomuudet ja kulujen hallinta

Oppitunti 14 / 14 Päivitetty 3. marraskuuta 2026 Aloittelija
Tällä sivulla
  1. Ymmärrä kuvien rajapinnan rajoitukset
  2. Sisällön moderointi
  3. OpenAI SDK:n yhteensopimattomuus muokkauksessa
  4. Kulujen hallinta
  5. Mallien etsintäpäätepiste
  6. Keskeiset asiat
  7. Testaa tietämyksesi

Päivitetty 2. marraskuuta 2026 — Imagine. grok-imagine-image-quality poistettiin 2. marraskuuta 2026 (sen pyynnöt käsitellään Imagine 2.0:lla laadulla low): esimerkit käyttävät nyt mallia grok-imagine-image (Imagine 1.0) ja grok-imagine-image-2.0 (Imagine 2.0, laatu low, medium tai auto). OpenAI SDK:n kanssa parametrit aspect_ratio, resolution ja quality välitetään kohdassa extra_body, kun taas kuvan muokkaus vaatii xAI SDK:n tai suoran HTTP-pyynnön.

Ymmärrä kuvien rajapinnan rajoitukset

Jotta voit rakentaa luotettavia sovelluksia Grokin kuvien generointirajapinnalla, sinun on tunnettava sen rajoitukset: automaattinen moderointi, yhteensopimattomuus tiettyjen OpenAI SDK -metodien kanssa sekä kulujen hallintamekanismit.

Sisällön moderointi

Rajapinta moderoi automaattisesti sekä kehotteet (promptit) että generoidut kuvat. Tietyt sisältötyypit evätään:

  • Ilmeisen väkivaltainen tai verinen sisältö
  • Ilmeisen seksuaalinen sisältö
  • Vihaa tai syrjintää levittävä sisältö
  • Alaikäisiin sopimattomalla tavalla liittyvä sisältö

Kun moderointi aktivoituu, rajapinta palauttaa virheen kuvan sijaan.

Käsittele moderoinnin hylkäykset

import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
    "Content-Type": "application/json"
}

def generate_safe(prompt, **kwargs):
    """Generoi kuva käsitellen moderoinnin hylkäykset."""
    try:
        response = requests.post(
            "https://api.x.ai/v1/images/generations",
            headers=headers,
            json={"model": "grok-imagine-image", "prompt": prompt, **kwargs}
        )
        response.raise_for_status()
        return response.json()["data"][0]["url"]
    except requests.exceptions.HTTPError as e:
        if response.status_code == 400:
            print(f"Moderointi hylkäsi kehotteen: {prompt[:50]}...")
            return None
        raise

Moderoinnin parhaat käytännöt

Käytännössä moderointi kannattaa hoitaa ennakoivasti eikä reaktiivisesti. Jos legitiimi kehote estetään, testaa muunnelmia tunnistaaksesi laukaisevan sanan – esimerkiksi “eeppinen taistelu” menee läpi, kun karkeampi termi ei, ja näiden herkkyyksien kartoittaminen estää toistuvat estot. Kun kehotteet tulevat käyttäjiltäsi, lisää palvelinpuoleinen esisuodatus ennen API-kutsua: se sieppaa ilmeisesti sääntöjen vastaiset pyynnöt kuluttamatta API-kutsua ja pitää sinut kontrollissa näytettävästä viestistä. Tämä viimeinen kohta tekee eron kokemukseen: moderointieston ei pitäisi koskaan näkyä käyttäjälle raakana teknisenä virheenä, vaan selkeänä viestinä – “tämä pyyntö ei ole käyttöehtojemme mukainen” – joka selittää tilanteen paljastamatta API:n yksityiskohtia.

OpenAI SDK:n yhteensopimattomuus muokkauksessa

Tämä on kriittinen kohta: OpenAI SDK:n images.edit()-metodi ei toimi xAI-rajapinnan kanssa. OpenAI SDK lähettää datan muodossa multipart/form-data, kun taas xAI-rajapinta odottaa muotoa application/json.

# EI TOIMI
from openai import OpenAI
client = OpenAI(api_key=os.getenv("XAI_API_KEY"), base_url="https://api.x.ai/v1")
client.images.edit(
    model="grok-imagine-image",
    image=open("photo.png", "rb"),
    prompt="Edit this image"
)
# → Content-type -virhe!

# TOIMII: suora REST-kutsu
import requests
response = requests.post(
    "https://api.x.ai/v1/images/edits",
    headers={
        "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "model": "grok-imagine-image",
        "prompt": "Edit this image",
        "image": {"url": "https://exemple.com/photo.jpg"}
    }
)

Yhteensopivuusyhteenveto

Toiminto OpenAI SDK REST (requests)
images.generate() Yhteensopiva Yhteensopiva
images.edit() Yhteensopimaton Yhteensopiva

Kulujen hallinta

Kulutuksen seuranta

Määritä koodiisi kululaskuri:

class ImageBudgetTracker:
    PRICES = {
        "grok-imagine-image": 0.02,
        "grok-imagine-image-2.0": 0.04,  # low quality; medium at grid rate
    }

    def __init__(self, budget_limit=10.0):
        self.total_spent = 0.0
        self.budget_limit = budget_limit
        self.image_count = 0

    def can_generate(self, model, n=1):
        cost = self.PRICES[model] * n
        return (self.total_spent + cost) <= self.budget_limit

    def record(self, model, n=1):
        cost = self.PRICES[model] * n
        self.total_spent += cost
        self.image_count += n

    def report(self):
        remaining = self.budget_limit - self.total_spent
        print(f"Images generated: {self.image_count}")
        print(f"Spent: ${self.total_spent:.2f}")
        print(f"Remaining budget: ${remaining:.2f}")

# Käyttö
tracker = ImageBudgetTracker(budget_limit=5.0)

if tracker.can_generate("grok-imagine-image", n=5):
    response = client.images.generate(
        model="grok-imagine-image",
        prompt="My image",
        n=5
    )
    tracker.record("grok-imagine-image", n=5)

tracker.report()

Kulujen optimointi

Kultainen sääntö on erottaa explorointi ja tuotanto. Kehoitteiden etsinnän aikana työskentele Imagine 1.0:lla (0,02 $) käyttäen parametria n=3-5 vertaillaksesi muunnelmia edullisemmin; kun kehote on vakaa, vaihda Imagine 2.0:aan parametrilla n=1 lopullista renderöintiä varten. Tämä sekvenssi varaa korkeimman hinnan vain valituille kuville.

Kaksi mekanismia täydentää asetelmaa sovelluspuolella. Ensinnäkin tulosvälimuisti: jos sama kehote palautuu – luettelon kuvat, useiden käyttäjien uudelleenluomat standardikuvat – tarjoile jo generoitu kuva uuden pyynnön maksamisen sijaan. Sitten kiintiöt, jos käyttäjäsi laukaisevat generoinnit itse: päivittäinen tai tuntikohtainen raja suojaa budjettiasi kohtuuttomalta käytöltä ja väärinkäytöksiltä. Lopuksi pidä silmällä nopeusrajoituksia (300 RPM vakio, 30 RPM pro): putkiputki, joka ignoroi ne, kerryttää 429-virheitä ja tarpeettomia uudelleenyrityksiä.

Kuukausittaisen budjetin arviointi

Sovellukselle, jossa on 100 käyttäjää generoimassa 10 kuvaa päivässä:

  • Imagine 1.0: 100 x 10 x 30 x 0,02 $ = 600 $/kk
  • Imagine 2.0 laadulla low: 100 x 10 x 30 x 0,04 $ = 1 200 $/kk
  • Sekalainen (80/20): 24 000 x 0,02 $ + 6 000 x 0,04 $ = 720 $/kk

Mallien etsintäpäätepiste

Tarkistaaksesi ohjelmallisesti saatavilla olevat kuvamallit ja niiden hinnat:

response = requests.get(
    "https://api.x.ai/v1/image-generation-models",
    headers={"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}"}
)

for model in response.json()["data"]:
    print(f"{model['id']} : ${model['image_price']}/image, "
          f"max prompt : {model['max_prompt_length']} chars")

Hinnat 5. elokuuta 2026 – hinnat muuttuvat säännöllisesti: ennen kuin teet budjettilaskelmia, tarkista nykyinen hinnasto xAI:n viralliselta mallit ja hinnat -sivulta.

Keskeiset asiat

  • Moderointi on automaattista: käsittele hylkäykset koodissasi
  • OpenAI SDK:n images.edit() on yhteensopimaton xAI:n kanssa: käytä requests-kirjastoa
  • OpenAI SDK:n images.generate() toimii normaalisti
  • Toteuta budjetin seuranta kulujen hallitsemiseksi
  • Tarkista mallit ja hinnat päätepisteen /v1/image-generation-models kautta

Testaa tietämyksesi

Kuvien generointi ja muokkaus: operatiivinen yleiskatsaus.

1. Mikä erottaa Imagine 1.0:n ja Imagine 2.0:n?

Vastaus: Laatu/kustannus-kompromissi: Imagine 1.0 (0,02 $) volyymiin ja iteraatioihin, Imagine 2.0 (0,04 $ laadulla low, asetuksella quality) lopullisiin renderöinteihin – prototyypität ensimmäisellä, viimeistelet toisella.

2. Mikä tekee hyvästä kuvakehotteesta?

Vastaus: Kohde, tyyli, sommittelu ja eksplisiittiset yksityiskohdat – kuvaile kohtaus kuin taiteellisen ohjauksen briefi, ja iteroi sitten kohdennetuilla säädöillä uudelleenkirjoittamisen sijaan.

3. Mitä päätepiste /v1/images/edits mahdollistaa?

Vastaus: Olemassa olevien kuvien muokkaamisen: kehotteella kohdistetun muokkauksen, usean kuvan muokkauksen viitteillä ja monivaiheisen muokkauksen – retusoi tarkasti uudelleengeneroinnin sijaan.

4. Miten tuottaa tehokkaasti suurissa volyymeissä?

Vastaus: Parametri n erille, asynkroninen asiakas läpimenolle – ja koska tulosteen URL-osoitteet ovat väliaikaisia, lataa ja arkistoi ne välittömästi.

5. Mitä suojauksia ennen tuotantoon siirtymistä?

Vastaus: Kehoitteiden ja tulosteiden moderointi, tietämys SDK-yhteensopimattomuuksista ja kulujen hallinta (malli, resoluutio, volyymit) – luominen suurissa mittakaavoissa vaatii hallintaa.

Prototyypitä, muokkaa, teollista, hallinnoi: täydellinen kuvaputki – kulut hallinnassa joka vaiheessa.