LiteLLM: запросы к моделям для работы с изображениями

LiteLLM: запросы к моделям для работы с изображениями делятся на три разных пути. Генерация вызывает image_generation() и эндпоинт /v1/images/generations. Редактирование — image_edit() и /v1/images/edits. Передача картинки на вход модели идёт через completion() с массивом content и блоком image_url. Ниже — документированные вызовы, таблица выбора и проверка результата.

Три задачи и три разных вызова

Разделение начинается с того, что вы просите у модели. Генерация создаёт изображение с нуля по текстовому описанию: в документации LiteLLM это функция image_generation() и эндпоинт /v1/images/generations. Редактирование берёт готовый файл и меняет его: функция image_edit(), эндпоинт /v1/images/edits, обязательные аргументы image и prompt. Vision отправляет картинку на вход языковой модели и получает текстовый ответ: это completion(), где в messages лежит content-массив с блоком type: image_url.

Аргументы тоже разные. У генерации обязателен только prompt, а model, n, size, quality, response_format — опциональные поля. У редактирования обязательны image и prompt. У vision обязателен блок image_url внутри content.

Ответы отличаются по типу. Генерация и редактирование возвращают структуру с массивом data, где лежит url или b64_json. Vision возвращает текст в choices[].message.content. Смешивать эти пути в одном вызове нельзя: у каждого свой набор параметров и свой формат результата. Выбирайте функцию по типу задачи.

Генерация через Python SDK

Базовый вызов в документации LiteLLM выглядит так: импортируется image_generation, ключ провайдера кладётся в переменную окружения, затем идёт вызов с prompt и model. Обязательное поле здесь одно — prompt, текстовое описание нужного изображения. Остальное опционально.

Ключевые параметры из официальной страницы генерации:

• model — модель генерации; по умолчанию openai/gpt-image-1;
• n — число изображений, от 1 до 10; для dall-e-3 поддерживается только n=1;
• quality — auto по умолчанию; для gpt-image-1 доступны high, medium, low, для dall-e-3 — hd и standard, для dall-e-2 — только standard;
• size — для gpt-image-1 это 1024x1024, 1536x1024, 1024x1536 или auto; для dall-e-2 — 256x256, 512x512, 1024x1024; для dall-e-3 — 1024x1024, 1792x1024, 1024x1792;
• response_format — url или b64_json;
• timeout — по умолчанию 600 секунд.

Пример из документации для OpenAI. Перед запуском задайте свой ключ в переменной окружения OPENAI_API_KEY; примеры ниже используют её без изменения значения:

from litellm import image_generation
import os


response = image_generation(prompt="A cute baby sea otter", model="dall-e-3")
print(f"response: {response}")

Для Azure ключи задаются отдельно: AZURE_API_KEY, AZURE_API_BASE, AZURE_API_VERSION, а модель указывается как azure/<your deployment name>. Для Recraft используется RECRAFT_API_KEY и модель recraft/recraftv3. Для OpenRouter — OPENROUTER_API_KEY и модель вида openrouter/google/gemini-2.5-flash-image. Для Bedrock нужны AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION_NAME. Для Vertex AI — vertex_ai_project и vertex_ai_location в аргументах вызова.

Генерация через прокси

Прокси поднимается из config.yaml с секцией model_list. Каждая запись содержит model_name — имя, которое увидит клиент, и litellm_params с реальной моделью провайдера и ключом. Пример из документации:

model_list:
  - model_name: gpt-image-1
    litellm_params:
      model: azure/gpt-image-1
      api_base: https://my-endpoint-europe-berri-992.openai.azure.com/
      api_key: "os.environ/AZURE_API_KEY_EU"

Запуск: litellm --config /path/to/config.yaml. Прокси слушает http://0.0.0.0:4000. Запрос через curl:

curl -X POST 'http://0.0.0.0:4000/v1/images/generations' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $LITELLM_API_KEY" \
-d '{
  "model": "gpt-image-1",
  "prompt": "A cute baby sea otter",
  "n": 1,
  "size": "1024x1024"
}'

Тот же вызов через OpenAI SDK: клиент инициализируется с base_url="http://0.0.0.0:4000" и ключом прокси, затем вызывается client.images.generate(). В поле model запроса укажите model_name из конфигурации прокси. Прокси сам подставит реальную модель и ключ.

Vision: картинка на входе модели

Для Vision используется completion(). В messages лежит content-массив, где текст и картинка — отдельные блоки:

import os
from litellm import completion


response = completion(
    model="gpt-6.1-sol",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What's in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://awsmp-logos.s3.amazonaws.com/seller-xw5kijmvmzasy/c233c9ade2ccb5491072ae232c814942.png"
                    }
                }
            ]
        }
    ],
)

Спецификация image_url из документации допускает две формы. Строка: "image_url": "url OR base64 encoded str". Объект: "image_url": {"url": "...", "detail": "openai-only param", "format": "specify mime-type of image"}. Поле format задаёт MIME-тип, когда LiteLLM неверно определяет его сам — например, для gs://-адресов Vertex AI. Для OpenAI это поле игнорируется.

Проверка поддержки vision делается двумя способами. В SDK: litellm.supports_vision(model="") возвращает True или False. В документации приведены примеры: openai/gpt-5.6-terra — True, vertex_ai/gemini-3.1-pro-preview — True, openai/gpt-3.5-turbo — False, xai/grok-2-vision-latest — True, xai/grok-2-latest — False.

Через прокси поддержка проверяется запросом GET /model_group/info с заголовком x-api-key. В ответе для каждой группы есть поле supports_vision. Чтобы кастомная модель отдавала его как True, в config.yaml добавляется model_info: supports_vision: True.

Таблица выбора пути

Выбор между SDK и прокси определяется тем, где живёт ключ провайдера. SDK подходит для скрипта, где ключ лежит в переменной окружения процесса. Прокси нужен, когда ключи централизованы на сервере, а клиенты обращаются по одному адресу с ключом прокси.

Проверка результата вызова

Код 200 подтверждает, что запрос дошёл. Изображение подтверждается содержимым ответа. У генерации и редактирования ответ содержит массив data. Проверяйте url или b64_json в элементах data; поле revised_prompt показано в документации генерации и может отсутствовать в ответе редактирования. Пример структуры из документации генерации:

{
  "created": 1703658209,
  "data": [{
    "b64_json": null,
    "revised_prompt": "Adorable baby sea otter...",
    "url": "https://oaidalleapiprodscus.blob.core.windows.net/..."
  }],
  "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
}

При response_format: "b64_json" поле url пустое, а картинка лежит в b64_json в base64. Для редактирования через Gemini документация описывает ответы только в base64 и показывает декодирование через base64.b64decode(response.data[0].b64_json) с записью в файл.

Проверка строится на трёх пунктах. Первое: data непустой. Второе: в элементе есть url или b64_json в зависимости от запрошенного формата. Третье: у vision-вызова есть текст в choices[].message.content. Если data пуст или оба поля null, вызов не дал изображения, даже при коде 200.

Диагностика типовых ошибок

Неверное имя модели. В прокси поле model в запросе должно совпадать с model_name из config.yaml. Если указать имя модели провайдера, прокси не найдёт запись в model_list. В SDK имя модели должно соответствовать формату провайдера: azure/<deployment>, recraft/recraftv3, openrouter/google/gemini-2.5-flash-image, bedrock/stability.stable-diffusion-xl-v0.

Неподдерживаемый размер или quality. Наборы значений различаются по моделям. 1536x1024 документирован для gpt-image-1 и не входит в список для dall-e-2 или dall-e-3. quality: "hd" документирован для dall-e-3, а для gpt-image-1 перечислены high, medium, low. Сверяйте значения с таблицей параметров на странице нужной модели.

Отсутствие ключа провайдера. Каждый провайдер читает свою переменную окружения: OPENAI_API_KEY, AZURE_API_KEY, RECRAFT_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY, BFL_API_KEY, AWS_ACCESS_KEY_ID. Для Azure дополнительно нужны AZURE_API_BASE и AZURE_API_VERSION, причём api_version документирован как обязательный для dall-e-3 на Azure.

Модель без vision. Если модель не поддерживает изображения на входе, вызов completion() с блоком image_url не даст осмысленного ответа. Проверьте supports_vision() до вызова или поле supports_vision в ответе /model_group/info.

MIME-тип определён неверно. Для gs://-адресов Vertex AI и изображений без явного типа помогает поле format внутри image_url. Для OpenAI это поле игнорируется, для Anthropic, Bedrock и Vertex AI применяется.

Частые вопросы

Чем отличается image_generation от image_edit?

image_generation() создаёт изображение по текстовому описанию, обязателен только prompt. image_edit() берёт готовый файл и меняет его, обязательны image и prompt. Это разные функции и разные эндпоинты: /v1/images/generations и /v1/images/edits.

Как передать картинку в модель для анализа?

Через completion() с content-массивом. Внутри массива два блока: type: text с вопросом и type: image_url с адресом или base64-строкой. Ответ придёт текстом в choices[].message.content.

Как узнать, поддерживает ли модель изображения на входе?

В SDK вызовите litellm.supports_vision(model="...") — вернётся True или False. Через прокси запросите GET /model_group/info и посмотрите поле supports_vision для нужной группы моделей.

Что считать успешным ответом на генерацию?

Непустой массив data с полем url или b64_json в элементе. При response_format: "b64_json" картинка лежит в base64, поле url остаётся пустым. Код 200 сам по себе изображение не подтверждает.

Где смотреть актуальный набор полей?

На официальных страницах LiteLLM: docs.litellm.ai/docs/image_generation для генерации, docs.litellm.ai/docs/image_edits для редактирования, docs.litellm.ai/docs/completion/vision для vision. Список поддерживаемых моделей и провайдеров — на models.litellm.ai.