Documentación de la API de Reconocimiento de Imágenes DeepSeek-OCR

Esta interfaz proporciona la función de Reconocimiento Óptico de Caracteres (OCR) en imágenes basada en el modelo DeepSeek-OCR. La API utiliza el formato de finalización de chat (Chat Completions) compatible con OpenAI y permite subir imágenes a través de una URL o codificación Base64 para convertirlas a formato de texto o Markdown.

Dominio del servicio: https://api.codingplanx.ai
Ruta de la API: /v1/chat/completions
Método HTTP: POST
Estado de la API: Publicado (Released)

1. Parámetros de la Solicitud

1.1 Encabezados de la Solicitud (Headers)

Parámetro	Requerido	Tipo	Valor de Ejemplo	Descripción
Content-Type	Sí	String	`application/json`	Formato del cuerpo de la solicitud
Accept	Sí	String	`application/json`	Formato del cuerpo de la respuesta
Authorization	Sí	String	`Bearer TU_API_KEY`	Clave API (API Key) para autenticación

1.2 Cuerpo de la Solicitud (Request Body)

Parámetro	Requerido	Tipo	Descripción
model	Sí	String	ID del modelo a utilizar. Para reconocimiento OCR, especifique `deepseek-ocr`.
messages	Sí	Array	Lista de mensajes de la conversación. Para OCR, debe incluir la información de la imagen en el mensaje.
stream	No	Boolean	Por defecto es `false`. Si es `true`, la respuesta se devolverá en formato streaming (flujo de datos).
temperature	No	Number	Temperatura de muestreo (0-2). Valores bajos generan respuestas más enfocadas y estables; valores altos son más aleatorios.
top_p	No	Number	Umbral de probabilidad de muestreo de núcleo (nucleus sampling).
max_tokens	No	Integer	Número máximo de tokens a generar.
response_format	No	Object	Especifica el formato de respuesta. Por ejemplo, `{"type": "json_object"}` para habilitar el modo JSON.
tools	No	Array	Lista de herramientas que el modelo puede llamar (actualmente soporta principalmente llamadas a funciones / function calling).

2. Ejemplos de Solicitud

2.1 Solicitud de Reconocimiento de Imagen OCR (JSON)

{
  "model": "deepseek-ocr",
  "stream": false,
  "messages": [
    {
      "role": "system",
      "content": "<image>\r
Free OCR."
    },
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://s3.ffire.cc/files/pdf_to_markdown.jpg" 
          }
        }
      ]
    }
  ]
}

Nota: El campo image_url.url soporta pasar directamente la URL pública de la imagen, o una cadena de datos codificada en Base64 (formato: data:image/jpeg;base64,...).

3. Detalles de la Respuesta

3.1 Estructura del Cuerpo de la Respuesta

Campo	Tipo	Descripción
id	String	Identificador único de la solicitud.
object	String	Tipo de objeto, generalmente `chat.completion`.
created	Integer	Marca de tiempo Unix (en segundos).
choices	Array	Contiene las múltiples opciones generadas.
└─ message	Object	Contenido del mensaje devuelto por el modelo, incluye `role` y `content`.
└─ finish_reason	String	Motivo de finalización (por ejemplo, `stop` o `length`).
usage	Object	Estadísticas de uso de Tokens, incluye tokens del prompt, de completado y el total.

3.2 Ejemplo de Respuesta

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Aquí está el contenido de texto reconocido por el OCR, generalmente devolviendo la información de formato de la imagen en formato Markdown."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 512,
        "completion_tokens": 128,
        "total_tokens": 640
    }
}

4. Preguntas Frecuentes (FAQs)

P1: ¿Qué formatos de imagen soporta DeepSeek-OCR? R: Actualmente soporta los formatos de imagen más comunes como JPEG, PNG, WebP y BMP. Se recomienda usar imágenes nítidas y con una resolución adecuada para garantizar una alta precisión en el reconocimiento.

P2: ¿Cómo utilizo Base64 para subir una imagen? R: Simplemente reemplace el valor de image_url.url por su cadena Base64. Ejemplo de formato: "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...".

P3: ¿Por qué el resultado del reconocimiento aparece cortado o incompleto? R: Por favor, revise el campo finish_reason en la respuesta. Si el valor es length, significa que el contenido generado superó el límite establecido en max_tokens. Le sugerimos aumentar el valor del parámetro max_tokens.

P4: ¿Esta API soporta el reconocimiento de imágenes por lotes (batch processing)? R: En el array messages de una sola solicitud, usted puede intentar agregar múltiples objetos image_url. Sin embargo, se recomienda realizar llamadas individuales para cada imagen con el fin de obtener un mejor procesamiento del contexto y respuestas más estables.

P5: ¿Cómo puedo obtener un formato y diseño más preciso (como tablas o fórmulas)? R: Puede agregar palabras clave o instrucciones en los mensajes de system o user (prompt). Por ejemplo: "Por favor, usa el formato Markdown para mantener el diseño de la tabla en la imagen y reconoce las fórmulas matemáticas que contiene".

P6: ¿Soporta la salida de datos en tiempo real (Streaming)? R: Sí. Al configurar el parámetro stream en true dentro de su solicitud, el modelo devolverá los fragmentos de texto reconocido en tiempo real. Esto es ideal para escenarios de interacción en vivo donde se requiere reducir la latencia al mostrar la primera letra (TTFT).