Guia da API DeepSeek V4 Flash Vision Exp: limites e exemplos

O endpoint deepseek-v4-flash-vision-exp leva entrada de imagens à linha V4 Flash. Mas o rótulo experimental merece atenção: as evidências citadas no lançamento não comprovam confiabilidade em produção. Antes de adotá-lo como padrão, faça um piloto monitorado e mantenha um fallback.

Decisão rápida: qual caminho seguir?

O DeepSeek V4 Flash Vision Exp faz sentido quando um fluxo já baseado em V4 Flash precisa interpretar screenshots, gráficos, documentos ou outras imagens por uma interface compatível com API. Para decisões visuais de alto risco ou sensíveis à identidade, valide o caso de uso separadamente e mantenha uma alternativa disponível.

O identificador exato é deepseek-v4-flash-vision-exp. A DeepSeek classifica o modelo como experimental e informa que ele está disponível na plataforma de API desde 21 de agosto de 2026, conforme seu changelog oficial. A nota de lançamento aponta paridade com o V4 Flash em recursos exclusivamente textuais e uma grande melhora em benchmarks de agentes que exigem compreensão visual.

Como enviar uma imagem com Chat Completions

Na requisição OpenAI-compatible de Chat Completions, texto e imagem ficam em um array content dentro de uma mensagem user. O guia oficial de Vision detalha o comportamento específico do modelo: enviar uma imagem ao deepseek-v4-flash comum retorna erro 400.

import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

with open("chart.png", "rb") as image_file:
    encoded = base64.b64encode(image_file.read()).decode("utf-8")

response = client.chat.completions.create(
    model="deepseek-v4-flash-vision-exp",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Extract the three trends from this chart."},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/png;base64,{encoded}",
                        "detail": "original",
                    },
                },
            ],
        }
    ],
)

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

O Chat Completions aceita imagens em mensagens de usuário. Deixe a imagem e a instrução no mesmo array de conteúdo para que o modelo receba, ao mesmo tempo, o contexto visual e a tarefa.

Escolha a melhor forma de transportar a imagem

Base64 para arquivos locais pequenos

Base64 é o caminho mais simples para uma imagem local e pontual. Ele dispensa hospedagem pública, mas os dados codificados contam para o limite de 48 MiB do corpo da requisição, e a imagem de origem é limitada a 32 MiB.

Use esse formato para uploads isolados de usuários ou workers, não para imagens reutilizadas em lote.

URL pública para assets hospedados

URLs públicas http ou https mantêm as requisições leves, mas precisam estar acessíveis, ter menos de 8.192 caracteres, permitir download em até 60 segundos e apontar para arquivos de no máximo 32 MiB. URLs privadas, expiradas ou internas podem falhar antes mesmo de a DeepSeek buscar a imagem.

Files API para reutilização ou arquivos maiores

Envie a imagem pela Files API e depois use o ID retornado na requisição de visão:

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

Um arquivo referenciado pode ter até 64 MiB por imagem e evita reenviar os mesmos bytes a cada chamada. Em troca, há uma etapa adicional de upload e gestão do ciclo de vida do arquivo; associe o ID retornado à chave que o criou, em vez de tratá-lo como um link público de compartilhamento.

Na prática, a Files API é a melhor opção quando o arquivo passa de 32 MiB, a requisição pode ultrapassar 48 MiB ou várias etapas de um agente precisam analisar a mesma imagem.

Defina o nível de detalhe antes de pagar por ele

O campo detail está disponível em entradas image_url e em partes de imagem da Responses API. O comportamento abaixo segue o guia oficial de Vision da DeepSeek.

A DeepSeek redimensiona as imagens antes da inferência. Segundo o guia de Vision, cada imagem tem um teto de 384 tokens de imagem, e cada uma é contabilizada de forma independente. Uma imagem de origem muito grande não consome necessariamente uma quantidade proporcional de tokens após o redimensionamento, embora arquivos grandes ainda possam atingir os limites de upload e tamanho da requisição.

A página oficial de Modelos e Preços lista o deepseek-v4-flash-vision-exp com as mesmas tarifas por token do V4 Flash: US$ 0,007 por 1M de tokens de entrada em cache e US$ 0,22 por 1M de tokens de entrada sem cache no horário de menor demanda; no pico, as tarifas são US$ 0,014 e US$ 0,44. A saída custa US$ 0,66 fora do pico e US$ 1,32 no pico. Tokens de imagem são cobrados como tokens de entrada, portanto a quantidade de imagens e a escolha de detalhe devem entrar na estimativa de custos.

Limites que realmente provocam falhas na API

Duas restrições passam despercebidas com facilidade. Apenas o deepseek-v4-flash-vision-exp aceita imagens, e blocos de imagem em mensagens system ou assistant falham no Chat Completions. Se uma imagem for enviada a um modelo sem visão, a DeepSeek documenta a mensagem de erro 400 como This model does not support image.

O mesmo modelo em três interfaces de API

A DeepSeek documenta o modelo em três interfaces no seu guia de Vision:

As três interfaces aceitam Base64, URLs públicas e referências da Files API, mas os tipos de conteúdo são diferentes. Não copie o bloco de Chat Completions sem alterações para a Responses API.

O que os dados de lançamento mostram — e o que não mostram

O changelog de 21 de agosto da DeepSeek informa bons resultados de lançamento, incluindo Terminal Bench 2.1 com 83,9 e Chartography com 64,3 em p0.95. São resultados reportados pelo fornecedor, não reproduções independentes; o lançamento também observa que o V4 Flash exclusivamente textual ignora elementos multimodais em duas avaliações visuais.

Como os benchmarks de lançamento foram reportados pelo fornecedor, valide as tarefas visuais relevantes para sua aplicação antes de direcionar tráfego de produção.

Vale usar em produção?

Use o DeepSeek V4 Flash Vision Exp em um piloto controlado se sua carga envolve análise de screenshots, extração de gráficos, triagem de documentos ou um agente que precisa inspecionar estado visual. O preço equivalente ao Flash e os três caminhos de entrada tornam a avaliação barata, enquanto o limite de 384 tokens por imagem oferece um ponto de partida concreto para modelar custos.

Enquanto o modelo continuar experimental e as evidências de lançamento citadas não estabelecerem confiabilidade nesses cenários, não o adote como único backend para verificação de identidade, decisões de segurança, interpretação médica ou outros julgamentos visuais de alta consequência. Coloque um fallback atrás da mesma interface e registre a origem da imagem, a configuração de detail, o uso de entrada e saída, a latência, as tentativas, e o sucesso da tarefa.

Antes de direcionar tráfego de produção, teste pelo menos:

1. Textos pequenos em screenshots com detalhe low e original.
2. Gráficos com rótulos, legendas e eixos densos.
3. Várias imagens em uma única requisição.
4. URLs de imagem privadas e lentas.
5. Chamadas de ferramentas após a inspeção visual.
6. Prompts de identidade incorretos ou ambíguos.
7. O comportamento do fallback após um erro 400, timeout ou resposta de imagem malformada.

Perguntas frequentes sobre a API DeepSeek V4 Flash Vision Exp

Qual é o nome exato do modelo?

Use deepseek-v4-flash-vision-exp. O changelog da DeepSeek de 21 de agosto de 2026 o identifica como um modelo multimodal experimental na plataforma de API.

O preço é igual ao do V4 Flash?

Sim. A página de preços da DeepSeek lista as mesmas tarifas de tokens para acertos de cache, falhas de cache e saída no Vision Exp e no V4 Flash. Tokens de imagem são cobrados como entrada, com até 384 tokens de imagem por imagem após o redimensionamento.

Ele gera imagens?

O guia oficial de Vision documenta compreensão de imagens, não geração. Trate esse endpoint como voltado apenas à compreensão até que a DeepSeek publique suporte específico para geração.

Por que minha requisição retorna erro 400?

Verifique a string do modelo, o papel da mensagem, o tipo de bloco de conteúdo, o tamanho do arquivo e o formato da imagem. Imagens enviadas a um modelo sem visão ou posicionadas em papéis de mensagem não suportados podem disparar o erro documentado This model does not support image.