Salt la conținutul principal
Română— Alege o limbă
Meniu

Surse de imagini: URL și Base64

Lecția 6 din 14 Actualizată 3 noiembrie 2026 Începător
Pe această pagină
  1. Furnizarea imaginilor către endpoint-ul de editare
  2. Formatul URL
  3. Formatul URI de date Base64
  4. A treia opțiune: Un fișier din API-ul Files
  5. Funcție utilitară
  6. Exercițiu practic
  7. Puncte cheie

Actualizat la 3 noiembrie 2026. Pe baza paginii Image Editing și a referinței API xAI Images: o imagine sursă poate fi specificată și folosind file_id al unui fișier din API-ul Files, ca alternativă exclusivă la url. Surse: Image Editing · Images API.

Furnizarea imaginilor către endpoint-ul de editare

Endpoint-ul de editare acceptă imagini sursă în trei forme: un URL public, un URI de date Base64 sau file_id al unui fișier deja încărcat în API-ul xAI Files. Fiecare are cazurile sale de utilizare; stăpânirea lor vă permite să construiți fluxuri de lucru de editare flexibile.

Formatul URL

Formatul URL este cea mai convenabilă opțiune atâta timp cât imaginea este deja online: nimic de codificat, o sarcină utilă (payload) minusculă și o cerere care rămâne lizibilă în jurnale. Constrângerea cheie aici este public—imaginea trebuie să poată fi recuperată de serverele xAI fără o sesiune sau un token.

payload = {
    "model": "grok-imagine-image",
    "prompt": "Add a gold frame around this image",
    "image": {
        "url": "https://exemple.com/ma-photo.jpg"
    }
}

Constrângeri URL

  • URL-ul trebuie să fie accesibil public (fără link-uri protejate prin autentificare)
  • Formatele suportate sunt JPEG, PNG și WebP
  • Imaginea trebuie să fie accesibilă rapid (evitați serverele lente)

Utilizarea URL-urilor de ieșire din API

Acest lucru face ca editarea în mai multe etape să fie practică: ieșirea unei editări devine intrarea pentru următoarea, fără a descărca vreodată imaginea pe mașina locală. O singură precizare totuși—aceste URL-uri expiră, așa că lanțul trebuie executat dintr-o singură mișcare. Pentru un flux de lucru desfășurat în timp, descărcați-l între fiecare pas.

import requests
import os

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

# Generarea unei imagini
gen_response = requests.post(
    "https://api.x.ai/v1/images/generations",
    headers=headers,
    json={
        "model": "grok-imagine-image",
        "prompt": "A medieval castle on a hill"
    }
).json()

generated_url = gen_response["data"][0]["url"]

# Editarea imaginii generate
edit_response = requests.post(
    "https://api.x.ai/v1/images/edits",
    headers=headers,
    json={
        "model": "grok-imagine-image",
        "prompt": "Add a dragon flying over the castle",
        "image": {"url": generated_url}
    }
).json()

Formatul URI de date Base64

Pentru imaginile stocate local sau generate dinamic, utilizați formatul URI de date Base64:

import base64

# Citirea unei imagini locale
with open("photo_locale.jpg", "rb") as f:
    image_bytes = f.read()

b64_string = base64.b64encode(image_bytes).decode("utf-8")
data_uri = f"data:image/jpeg;base64,{b64_string}"

payload = {
    "model": "grok-imagine-image",
    "prompt": "Transform this photo into a vector illustration",
    "image": {
        "url": data_uri
    }
}

Când să utilizați Base64?

Criteriul este simplu: Base64 este necesar ori de câte ori utilizarea unui URL public ar fi un ocol inutil. Acest lucru se aplică imaginilor locale care nu sunt găzduite nicăieri—încărcarea lor pe un server doar pentru a le face accesibile API-ului adaugă un pas și o întârziere fără valoare. Se aplică, de asemenea, imaginilor generate în memorie de aplicația dumneavoastră: un grafic produs din mers, o captură de ecran a unei randări sau o miniatură compusă dinamic nu trebuie să atingă niciodată discul. Base64 răspunde, de asemenea, unei preocupări legate de confidențialitate—o imagine codificată în corpul cererii nu este niciodată expusă pe un server public, chiar și temporar—și simplifică arhitectura: un flux automatizat care înlănțuie generarea, editarea și salvarea funcționează cap-la-cap fără găzduire intermediară de provisionat, securizat și curățat.

Atenție la dimensiune

Base64 umflă sarcina utilă cu aproximativ o treime, ceea ce este neglijabil pentru o miniatură, dar devine semnificativ pentru o fotografie de mai mulți megabytes—timpi de încărcare mai lungi și riscul de a depăși limitele de dimensiune ale cererii. Regula de bază: dacă imaginea este deja accesibilă online, utilizați URL-ul; dacă este locală, Base64 este mai simplu decât găzduirea ei doar pentru această ocazie.

A treia opțiune: Un fișier din API-ul Files

O imagine deja încărcată în API-ul Files xAI este specificată prin identificatorul său, în loc de un URL. Cele două câmpuri se exclud reciproc: un obiect image conține fie url, fie file_id.

payload = {
    "model": "grok-imagine-image",
    "prompt": "Add snow to the landscape",
    "image": {"file_id": "file_abc123"}
}

Aceasta este alegerea naturală pentru o imagine reutilizată în mai multe editări: este trimisă o singură dată și nu trebuie să fie publică.

Funcție utilitară

Iată o funcție care gestionează automat ambele formate:

import base64
import os

def prepare_image_source(source):
    """Prepares an image source for the API (URL or local file)."""
    if source.startswith("http://") or source.startswith("https://"):
        return {"url": source}

    if os.path.isfile(source):
        ext = source.rsplit(".", 1)[-1].lower()
        mime_map = {"jpg": "jpeg", "jpeg": "jpeg", "png": "png", "webp": "webp"}
        mime_type = mime_map.get(ext, "jpeg")

        with open(source, "rb") as f:
            b64 = base64.b64encode(f.read()).decode("utf-8")
        return {"url": f"data:image/{mime_type};base64,{b64}"}

    raise ValueError(f"Invalid source: {source}")

Această funcție detectează automat dacă sursa este un URL sau o cale către un fișier local și formatează obiectul în consecință.

Exercițiu practic

Testați ambele formate cu aceeași imagine și același prompt pentru a verifica faptul că ambele căi funcționează; imaginile rezultate vor varia de la o execuție la alta, ca orice generare:

# Prin URL
payload_url = {
    "model": "grok-imagine-image",
    "prompt": "Add snow to the landscape",
    "image": {"url": "https://exemple.com/paysage.jpg"}
}

# Prin Base64
payload_b64 = {
    "model": "grok-imagine-image",
    "prompt": "Add snow to the landscape",
    "image": prepare_image_source("paysage.jpg")
}

Puncte cheie

  • Trei forme de intrare: URL public, URI de date Base64 sau file_id din API-ul Files
  • URL-urile temporare returnate de API pot servi drept surse pentru editare
  • Base64 mărește dimensiunea sarcinii utile cu ~33%
  • Creați o funcție utilitară pentru a gestiona automat ambele formate
  • URL-ul trebuie să fie accesibil public pentru a funcționa