input_image vs image_url: as duas sintaxes
Nesta página
Duas APIs, duas sintaxes
A xAI disponibiliza dois endpoints para interagir com o Grok, e cada um utiliza uma sintaxe diferente para o envio de imagens. Compreender estas diferenças é essencial para escrever código correto e evitar erros frustrantes.
API de Respostas: input_image (recomendado)
A API de Respostas é o novo endpoint principal da xAI. As novas funcionalidades são aqui implementadas em primeiro lugar. Esta é a API que deve priorizar para qualquer novo projeto.
Sintaxe
{
"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."
}
]
}
Características
- O tipo é
input_image(nãoimage_url) - O URL ou Data URI é inserido diretamente em
image_url(sem objeto aninhado) detailsitua-se ao mesmo nível queimage_url- O texto utiliza o tipo
input_text - O array
inputsubstitui o arraymessagesdas Conclusões de Chat (Chat Completions)
SDK Python
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)
API de Conclusões de Chat: image_url (legado)
A API de Conclusões de Chat é o endpoint legado, mantido para compatibilidade com os SDKs OpenAI existentes. Se estiver a migrar código escrito para a OpenAI, esta API facilita a transição.
Sintaxe
{
"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."
}
]
}
]
}
Características
- O tipo é
image_url(nãoinput_image) - O URL situa-se num objeto aninhado
image_url.url(aninhamento duplo) detailreside dentro do objetoimage_url- O texto utiliza o tipo
text(nãoinput_text) - As mensagens possuem um
role(system, user, assistant)
Python com SDK OpenAI
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)
Tabela comparativa
| Aspeto | API de Respostas | Conclusões de Chat |
|---|---|---|
| Estado | Principal (recomendado) | Legado (compatibilidade) |
| Tipo de imagem | input_image | image_url |
| Tipo de texto | input_text | text |
| URL da imagem | image_url: "..." | image_url.url: "..." |
| Gestão de estado | Com estado (previous_response_id) | Sem estado (reenviar tudo) |
| Armazenamento | store: true/false | Não (sem estado) |
| Ferramentas do servidor | web_search, x_search, code_interpreter | Limitado |
Erros de sintaxe comuns
Erro 1: Misturar formatos
# ERRADO — Sintaxe de Conclusões de Chat na API de Respostas
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Não!
]
# CORRETO — Sintaxe da API de Respostas
input=[
{"type": "input_image", "image_url": "..."} # Sim!
]
Erro 2: Esquecer a estrutura aninhada nas Conclusões de Chat
# ERRADO — URL direto nas Conclusões de Chat
{"type": "image_url", "image_url": "https://..."} # Não!
# CORRETO — Objeto aninhado
{"type": "image_url", "image_url": {"url": "https://..."}} # Sim!
Erro 3: Usar “text” em vez de “input_text”
# ERRADO — Tipo "text" na API de Respostas
input=[
{"type": "text", "text": "Describe."} # Não!
]
# CORRETO
input=[
{"type": "input_text", "text": "Describe."} # Sim!
]
Quando utilizar cada API
- Novo projeto: utilize a API de Respostas. Oferece acesso às funcionalidades mais recentes e ao armazenamento de conversas.
- Migração a partir da OpenAI: comece com as Conclusões de Chat para minimizar alterações de código e migre gradualmente para a API de Respostas.
- Imagens sensíveis: API de Respostas com
store: falseou API de Conclusões de Chat (inerentemente sem estado).
Pontos-chave
- A API de Respostas utiliza
input_image+input_text; a API de Conclusões de Chat utilizaimage_url+text - A estrutura do URL difere: direta na API de Respostas, aninhada nas Conclusões de Chat
- A API de Respostas é a escolha recomendada para todo o novo desenvolvimento
- Nunca misture sintaxes de ambas as APIs no mesmo pedido
- Verifique sempre o tipo de objeto (
input_imagevsimage_url) para evitar erros silenciosos
Teste os seus conhecimentos
Visão da API xAI: formatos, tokens, sintaxes — está tudo no lugar?
1. Como envia uma imagem para a API?
Resposta: Via URL ou Base64, numa mensagem de conteúdo misto — respeitando o formato documentado e as restrições de tamanho.
2. O que controla o parâmetro detail (auto, low, high)?
Resposta: A granularidade da análise e o custo: low poupa tokens para casos de uso grosseiros, high maximiza a precisão (OCR, detalhes finos), auto deixa a API decidir.
3. Como é calculado o custo de uma imagem?
Resposta: Em tokens de imagem — de 256 a 1792, dependendo da resolução e do detalhe: dimensionar as suas imagens e o seu nível de detalhe é a primeira alavanca de otimização.
4. O que permite a comparação de múltiplas imagens?
Resposta: O envio de várias imagens num único pedido e o raciocínio sobre as mesmas — diferenças, evoluções, consistência — sem limite no número de imagens por pedido.
5. input_image ou image_url: qual escolher?
Resposta: input_image é a sintaxe moderna da API de Respostas; image_url persiste como legado das Conclusões de Chat — para novo código, a sintaxe moderna é obrigatória.
Bom formato, bom detalhe, boa sintaxe: a visão é pilotada como o texto — até ao token.