Ir para o conteúdo principal
Português— Escolher um idioma
Menu

input_image vs image_url: as duas sintaxes

Aula 12 de 12 Atualizada a 30 de julho de 2026 Iniciante
Nesta página
  1. Duas APIs, duas sintaxes
  2. API de Respostas: input_image (recomendado)
  3. API de Conclusões de Chat: image_url (legado)
  4. Tabela comparativa
  5. Erros de sintaxe comuns
  6. Quando utilizar cada API
  7. Pontos-chave
  8. Teste os seus conhecimentos

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ão image_url)
  • O URL ou Data URI é inserido diretamente em image_url (sem objeto aninhado)
  • detail situa-se ao mesmo nível que image_url
  • O texto utiliza o tipo input_text
  • O array input substitui o array messages das 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ão input_image)
  • O URL situa-se num objeto aninhado image_url.url (aninhamento duplo)
  • detail reside dentro do objeto image_url
  • O texto utiliza o tipo text (não input_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: false ou 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 utiliza image_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_image vs image_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.