Configuración del Entorno

Esta página es para quienes nunca han llamado a una API HTTP desde un terminal. Si ya se siente cómodo con curl y las variables de entorno, vaya directamente a Inicio Rápido.

Instalar un cliente

Necesita algo que pueda enviar una solicitud HTTP con encabezados personalizados. Dos opciones comunes:

• curl — una herramienta de línea de comandos, normalmente ya instalada en macOS y Linux. Compruébelo con curl --version en un terminal. En Windows, instálelo desde curl.se/windows o use curl incluido con Git Bash / WSL. Todos los ejemplos de esta documentación están escritos primero como comandos curl.
• Postman (o Insomnia) — una aplicación gráfica para crear y guardar solicitudes, útil si prefiere hacer clic en un formulario en lugar de escribir comandos de shell. Instálelo desde postman.com/downloads y luego reproduzca cualquier ejemplo curl de este sitio copiando la URL, el método, los encabezados y el cuerpo en una nueva solicitud.

Usar los ejemplos de Python

Todos los fragmentos de código de este sitio tienen una pestaña de Python basada en la popular biblioteca requests — no es un SDK oficial de ImageToTable.ai (no publicamos ninguno; son llamadas HTTP simples con cualquier cliente estándar). Necesita:

• Python 3.8+ — compruébelo con python3 --version. Obténgalo desde python.org/downloads si no lo tiene.
• requests — no forma parte de la biblioteca estándar, instálelo primero:

  pip install requests

  (o pip3 install requests, según su sistema).

Los ejemplos de exportación que analizan el archivo descargado (xlsx/docx) también usan openpyxl / python-docx — solo son necesarios si sigue esos ejemplos específicos, instálelos con pip install openpyxl python-docx.

Uso de los ejemplos en JavaScript

La pestaña de JavaScript usa la API nativa fetch — no necesita instalar ninguna biblioteca — pero asume un entorno de ejecución razonablemente actualizado:

• Node.js 20+ si se ejecuta del lado del servidor — verifique con node --version. Los ejemplos usan await de nivel superior y crypto.randomUUID() global, ambos requieren un Node reciente; en Node 18 (ahora al final de su vida útil) crypto no es confiablemente global fuera de CommonJS/REPL y estos ejemplos pueden fallar con un confuso error crypto is not defined que no tiene nada que ver con su clave API. Obtenga una versión actualizada desde nodejs.org.
• O simplemente pegue el fragmento en la consola DevTools de un navegador — todos los navegadores modernos admiten las mismas API (fetch, FormData, crypto.randomUUID()) de forma nativa, sin necesidad de instalar nada.

Obtenga su clave API

Su clave API se emite desde la página de configuración del perfil de su cuenta. La API v1 está disponible para planes de pago (Basic y superiores); si la usa con una clave del plan Free, devuelve un error plan_required en lugar de un error de autenticación faltante, ya que la clave en sí es válida — simplemente aún no tiene permiso para usar v1.

Almacene su clave como variable de entorno

No pegue su clave directamente en un comando que pueda compartir, capturar en pantalla o enviar al control de versiones. Expórtela a su sesión de shell y luego refiérase a ella como $API_KEY en cada solicitud — todos los ejemplos de este sitio asumen que esta variable existe:

export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Esto solo dura para la sesión de terminal actual. Para algo más permanente, agregue la misma línea al archivo de inicio de su shell (~/.bashrc, ~/.zshrc o equivalente) — o, si está escribiendo un script, cárguela desde un archivo .env / gestor de secretos en lugar de codificarla directamente en el código fuente.

Enviar una solicitud de prueba

Confirme que su clave y configuración funcionan antes de pasar a documentos reales:

curl https://imagetotable.ai/api/v1/account \
  -H "Authorization: Bearer $API_KEY"

Una clave activa en un plan de pago devuelve una instantánea de su cuenta (plan, rol, créditos disponibles). Si no es así, consulte la lista de verificación de solución de problemas a continuación.

Lista de verificación de solución de problemas

Cada error de v1 se devuelve como JSON con un type/code/message; consulte la guía completa de Manejo de Errores para la lista completa. Las comprobaciones iniciales más rápidas para una solicitud que no funciona son:

• ¿Obtiene missing_api_key? Verifique que el encabezado sea exactamente Authorization: Bearer <key> — la palabra Bearer, un solo espacio y luego la clave. Un espacio faltante o un carácter de comilla extraviado en $API_KEY producen esto.
• ¿Obtiene invalid_api_key? La clave no coincide con ninguna cuenta, o la cuenta está deshabilitada. Vuelva a copiarla desde su página de perfil: las claves son largas y es fácil truncarlas al copiar y pegar.
• ¿Obtiene plan_required? Su clave es válida, pero su cuenta está en el plan Free. Actualice al plan Basic o superior para usar v1.
• ¿Obtiene un error de conexión, no una respuesta JSON? Verifique que la URL comience con https://imagetotable.ai/api/v1/ y que esté usando -X POST (o el verbo correcto) para los endpoints que lo requieran: una solicitud GET a un endpoint solo POST no llegará a la ruta en absoluto.
• ¿Sube un archivo y obtiene un error inesperado? Las cargas de archivos multiparte necesitan -F "file=@/ruta/al/archivo.jpg" (la bandera de carga de formulario de curl), no -d ni un cuerpo JSON sin procesar: confundirlos es el error de carga más común. La @ inicial le indica a curl que lea esa ruta como un archivo real en su propia máquina; no es una URL, y el archivo ya debe existir allí antes de ejecutar el comando. Si no tiene un archivo local a mano, omita esto por completo: pase un campo url en lugar de file y el servidor lo obtendrá por usted; consulte Inicio Rápido.
• ¿Obtiene rate_limit_exceeded? Consulte Límites de Velocidad; los límites son por cuenta, no por tipo de solicitud que usted espera, por lo que una ráfaga de llamadas de sondeo puede alcanzar el mismo límite que una ráfaga de cargas.