API de Visión DeepSeek-V4.1-Flash: Cómo enviar imágenes al modelo multimodal nativo de DeepSeek

El soporte de visión de DeepSeek dejó de ser un proyecto paralelo el 10 de septiembre de 2026. Con el lanzamiento de disponibilidad general de DeepSeek-V4.1-Flash, la entrada de imágenes reside en el modelo principal bajo una única ID, deepseek-flash. No hay una compilación de visión separada ni un sufijo "Exp". La nota de lanzamiento retira tanto deepseek-v4-flash como deepseek-v4-flash-vision-exp; las solicitudes a cualquiera de esos nombres ahora se dirigen a V4.1-Flash.

Esto es importante si construiste sobre el endpoint experimental hace tres semanas. El formato de solicitud contra el que escribiste para V4-Flash-Vision-Exp sigue funcionando, pero el modelo que lee tus imágenes es nuevo: 763B parámetros, con un codificador de visión entrenado desde cero junto con el núcleo de texto. Esta guía cubre lo que significa "multimodal nativo" en la práctica, las tres formas de entregar una imagen, el parámetro detail, el costo de las imágenes y cómo construir una prueba de visión repetible en Apidog que demuestre que el nombre antiguo y el nuevo se comportan de la misma manera.

En resumen

• ID del modelo: deepseek-flash. El nombre heredado deepseek-v4-flash-vision-exp aún se resuelve, pero es atendido por V4.1-Flash.
• Las imágenes van en el array content del mensaje de usuario: una URL de datos base64 (hasta 32 MiB), una URL externa (hasta 8.192 caracteres) o un ID de archivo.
• Campo detail opcional: low, high (alias original) o auto.
• Benchmarks de visión, según DeepSeek: MMMU-Pro 56.5, CVBench 77.9, DocVQA 95.6, RefCOCO 86.0.
• La tarificación es la tarifa estándar de Flash: $0.15 por cada 1M de tokens de entrada con fallo de caché en horas valle, $0.30 en horas pico.
• El contexto es de 1M de tokens, la salida máxima es de 384K, igual que las llamadas solo de texto.

Qué significa "multimodal nativo" aquí

Vision-Exp adjuntaba un codificador de imágenes a un modelo de texto ya terminado. V4.1-Flash lo hace al revés. Según la ficha del modelo, las imágenes formaron parte del corpus de pre-entrenamiento de 45T-tokens desde el principio, y el codificador es un nuevo DeepSeek-ViT entrenado desde cero en lugar de tomado de un modelo de visión existente. El núcleo es una mezcla de expertos de 552B parámetros; con el codificador adjunto, el total alcanza los 763B. Solo 8B parámetros están activos durante el pre-llenado y 16B durante la decodificación, lo que explica cómo un modelo tan grande sigue funcionando a velocidad y precios Flash. V4-Flash, el modelo solo de texto en la guía de la API V4-Flash, fue la base que Vision-Exp extendió.

DeepSeek informa estas cuatro puntuaciones de visión en la ficha del modelo. Son las mediciones propias del proveedor, así que trátalas como afirmaciones hasta que hayas pasado tus propios documentos por la API.

Para los usuarios de la API, DocVQA y RefCOCO son las filas a las que prestar atención. DocVQA es la puntuación detrás de la extracción de facturas y formularios. RefCOCO es el anclaje: dada la frase "el botón Enviar debajo del campo de correo electrónico", ¿puede el modelo encontrarlo? Esa habilidad convierte las capturas de pantalla en acciones de agente. La visión general de la arquitectura cubre el lado del texto y el informe técnico con más profundidad.

El formato de solicitud: tres formas de entregar una imagen

Nada cambió en el formato de la comunicación. Llama al endpoint de Chat Completions en https://api.deepseek.com con el SDK de OpenAI, coloca las partes de texto e imagen en el mismo array content y configura el modelo como deepseek-flash. Aquí tienes una llamada completa que convierte una factura en 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")

Esa es la opción uno, base64 en línea: autocontenida, limitada a 32 MiB por imagen, y adecuada para llamadas únicas o archivos que nunca salen de tu red.

La opción dos es una URL externa. Si la imagen ya tiene un enlace público en un CDN o en almacenamiento de objetos, omite la codificación y pasa el enlace (hasta 8.192 caracteres). Esta solicitud curl lee un gráfico de precios alojado:

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"}}
      ]
    }]
  }'

La opción tres es un ID de archivo. Sube la imagen una vez a través de la API de Archivos de DeepSeek, luego referénciala con una parte file en lugar de volver a enviar los bytes:

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

Elige los ID de archivo siempre que la misma imagen aparezca en más de una solicitud, como una captura de pantalla de referencia que cada prueba en una suite compara. El recorrido completo de los parámetros se encuentra en la guía de la API V4.1-Flash.

El parámetro 'detail' y los límites de solicitud

detail es opcional y reside dentro del objeto image_url. Los tres valores se trasladaron de Vision-Exp:

• "low" reduce la escala a 512x512. Es la opción más barata y rápida; funciona bien para preguntas como "¿es esto un panel de control o un recibo?".
• "high" (alias "original") mantiene la resolución original. Úsala para documentos densos, letra pequeña y capturas de pantalla de interfaz de usuario donde una etiqueta de 12px es importante.
• "auto" permite que la API elija.

Los límites que encontrarás primero:

La guía de Vision-Exp enumeraba límites adicionales en el recuento de imágenes, el tamaño del cuerpo y las dimensiones de los píxeles. Esos se publicaron para el modelo experimental; consulta el registro de cambios de la API antes de depender de ellos para V4.1-Flash. Una regla no ha cambiado: las imágenes pertenecen a los mensajes del usuario. Si colocas una en un mensaje del sistema o del asistente, obtendrás un error 400.

Cuánto cuestan las imágenes en deepseek-flash

No hay un precio de visión separado. Las imágenes se facturan como tokens de entrada a la tarifa Flash de la página de precios, efectiva desde el 10 de septiembre de 2026 a las 04:00 UTC:

Las horas pico son de lunes a viernes, de 01:00 a 04:00 y de 06:00 a 10:00 UTC; las horas valle tienen la mitad de precio. En Vision-Exp, cada imagen se facturaba con un máximo de 384 tokens de entrada. Si ese límite se mantiene sin cambios en V4.1-Flash es [VERIFICAR] contra la documentación. El usage.prompt_tokens de cada respuesta informa el recuento real, por eso el ejemplo de Python lo imprime.

Si el límite de 384 tokens se mantiene, una imagen cuesta aproximadamente $0.000115 en las tarifas pico de fallo de caché y la mitad de eso en horas valle, por lo que mil facturas ascenderían a aproximadamente $0.12 de entrada de imagen. La salida domina cualquier pipeline real: 400 tokens de JSON por factura cuestan aproximadamente cuatro veces más que la imagen en sí en horas pico. La palanca es un esquema de respuesta ajustado, no la reducción de escala de la imagen. Los cálculos de horas pico, horas valle y acierto de caché se explican en Precios de DeepSeek-V4.1-Flash explicados; la versión corta es que la entrada con fallo de caché es un 32% más barata de lo que Vision-Exp cobraba en agosto.

Tres casos de uso que valen la pena para un piloto

Extracción de documentos. Facturas, recibos, albaranes, formularios de seguros. Solicita un esquema JSON fijo, envíalo con detail: "high" y verifica que las partidas sumen el subtotal antes de confiar en un registro.

Capturas de pantalla de la interfaz de usuario para probar aserciones. Captura una página después de un despliegue, pregunta si los elementos esperados están presentes y dónde, y convierte la respuesta en un aprobado/fallo. RefCOCO es el benchmark relevante: el trabajo es encontrar elementos nombrados.

Lectura de gráficos. Extrae los nombres de las series, las etiquetas de los ejes y los valores trazados de una imagen de gráfico a una tabla. Las líneas superpuestas o los ejes sin etiquetar requieren una verificación manual por parte de un humano.

Probando el endpoint de visión en Apidog

Las solicitudes de visión son difíciles de iterar manualmente: un blob base64 hace que el cuerpo JSON sea ilegible, y comparar la configuración de detail implica manejar cargas útiles casi idénticas. Aquí tienes un bucle que se mantiene legible y se vuelve a ejecutar con un solo clic.

1. Configura un entorno. Crea variables para base_url, api_key, model (deepseek-flash) y detail (high). Cambiar el nivel de detalle más tarde es un cambio en un menú desplegable, no una edición de la carga útil.
2. Codifica la imagen en un script previo a la solicitud. En lugar de pegar base64 en el cuerpo, deja que un script previo a la solicitud codifique el archivo de ejemplo y escriba el resultado en una variable image_b64. El cuerpo visible se mantiene de unas pocas líneas, y cambiar la imagen de prueba significa cambiar una ruta.
3. Guarda el cuerpo de la solicitud con variables. Usa "model": "{{model}}", "detail": "{{detail}}" y "url": "data:image/png;base64,{{image_b64}}". Guárdalo como un caso de prueba para que sea reutilizable.
4. Afirma sobre la forma JSON. Afirma que la respuesta se analiza como JSON, que invoice_number es una cadena no vacía, que line_items es un array no vacío, que total es un número y que usage.prompt_tokens está por debajo de un umbral que elijas. Eso convierte "parece bien" en un aprobado/fallo.
5. Confirma que el nombre heredado se enruta al mismo modelo. Duplica la solicitud guardada, establece model en deepseek-v4-flash-vision-exp y ejecuta ambos en un escenario de prueba contra la misma imagen. Compara los campos extraídos y el recuento de usage.prompt_tokens. Los resultados coincidentes confirman lo que indica la nota de lanzamiento: ambos nombres apuntan a V4.1-Flash, por lo que puedes renombrar en tu configuración con confianza.
6. Ejecútalo en CI. Ejecuta el escenario con apidog-cli en cada cambio de prompt, para que una regresión del esquema aparezca antes de la producción.

Descarga Apidog y la configuración tarda unos quince minutos en construirse. Apidog prueba la capa de la API, no el host del modelo, por lo que el mismo escenario funciona contra cualquier endpoint compatible con OpenAI que uses más tarde.

Dónde te deja esto

El endpoint experimental probó el formato de solicitud y el precio. V4.1-Flash mantiene ambos e incorpora un modelo que vio imágenes desde su primer token de entrenamiento. Apunta tu cliente a deepseek-flash, mantén detail en una variable, afirma el JSON que recibes y ejecuta el nombre heredado a través del mismo escenario de Apidog una vez para confirmar el reenvío. Después de eso, la única pregunta que queda es la precisión en tus propios documentos, y ahora tienes una prueba que la responde.