DeepSeek-V4.1-Flash Vision API: Como Enviar Imagens para o Modelo Multimodal Nativo da DeepSeek

O suporte à visão do DeepSeek deixou de ser um projeto paralelo em 10 de setembro de 2026. Com o lançamento GA do DeepSeek-V4.1-Flash, a entrada de imagens reside no modelo principal sob um único ID, deepseek-flash. Não há uma versão de visão separada e nenhum sufixo "Exp". A nota de lançamento aposenta tanto deepseek-v4-flash quanto deepseek-v4-flash-vision-exp; as solicitações para qualquer um dos nomes agora chegam ao V4.1-Flash.

Isso importa se você construiu no endpoint experimental três semanas atrás. O formato de solicitação que você usou para V4-Flash-Vision-Exp ainda funciona, mas o modelo que lê suas imagens é novo: 763 bilhões de parâmetros, com um codificador de visão treinado do zero ao lado do backbone de texto. Este guia aborda o que "multimodal nativo" significa na prática, as três formas de entregar uma imagem, o parâmetro detail, o custo das imagens e como construir um teste de visão repetível no Apidog que prova que o nome antigo e o novo se comportam da mesma maneira.

TL;DR

• ID do modelo: deepseek-flash. O nome legado deepseek-v4-flash-vision-exp ainda resolve, mas é servido pelo V4.1-Flash.
• As imagens vão na matriz content da mensagem do usuário: uma URL de dados base64 (até 32 MiB), uma URL externa (até 8.192 caracteres) ou um ID de arquivo.
• Campo detail opcional: low, high (alias original) ou auto.
• Benchmarks de visão, conforme relatado pelo DeepSeek: MMMU-Pro 56.5, CVBench 77.9, DocVQA 95.6, RefCOCO 86.0.
• O preço é a taxa padrão do Flash: $0.15 por 1M de tokens de entrada cache-miss fora do horário de pico, $0.30 no pico.
• O contexto é de 1M de tokens, saída máxima de 384K, o mesmo que as chamadas apenas de texto.

O que "multimodal nativo" significa aqui

O Vision-Exp anexava um codificador de imagem a um modelo de texto finalizado. O V4.1-Flash faz o contrário. De acordo com o cartão do modelo, as imagens faziam parte do corpus de pré-treinamento de 45T tokens desde o início, e o codificador é um novo DeepSeek-ViT treinado do zero em vez de emprestado de um modelo de visão existente. O backbone é uma mistura de especialistas de 552 bilhões de parâmetros; com o codificador anexado, o total atinge 763 bilhões. Apenas 8 bilhões de parâmetros estão ativos durante o preenchimento e 16 bilhões durante a decodificação, o que explica como um modelo tão grande ainda funciona na velocidade e nos preços do Flash. O V4-Flash, o modelo apenas de texto no guia da API V4-Flash, foi a base que o Vision-Exp estendeu.

DeepSeek relata essas quatro pontuações de visão no cartão do modelo. São as próprias medições do fornecedor, então trate-as como afirmações até que você mesmo as tenha testado com seus próprios documentos através da API.

Para usuários de API, DocVQA e RefCOCO são as linhas a serem observadas. A QA de documentos é a pontuação por trás da extração de faturas e formulários. RefCOCO é o "grounding": dada a frase "o botão Enviar abaixo do campo de e-mail", o modelo consegue encontrá-lo? Essa habilidade transforma capturas de tela em ações do agente. A visão geral da arquitetura cobre o lado do texto e o relatório técnico em mais profundidade.

O formato da solicitação: três maneiras de entregar uma imagem

Nada no formato da comunicação mudou. Chame o endpoint de Chat Completions em https://api.deepseek.com com o SDK do OpenAI, coloque as partes de texto e imagem na mesma matriz content e defina o modelo como deepseek-flash. Aqui está uma chamada completa que transforma uma fatura em JSON:

import base64, json
from openai import OpenAI

client = OpenAI(api_key="YOUR_DEEPSEEK_KEY", base_url="https://api.deepseek.com")

with open("invoice-2026-0912.png", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

schema_hint = (
    "Return only JSON with keys: invoice_number (string), issue_date (YYYY-MM-DD), "
    "vendor (string), currency (string), line_items (array of {description, quantity, "
    "unit_price, amount}), subtotal, tax, total (numbers)."
)

response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": schema_hint},
            {
                "type": "image_url",
                "image_url": {
                    "url": f"data:image/png;base64,{image_b64}",
                    "detail": "high",
                },
            },
        ],
    }],
    temperature=1.0,
    max_tokens=2048,
)

invoice = json.loads(response.choices[0].message.content)
print(invoice["invoice_number"], invoice["total"])
print(response.usage.prompt_tokens, "prompt tokens")

Essa é a opção um, base64 inline: autocontida, limitada a 32 MiB por imagem e ideal para chamadas únicas ou arquivos que nunca saem da sua rede.

A opção dois é uma URL externa. Se a imagem já tiver um link público em uma CDN ou no armazenamento de objetos, pule a codificação e passe o link (até 8.192 caracteres). Esta solicitação curl lê uma tabela de preços hospedada:

curl https://api.deepseek.com/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "List every plan name and its monthly price from this chart as a JSON array."},
        {"type": "image_url", "image_url": {"url": "https://assets.example-saas.com/pricing/plans-q3.png", "detail": "auto"}}
      ]
    }]
  }'

A opção três é um ID de arquivo. Faça o upload da imagem uma vez através da API de Arquivos do DeepSeek e, em seguida, referencie-a com uma parte file em vez de reenviar os bytes:

{"type": "file", "file": {"file_id": "file-api-xxxxxxxxxxxxxxxx"}}

Escolha IDs de arquivo sempre que a mesma imagem aparecer em mais de uma solicitação, como uma captura de tela de referência que todo teste em um conjunto compara. A explicação completa dos parâmetros está no guia da API V4.1-Flash.

O parâmetro detail e os limites de solicitação

detail é opcional e reside dentro do objeto image_url. Os três valores herdados do Vision-Exp:

• "low" reduz para 512x512. Mais barato e mais rápido; bom para perguntas como "isso é um painel ou um recibo".
• "high" (alias "original") mantém a resolução da fonte. Use-o para documentos densos, letras miúdas e capturas de tela de interface de usuário onde um rótulo de 12px importa.
• "auto" permite que a API escolha.

Os tetos que você encontrará primeiro:

O guia do Vision-Exp listava outros limites para contagem de imagens, tamanho do corpo e dimensões em pixels. Esses foram publicados para o modelo experimental; verifique o changelog da API antes de depender deles para o V4.1-Flash. Uma regra não mudou: as imagens pertencem às mensagens do usuário. Coloque uma em uma mensagem do sistema ou do assistente e você receberá um erro 400.

Quanto as imagens custam no deepseek-flash

Não há um preço separado para visão. As imagens são cobradas como tokens de entrada à taxa do Flash da página de preços, efetiva em 10 de setembro de 2026 às 04:00 UTC:

As horas de pico são de segunda a sexta-feira, das 01:00 às 04:00 e das 06:00 às 10:00 UTC; fora do pico é metade do preço. No Vision-Exp, cada imagem era cobrada em não mais de 384 tokens de entrada. Se esse limite se mantém inalterado para o V4.1-Flash, isso precisa ser [VERIFICADO] em relação à documentação. O usage.prompt_tokens de cada resposta reporta a contagem real, por isso o exemplo em Python a imprime.

Se o limite de 384 tokens se mantiver, uma imagem custa cerca de $0.000115 na taxa de pico de erro de cache e metade disso fora do pico, então mil faturas chegam a aproximadamente $0.12 de entrada de imagem. A saída domina qualquer pipeline real: 400 tokens de JSON por fatura custam cerca de quatro vezes mais do que a imagem em si no pico. A alavanca é um esquema de resposta apertado, não a redução de escala da imagem. A matemática de pico, fora do pico e acerto de cache é detalhada em DeepSeek-V4.1-Flash pricing explained; a versão curta é que a entrada de erro de cache é 32% mais barata do que o Vision-Exp cobrava em agosto.

Três casos de uso que valem um piloto

• Extração de documentos. Faturas, recibos, notas de entrega, formulários de seguro. Solicite um esquema JSON fixo, envie com detail: "high" e verifique se os itens de linha somam o subtotal antes de confiar em um registro.
• Capturas de tela de UI para testar asserções. Capture uma página após um deploy, pergunte se os elementos esperados estão presentes e onde, e transforme a resposta em um passa/falha. RefCOCO é o benchmark relevante: o trabalho é encontrar elementos nomeados.
• Leitura de gráficos. Extraia nomes de séries, rótulos de eixos e valores plotados de uma imagem de gráfico para uma tabela. Linhas sobrepostas ou eixos sem rótulo exigem uma verificação humana.

Testando o endpoint de visão no Apidog

As solicitações de visão são difíceis de iterar manualmente: um blob base64 torna o corpo JSON ilegível, e comparar as configurações de detail significa manipular payloads quase idênticos. Aqui está um loop que permanece legível e pode ser executado novamente com um clique.

1. Configure um ambiente. Crie variáveis para base_url, api_key, model (deepseek-flash) e detail (high). Mudar o nível de detalhe posteriormente é uma alteração de menu suspenso, não uma edição de payload.
2. Codifique a imagem em um script de pré-requisição. Em vez de colar base64 no corpo, deixe um script de pré-requisição codificar o arquivo de amostra e escrever o resultado em uma variável image_b64. O corpo visível permanece com algumas linhas, e trocar a imagem de teste significa mudar um caminho.
3. Salve o corpo da solicitação com variáveis. Use "model": "{{model}}", "detail": "{{detail}}" e "url": "data:image/png;base64,{{image_b64}}". Salve-o como um caso de teste para que seja reutilizável.
4. Afirme a forma do JSON. Afirme que a resposta é analisada como JSON, invoice_number é uma string não vazia, line_items é um array não vazio, total é um número e usage.prompt_tokens está abaixo de um limite que você escolher. Isso transforma "parece bom" em um passa/falha.
5. Confirme que o nome legado roteia para o mesmo modelo. Duplique a solicitação salva, defina model como deepseek-v4-flash-vision-exp e execute ambos em um cenário de teste contra a mesma imagem. Compare os campos extraídos e a contagem de usage.prompt_tokens. Resultados correspondentes confirmam o que a nota de lançamento afirma: ambos os nomes atingem o V4.1-Flash, então você pode renomear em sua configuração com confiança.
6. Execute-o no CI. Execute o cenário com apidog-cli a cada alteração de prompt, para que uma regressão de esquema seja identificada antes da produção.

Baixe o Apidog e a configuração leva cerca de quinze minutos para ser construída. O Apidog testa a camada da API, não o host do modelo, então o mesmo cenário funciona contra qualquer endpoint compatível com OpenAI que você rotear posteriormente.

Onde isso te deixa

O endpoint experimental provou o formato da solicitação e o preço. O V4.1-Flash mantém ambos e troca por um modelo que viu imagens desde seu primeiro token de treinamento. Aponte seu cliente para deepseek-flash, mantenha detail em uma variável, afirme o JSON que você recebe de volta e execute o nome legado através do mesmo cenário do Apidog uma vez para confirmar o redirecionamento. Depois disso, a única questão restante é a precisão em seus próprios documentos, e agora você tem um teste que a responde.