Cómo usar deepseek-v4-flash-vision-exp a través de la API de hiapi: curl, Python y una solicitud que funciona

deepseek-v4-flash-vision-exp es un modelo de texto y visión con capacidad de razonamiento en hiapi, accesible a través del endpoint estándar compatible con OpenAI: POST /v1/chat/completions. Puede leer imágenes y texto a la vez, admite el modo JSON y la llamada a funciones/herramientas, y soporta salida en streaming; todo ello mediante la misma estructura de solicitud que cualquier otro modelo de chat de hiapi. Esta guía te llevará por una solicitud que funciona, un comportamiento que suele sorprender (el modelo razona antes de responder, y el proceso de razonamiento consume tu presupuesto de tokens), y prácticas de producción que vale la pena conocer antes de lanzar a producción.

Qué vas a construir

Un script que envía un prompt a deepseek-v4-flash-vision-exp —opcionalmente con una imagen adjunta— y lee la respuesta real, no solo su traza interna de razonamiento.

Requisitos previos: una clave de API de hiapi. Obtén una desde la consola; cada una de las solicitudes a continuación debe incluirla en el encabezado Authorization.

Ejemplo mínimo funcional

curl

curl -s -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-vision-exp",
    "messages": [
      { "role": "user", "content": "Say OK and nothing else." }
    ],
    "max_tokens": 200
  }'

La respuesta simplificada se ve así:

{
  "choices": [
    {
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "OK",
        "reasoning_content": "We need to respond exactly \"OK\" and nothing else. ..."
      }
    }
  ],
  "usage": {
    "completion_tokens": 37,
    "completion_tokens_details": { "reasoning_tokens": 34 },
    "prompt_tokens": 89,
    "total_tokens": 126
  }
}

Hay dos campos que importan aquí: message.content es la respuesta real, mientras que message.reasoning_content es la cadena de pensamiento interna del modelo antes de determinar esa respuesta. usage.completion_tokens_details.reasoning_tokens te indica cuánto presupuesto de max_tokens consumió el proceso de razonamiento: en este ejemplo sencillo, 34 de los 37 tokens de completion se usaron para razonar antes de que el modelo escribiera "OK".

Aquí está la trampa: si configuras max_tokens demasiado bajo, el modelo puede gastar todo el presupuesto en razonar, lo que hace que content sea null y finish_reason sea "length". La misma solicitud con max_tokens: 10 devuelve content: null: el modelo seguía pensando cuando alcanzó el límite. Dale espacio suficiente a este modelo: al menos 150–300 tokens para respuestas breves, y más para contenido que requiera profundidad de razonamiento real.

Python

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "model": "deepseek-v4-flash-vision-exp",
        "messages": [
            {"role": "user", "content": "Say OK and nothing else."},
        ],
        "max_tokens": 200,
    },
    timeout=60,
)
resp.raise_for_status()
message = resp.json()["choices"][0]["message"]
print(message["content"])

Entrada visual

Puedes pasar una imagen junto al texto configurando content como un array de segmentos tipados; image_url acepta cualquier URL de imagen de acceso público:

curl -s -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-vision-exp",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "What color is the dominant background color of this image? One word." },
          { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
        ]
      }
    ],
    "max_tokens": 200
  }'

Con una imagen de prueba real, el modelo devolvió "Beige", y reasoning_content mostró que repasó una descripción visual antes de dar la respuesta de una sola palabra: el mismo patrón de razonar primero y responder después que en las solicitudes de solo texto, solo que basado en la imagen.

Modo JSON y llamada a herramientas

Salida JSON estructurada: añade response_format: {"type": "json_object"} y menciona JSON en el prompt:

{
  "model": "deepseek-v4-flash-vision-exp",
  "messages": [
    { "role": "user", "content": "Return a JSON object with keys name and age for a fictional person." }
  ],
  "response_format": { "type": "json_object" },
  "max_tokens": 300
}

message.content devolverá un string JSON parseable ({"name": "Alex Doe", "age": 30}), mientras que reasoning_content sigue conteniendo el borrador del modelo: parsea solo content, nunca reasoning_content.

Llamada a funciones/herramientas: pasa un array tools estándar al estilo OpenAI:

{
  "model": "deepseek-v4-flash-vision-exp",
  "messages": [
    { "role": "user", "content": "What is the weather in Tokyo right now? Use the get_weather tool." }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }
  ],
  "max_tokens": 300
}

El modelo responde con finish_reason: "tool_calls" y un array tool_calls (que contiene function.name, function.arguments como string JSON, y el call_id que devuelves en turnos posteriores); el ciclo estándar de llamada a funciones de OpenAI funciona sin modificaciones.

Consideraciones para producción

• Reserva presupuesto de max_tokens para el razonamiento, no solo para la respuesta. Este es un modelo de razonamiento: cada respuesta incluye un proceso de reasoning_content antes del content final, y ambos consumen del mismo pool de max_tokens. Revisa usage.completion_tokens_details.reasoning_tokens en tus pruebas iniciales, calibra un límite seguro para tus prompts y comprueba siempre finish_reason: "length" con content null significa que te cortaron a mitad del razonamiento, no que obtuviste una respuesta real.
• El streaming funciona mediante stream: true. A diferencia de algunos modelos de razonamiento de hiapi que fuerzan el streaming, este modelo admite ambos modos. En modo streaming, reasoning_content y content llegan como campos delta independientes en el mismo flujo de chunks; si quieres mostrar el "pensamiento" y la "respuesta" como estados de UI distintos, bufferízalos por separado.
• Los fallos de autenticación se devuelven de forma explícita. Una clave incorrecta o revocada devuelve HTTP 401, con un cuerpo de error que contiene "code": "permission_denied" y un request_id. Ramifica según el campo code, no comparando el string del mensaje, e incluye el request_id al contactar con soporte.
• No muestres reasoning_content al usuario final como si fuera la respuesta. Es contenido de borrador no estructurado, no la respuesta final; especialmente en modo JSON o en llamada a herramientas, solo content (o tool_calls) es lo que debe consumir una máquina.
• La entrada visual acepta URL públicas, no base64 en línea. image_url.url debe ser accesible por los servidores de hiapi; antes de enviar la solicitud, aloja la imagen tú mismo o usa una URL que controles.

Lecturas relacionadas

• Página del modelo deepseek-v4-flash-vision-exp: referencia completa de parámetros y precios en tiempo real
• Documentación de la API de hiapi: autenticación, otras familias de modelos y la lista completa de endpoints
• Precios de hiapi: tarifas por token de deepseek-v4-flash-vision-exp y de todos los demás modelos
• Guía de la API de gpt-6-astra: un segundo modelo de razonamiento en hiapi, con una forma de integración distinta (solo streaming, API Responses) que vale la pena comparar

Preguntas frecuentes

¿deepseek-v4-flash-vision-exp admite entrada visual? Sí. Envía un content en forma de array que contenga un segmento text y uno o más segmentos image_url, cada uno apuntando a una URL de imagen de acceso público. El modelo razona primero sobre la imagen, igual que con el texto, y después responde.

¿Por qué message.content es null en mi respuesta? Tu max_tokens es demasiado bajo y el proceso de razonamiento del modelo agotó todo el presupuesto antes de escribir la respuesta. Comprueba finish_reason: "length" con content: null es exactamente este caso; aumenta max_tokens y vuelve a intentarlo.

¿Admite el modo JSON? Sí, mediante response_format: {"type": "json_object"}. El JSON llega como string en message.content, y tú lo parseas; reasoning_content no forma parte de la salida estructurada y debe ignorarse en este escenario.

¿Admite llamada a funciones/herramientas? Sí, usando el formato estándar de array tools de OpenAI. Una respuesta que activa una herramienta devuelve finish_reason: "tool_calls" y un array tool_calls que contiene el nombre de la función y los argumentos.

¿Puedo recibir la respuesta en streaming? Sí: configura "stream": true y consume los eventos chat.completion.chunk. Tanto content como reasoning_content se transmiten como campos delta independientes dentro del mismo chunk.

¿Cómo se ve un error de autenticación? HTTP 401, con un cuerpo de respuesta JSON que contiene "type": "hiapi_error", "code": "permission_denied", un message legible por humanos y un request_id que puedes entregar a soporte (si el problema persiste).