Премини към основното съдържание
Български— Изберете език
Меню

Крайна точка /v1/images/edits: Редактиране на изображения

Урок 5 от 14 Обновен 2 ноември 2026 г. Начинаещ
На тази страница
  1. Редактиране на изображения с Grok API
  2. Структура на заявката за редактиране
  3. Защо да използвате requests вместо OpenAI SDK?
  4. Параметри на крайната точка за редактиране
  5. Видове възможни редакции
  6. Практическо упражнение
  7. Ключови изводи

Обновено на 2 ноември 2026 г. — Imagine. grok-imagine-image-quality беше премахнат на 2 ноември 2026 г. (заявките му се обслужват от Imagine 2.0 с качество low): примерите сега използват grok-imagine-image (Imagine 1.0) и grok-imagine-image-2.0 (Imagine 2.0, с качество low, medium или auto). Когато използвате OpenAI SDK, параметрите aspect_ratio, resolution и quality се предават чрез extra_body, а редактирането изисква използването на xAI SDK или директна HTTP заявка.

Редактиране на изображения с Grok API

Освен генерирането, xAI API предлага специализирана крайна точка за редактиране на съществуващи изображения: POST /v1/images/edits. Тази крайна точка Ви позволява да модифицирате, трансформирате или подобрявате изображения, като описвате желаните промени чрез обикновен текстов подканващ текст (prompt).

5
Максимален брой изходни изображения
2
Входни формати
JSON
Задължителен Content-Type
∞
Кръгове на редактиране

Структура на заявката за редактиране

Редактирането работи подобно на генерирането, но с една ключова разлика, която променя изцяло начина, по който пишете подканващите текстове: текстът описва модификацията, а не крайното изображение. Фразата „Жена със слънчеви очила“ ще регенерира цяло ново изображение, докато „добави слънчеви очила“ запазва оригиналната снимка и intervenира само върху този конкретен елемент. Това е най-честата грешка при първия опит и тя обяснява повечето разочароващи резултати.

import requests
import os

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

payload = {
    "model": "grok-imagine-image",
    "prompt": "Добави червена шапка на героя",
    "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"]

Защо да използвате requests вместо OpenAI SDK?

Ето техническия капан в този урок, който е добре да знаете, преди да загубите часове в опити: съвместимостта с OpenAI SDK, която работи безупречно за генериране, спира при редактирането. Крайната точка за редактиране на xAI използва JSON формат, докато методът images.edit() на SDK изпраща данни във формат multipart/form-data. Тази несъвместимост на типа съдържание означава, че за редактиране трябва да използвате директно REST API чрез библиотеката requests.

# НЕ РАБОТИ с xAI API
# client.images.edit(...)  # Изпраща multipart, а не JSON

# РАБОТИ: директна REST заявка
requests.post(
    "https://api.x.ai/v1/images/edits",
    headers=headers,
    json=payload
)

Параметри на крайната точка за редактиране

  • model (задължително): grok-imagine-image (Imagine 1.0) или grok-imagine-image-2.0 (Imagine 2.0, който също приема параметъра quality)
  • prompt (задължително): описание на модификацията, която да се приложи
  • image: обект, съдържащ URL адреса на едно изходно изображение
  • images: масив от обекти за множество изходни изображения (взаимно изключващо се с image)
  • mask: обект, съдържащ URL адреса на маската на областта за редактиране
  • n: брой варианти за генериране (от 1 до 10)
  • response_format: url или b64_json

Видове възможни редакции

Петте категории по-долу нямат еднакъв процент на успех и е полезно да го знаете, преди да обещаете конкретен резултат. Добавянето на елементи и промяната на атмосферата работят много добре, тъй като разчитат на съществуващото съдържание. Премахването е по-сложно – моделът трябва да реконструира това, което се е намирало зад премахнатия елемент – и точно тук маската става съществена, като точно ограничава областта за прекалкулация.

  • Добавяне на елементи: „Добави слънчеви очила на героя“
  • Премахване: „Премахни фона и го замени с бял фон“
  • Трансформация на стила: „Преобразувай тази снимка в акварелна илюстрация“
  • Промяна на атмосферата: „Промени сцената от ден на нощ“
  • Корекция: „Подобри осветлението и увеличи контраста“
# Пример: промяна на стила на изображение
payload = {
    "model": "grok-imagine-image",
    "prompt": "Трансформирай тази снимка в илюстрация в стил френско-белгийски комикс",
    "image": {
        "url": "https://exemple.com/photo-ville.jpg"
    }
}

Практическо упражнение

Опитайте да редактирате изображение на няколко етапа. Започнете с проста модификация, след което я усъвършенствайте:

# Стъпка 1: модифициране на фона
payload_step1 = {
    "model": "grok-imagine-image",
    "prompt": "Замени фона със залез над океана",
    "image": {"url": "https://exemple.com/portrait.jpg"}
}

Ключови изводи

  • Крайната точка за редактиране е POST /v1/images/edits
  • Използвайте requests в Python, а не OpenAI SDK (несъвместимост на формата)
  • Можете да предоставите до 5 изходни изображения на заявка
  • Подканващият текст описва желаната модификация на естествен език
  • И двата модела (Imagine 1.0 и Imagine 2.0) са налични за редактиране; при използване на OpenAI SDK, images.edit() не се поддържа от xAI: използвайте xAI SDK или HTTP заявка