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

input_image срещу image_url: Двата синтаксиса

Урок 12 от 12 Обновен 30 юли 2026 г. Начинаещ
На тази страница
  1. Две API, два синтаксиса
  2. Responses API: input_image (препоръчително)
  3. Chat Completions API: image_url (остаряло)
  4. Сравнителна таблица
  5. Чести синтактични грешки
  6. Кога да използвате кое API
  7. Ключови изводи
  8. Проверете знанията си

Две API, два синтаксиса

xAI предлага две крайни точки (endpoints) за взаимодействие с Grok и всяка използва различен синтаксис за изпращане на изображения. Разбирането на тези разлики е от съществено значение за написването на коректен код и избягването на досадни грешки.

Responses API: input_image (препоръчително)

Responses API е новата основна крайна точка на xAI. Новите функции се добавят първо тук. Това е API, което трябва да приоритизирате за всеки нов проект.

Синтаксис

{
  "model": "grok-4.5",
  "store": false,
  "input": [
    {
      "type": "input_image",
      "image_url": "https://exemple.com/photo.jpg",
      "detail": "high"
    },
    {
      "type": "input_text",
      "text": "Describe this image."
    }
  ]
}

Характеристики

  • Типът е input_image (не image_url)
  • URL адресът или Data URI отиват директно в image_url (без вложен обект)
  • detail е на същото ниво като image_url
  • Текстът използва типа input_text
  • Масивът input замества масива messages от Chat Completions

Python SDK

response = client.responses.create(
    model="grok-4.5",
    input=[
        {
            "type": "input_image",
            "image_url": "https://exemple.com/photo.jpg",
            "detail": "high"
        },
        {
            "type": "input_text",
            "text": "Describe this image."
        }
    ],
    store=False
)

print(response.output_text)

Chat Completions API: image_url (остаряло)

Chat Completions API е остарялата крайна точка, поддържана за съвместимост със съществуващите SDK на OpenAI. Ако мигрирате код, написан за OpenAI, това API улеснява прехода.

Синтаксис

{
  "model": "grok-4.5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://exemple.com/photo.jpg",
            "detail": "high"
          }
        },
        {
          "type": "text",
          "text": "Describe this image."
        }
      ]
    }
  ]
}

Характеристики

  • Типът е image_url (не input_image)
  • URL адресът се намира във вложен обект image_url.url (двойно влагане)
  • detail се намира вътре в обекта image_url
  • Текстът използва типа text (не input_text)
  • Съобщенията имат role (system, user, assistant)

Python с OpenAI SDK

from openai import OpenAI

client = OpenAI(
    api_key="your-xai-key",
    base_url="https://api.x.ai/v1"
)

response = client.chat.completions.create(
    model="grok-4.5",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://exemple.com/photo.jpg",
                    "detail": "high"
                }
            },
            {
                "type": "text",
                "text": "Describe this image."
            }
        ]
    }]
)

print(response.choices[0].message.content)

Сравнителна таблица

Аспект API Responses Chat Completions
Статус Основно (препоръчително) Остаряло (съвместимост)
Тип изображение input_image image_url
Тип текст input_text text
URL на изображението image_url: "..." image_url.url: "..."
Управление на състоянието Съхраняващо състоянието (previous_response_id) Без състояние (повторно изпращане на всичко)
Съхранение store: true/false Не (без състояние)
Сървърни инструменти web_search, x_search, code_interpreter Ограничени

Чести синтактични грешки

Грешка 1: Смесване на формати

# ГРЕШНО — Синтаксис на Chat Completions в Responses API
input=[
    {"type": "image_url", "image_url": {"url": "..."}}  # Не!
]

# ПРАВИЛНО — Синтаксис на Responses API
input=[
    {"type": "input_image", "image_url": "..."}  # Да!
]

Грешка 2: Пропускане на вложената структура в Chat Completions

# ГРЕШНО — Директен URL в Chat Completions
{"type": "image_url", "image_url": "https://..."}  # Не!

# ПРАВИЛНО — Вложен обект
{"type": "image_url", "image_url": {"url": "https://..."}}  # Да!

Грешка 3: Използване на “text” вместо “input_text”

# ГРЕШНО — Тип "text" в Responses API
input=[
    {"type": "text", "text": "Describe."}  # Не!
]

# ПРАВИЛНО
input=[
    {"type": "input_text", "text": "Describe."}  # Да!
]

Кога да използвате кое API

  • Нов проект: използвайте Responses API. То осигурява достъп до най-новите функции и съхранение на разговорите.
  • Миграция от OpenAI: започнете с Chat Completions, за да минимизирате промените в кода, след което мигрирайте постепенно към Responses API.
  • Чувствителни изображения: Responses API с store: false или Chat Completions API (по природа без състояние).

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

  • Responses API използва input_image + input_text, докато Chat Completions API използва image_url + text
  • Структурата на URL адреса се различава: директна в Responses, вложена в Chat Completions
  • Responses API е препоръчителният избор за цялата нова разработка
  • Никога не смесвайте синтаксиси от двете API в една и съща заявка
  • Винаги проверявайте типа на обекта (input_image срещу image_url), за да избегнете тихи грешки

Проверете знанията си

API за визия на xAI: формати, токени, синтаксиси – всичко на място ли е?

1. Как изпращате изображение до API?

Отговор: Чрез URL адрес или Base64, в съобщение със смесено съдържание – спазвайки документираните ограничения за формат и размер.

2. Какво контролира параметърът detail (auto, low, high)?

Отговор: Грануларността на анализа и разходите: low пести токени за груби случаи на употреба, high максимизира прецизността (OCR, фини детайли), auto позволява на API да реши.

3. Как се изчислява цената на едно изображение?

Отговор: В токени за изображения – от 256 до 1792 в зависимост от резолюцията и детайлите: оразмеряването на изображенията и нивото на детайлност е първият лост за оптимизация.

4. Какво позволява сравнението на множество изображения?

Отговор: Изпращането на няколко изображения в една заявка и разсъждаването върху тях – разлики, еволюции, последователност – без ограничение за броя изображения на заявка.

5. input_image или image_url: кое да изберете?

Отговор: input_image е модерният синтаксис на Responses API; image_url продължава да съществува като остаряло решение за Chat Completions – за нов код модерният синтаксис е задължителен.

Добър формат, добри детайли, добър синтаксис: визията се управлява като текст – до последния токен.