input_image срещу image_url: Двата синтаксиса
На тази страница
Две 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 – за нов код модерният синтаксис е задължителен.
Добър формат, добри детайли, добър синтаксис: визията се управлява като текст – до последния токен.