Referencia API | EmpirioLabs AI Docs

EmpirioLabs habla de formas de solicitud compatibles con OpenAI y Anthropic. Introduce cualquier SDK, apúntalo a https://api.empiriolabs.ai y autentica con tu clave API de EmpirioLabs. Todos los endpoints de abajo funcionan sin cambios contra cualquier cliente OpenAI o Anthropic.

Autenticación

Cada solicitud requiere un token de portador. Cualquiera de los encabezados es aceptado en todos los extremos:

Authorization: Bearer $EMPIRIOLABS_API_KEY
x-api-key: $EMPIRIOLABS_API_KEY

1 from openai import OpenAI
2 
3 client = OpenAI(
4     base_url="https://api.empiriolabs.ai",
5     api_key="$EMPIRIOLABS_API_KEY",
6 )
7 
8 resp = client.chat.completions.create(
9     model="deepseek-v4-pro",
10     messages=[{"role": "user", "content": "Hello!"}],
11 )

Superficie del extremo

Completados de chats

Chat compatible con OpenAI. Streaming, llamada a herramientas, visión, entrada de audio, modo JSON, salida estructurada, controles de razonamiento.

Finalizaciones de legado

Completaciones de prompts compatibles con OpenAI para modelos que anuncian POST /v1/completions.

Anthropic Mensajes

Entrada sin cita para clientes de SDK de Anthropic. tool_use / tool_result bloques de ida y vuelta limpios.

Imágenes

Generar, editar, inpaint, variaciones de imagen. URLs CDN alojadas, firmadas 7 días.

Vídeo

Generación de vídeo asincrónica. Regresa un job_id; Consulta la URL en el endpoint de empleos.

Audio (TTS, música, voces)

TTS más streaming en tiempo real TTS (Inworld), generación de música / podcast / SFX, gestión de clones de voz.

Agentes

Tareas de agente que usan herramientas de larga duración. Empezar, encuestar, transmitir mensajes, parar pronto.

Transcripción

Susurro / Deepgram / Periquito. Subir o file_url en varias partes.

Búsqueda e investigación

Exa, Tavily, Linkup, Perplexity Busca. Filtros de dominio, intervalos de fechas, sesgo geográfico.

Generación 3D

Generación de activos de imagen asíncrona a 3D. Regresa un job_id; encuesta para la URL firmada de GLB.

Detección

POST /v1/detect - Detección de IA GPTZero, escaneo de bibliografía, análisis de fuentes.

Incrustaciones

Embeddings compatibles con OpenAI. Texto multilingüe + incrustadores multimodales.

Reclasificaciones

Reclasificación semántica del documento. Ordena los candidatos a recuperación por relevancia para RAG y refinamiento de búsqueda.

URLs de archivos

Pasa cualquier URL pública en los campos de entrada. No hay subida ni renovación - las salidas generadas son válidas durante 7 días.

Empleos

Consulta el estado / resultado de cualquier generación asincrónica. State se mantuvo 1 hora después de completarlo.

Modelos

Catálogo en vivo con precios, esquema de parámetros, flags de capacidades, regiones.

Errores

Envolventes de error compatibles con OpenAI y Anthropic.

Completados de chats

POST /v1/chat/completions

Pasa cualquier modelo con capacidad de chat del catálogo como model. El streaming utiliza eventos enviados por servidor con data: ... líneas y una data: [DONE] final.

$ curl https://api.empiriolabs.ai/v1/chat/completions \
>   -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "deepseek-v4-pro",
>     "messages": [{"role": "user", "content": "Summarize CRDT consistency in 3 bullets."}],
>     "stream": true,
>     "temperature": 0.7
>   }'

Los parámetros aceptados de cada modelo están en su página de documentación (por ejemplo, temperature, top_p, enable_thinking, reasoning_effort, web_search_tier). Explora ellos en Proveedores y Modelos.

Parámetros del modelo entre extremos

Los parámetros específicos del modelo anunciados en la página del modelo y en GET /v1/models/\{id\} pueden enviarse a /v1/chat/completions, /v1/responses y /v1/messages cuando ese modelo soporte el endpoint. La pasarela adapta las formas de las peticiones para que los mismos controles lleguen al modelo subyacente.

Para modelos con capacidad de pensamiento, enable_thinking y thinking_budget se aceptan en los tres extremos de texto. En /v1/messages, también puedes usar el pensamiento al estilo antrópico:

1 {
2   "thinking": {
3     "type": "enabled",
4     "budget_tokens": 1024
5   }
6 }

Eso corresponde con los mismos controles enable_thinking=true y thinking_budget=1024 que usan las Finalizaciones y Respuestas de Chat.

Finalizaciones de legado

POST /v1/completions

Utiliza este endpoint para clientes compatibles con OpenAI que aún envían un prompt en bruto en lugar de messages de chat. Solo los modelos que listan POST /v1/completions en supported_endpoints aceptan esta forma.

El streaming utiliza eventos enviados por el servidor e incluye el uso cuando el servicio modelo los reporta.

$ curl https://api.empiriolabs.ai/v1/completions \
>   -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "qwen3-5-9b",
>     "prompt": "Write one concise launch sentence.",
>     "max_tokens": 64,
>     "stream": true
>   }'

Anthropic Mensajes

POST /v1/messages

Disponible para cualquier cliente de SDK de Anthropic - los mismos modelos accesibles en /v1/chat/completions y /v1/responses están disponibles aquí bajo la forma de Mensajes Antrópicos.

$ curl https://api.empiriolabs.ai/v1/messages \
>   -H "x-api-key: $EMPIRIOLABS_API_KEY" \
>   -H "anthropic-version: 2023-06-01" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "deepseek-v4-pro",
>     "max_tokens": 1024,
>     "messages": [{"role": "user", "content": "Hi!"}]
>   }'

tool_use y tool_result bloques de ida y vuelta limpios. Se conservan los arrays de contenido text-plus-tool_use mixto.

Generación de imágenes

POST /v1/images/generations

$ curl https://api.empiriolabs.ai/v1/images/generations \
>   -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "wan-2-7-image",
>     "prompt": "A glass cathedral at sunset, dramatic lighting",
>     "aspect_ratio": "16:9",
>     "resolution": "4K",
>     "thinking_mode": true,
>     "num_images": 4
>   }'

Los flujos de edición de imagen aceptan image: ["https://..."] con hasta el límite documentado del modelo (3 para qwen-image-2-0, 9 para wan-2-7-image, 14 para seedream-5-0-lite). Los modos de conjunto de imágenes generan series cohesivas - consulta la página de cada modelo para el toggle.

Las URLs devueltas están activas en https://media.empiriolabs.ai y expiran tras 7 días. Guarda lo que quieras conservar antes de que caduque la URL.

POST /v1/images/analysis realiza análisis solo de visión (sin generación) sobre una o más imágenes de entrada. Úsase para extracción de diseño, detección de objetos, OCR y tareas de inspección similares donde el modelo devuelve texto o JSON describiendo la imagen en lugar de una imagen nueva.

Generación de vídeo

POST /v1/videos/generations

Siempre asíncrono: el endpoint devuelve una job_id y una URL de sondeo.

$ curl https://api.empiriolabs.ai/v1/videos/generations \
>   -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "seedance-2-0-pro",
>     "prompt": "A cinematic dolly shot of a city street at dusk in the rain",
>     "resolution": "1080p",
>     "aspect_ratio": "16:9",
>     "duration": 8,
>     "generate_audio": true
>   }'

Generación de audio

POST /v1/audio/speech síncrono, devuelve por defecto una URL alojada; Pase response_format: "b64_json" bytes de audio en línea.

POST /v1/audio/speech:stream TTS en tiempo real. Devuelve eventos enviados por el servidor mientras el modelo se sintetiza. Menos de 130 ms time-to-first-byte en Inworld TTS Mini, menos de 250 ms en Max. Úsalo para agentes de voz y reproducción interactiva. Actualmente soportado en Inworld TTS Mini / Max; otros modelos TTS utilizan el punto final síncrono.

POST /v1/audio/generations generación de música, podcast y efectos de sonido. Incluye Stable Audio, GLM TTS, MOSS, SoulX Podcast, donde la forma prompt-to-audio difiere de la de TTS.

GET /v1/voices listar y gestionar voces, incluyendo clones de voz personalizados para Inworld TTS. Utiliza el voice_id devuelto en cualquiera de los extremos de voz.

$ curl https://api.empiriolabs.ai/v1/audio/speech \
>   -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gemini-2-5-flash-tts",
>     "input": "Hello from EmpirioLabs.",
>     "voice": "Charon",
>     "output_format": "WAV"
>   }'

Transcripción

POST /v1/audio/transcriptions

Acepta una carga de file multiparte o una carga útil JSON con file_url.

$ curl https://api.empiriolabs.ai/v1/audio/transcriptions \
>   -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
>   -F "model=openai-whisper-1" \
>   -F "file=@meeting.mp3" \
>   -F "response_format=verbose_json" \
>   -F "timestamp_granularities=word,segment"

Los archivos largos (más de 5 minutos) se enrutan automáticamente al sistema de trabajos asincrónicos - la respuesta incluye un job_id en lugar de texto en línea. Consulta el endpoint de trabajos para recuperar la transcripción final.

Búsqueda e investigación

POST /v1/search superficie de búsqueda unificada para modelos de tipo recuperación. Los parámetros exactos aceptados por modelo están presentes en la página de cada modelo (por ejemplo, exa-search expone 28 parámetros, incluyendo category, livecrawl, subpages, summary_query, code_tokens).

POST /v1/research modelos de investigación profunda / recuperación en varios pasos (Exa Research, Perplexity Deep Research, Linkup Deep Search). Genera un informe de investigación estructurado con fuentes citadas.

POST /v1/answer modelos directos de preguntas y respuestas (Exa Answer). Devuelve una respuesta concisa más citas sin la forma completa del informe.

$ curl https://api.empiriolabs.ai/v1/search \
>   -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "tavily-search",
>     "query": "latest CRDT research papers 2026",
>     "search_depth": "advanced",
>     "include_answer": "advanced",
>     "max_results": 10,
>     "topic": "general"
>   }'

Agentes

Tareas de agente de larga duración que usan herramientas (actualmente enrutadas a Manus). Envía una vez, luego consulta el estado y step-by-step mensajes, o para antes de tiempo.

POST /v1/agents/run cumple doble función:

Sin task_id empieza una tarea nova. La respuesta lleva a cabo el nuevo task_id.
Con task_id envía un mensaje de seguimiento a una tarea existente. El agente lo recoge en su siguiente paso de razonamiento.

GET /v1/agents/\{task_id\} recuperar el estado actual de la tarea y el resultado final.

GET /v1/agents/\{task_id\}/messages enumerar todos los pasos que el agente ha emitido hasta ahora. Útil para mostrar un trazado de razonamiento en tiempo real junto con la respuesta final.

POST /v1/agents/\{task_id\}/stop detener una tarea en marcha. La facturación se conforma con el trabajo que el agente ya ha realizado.

$ curl https://api.empiriolabs.ai/v1/agents/run \
>   -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "manus",
>     "input": "Summarize the top 5 humanoid robotics startups by funding raised in 2025-2026"
>   }'

Generación 3D

POST /v1/3d/generations

La generación de imagen a 3D es asincrónica. El endpoint devuelve una job_id y una URL de sondeo; consulta el endpoint de jobs para recuperar la última URL firmada de GLB.

$ curl https://api.empiriolabs.ai/v1/3d/generations \
>   -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "trellis-2-4b",
>     "image_url": "https://example.com/product-photo.png",
>     "resolution": "1024",
>     "texture_size": "2048",
>     "decimation_target": 500000,
>     "seed": 42
>   }'

trellis-2-4b expone toda la imagen, resolución, sampler, textura y parámetro de exportación de la malla en su página de modelo.

Detección

POST /v1/detect

Punto final especializado en clasificación de texto. Actualmente alimenta GPTZero (detección por IA, escaneo de bibliografía, análisis de fuentes). El scan_type enum de cada modelo elige el camino aguas arriba; consulta la documentación por modelo para la superficie completa de parámetros.

$ curl https://api.empiriolabs.ai/v1/detect \
>   -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gptzero",
>     "input": "The quick brown fox jumps over the lazy dog.",
>     "scan_type": "ai_detection",
>     "multilingual": false
>   }'

GPTZero también es accesible a través de /v1/chat/completions y /v1/responses - pasa el texto al cuerpo del mensaje y la pasarela adapta la llamada. El resumen de detección vuelve como el mensaje del asistente; pasa disable_formatting: true para recibir el JSON en bruto aguas arriba en su lugar.

Incrustaciones

POST /v1/embeddings

Embeddings compatibles con OpenAI. Hay textos multilingües y embebidos multimodales (texto + imagen + vídeo) disponibles.

$ curl https://api.empiriolabs.ai/v1/embeddings \
>   -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "text-embedding-v4",
>     "input": ["Sentence one.", "Sentence two."],
>     "encoding_format": "float"
>   }'

Reclasificaciones

POST /v1/reranks

Ordena documents candidato por relevancia semántica para un query. Devuelve el índice original de cada documento más una puntuación de relevancia de 0-1 (mayor = más relevante). Úsalo para ajustar la salida de un almacén vectorial / BM25 / retriever híbrido antes de pasar los primeros resultados a un modelo de lenguaje - el paso estándar final en una pipeline RAG.

$ curl https://api.empiriolabs.ai/v1/reranks \
>   -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "qwen3-rerank",
>     "query": "What is a rerank model?",
>     "documents": [
>       "Rerank models sort candidate documents by relevance.",
>       "Quantum computing is a cutting-edge field of computer science.",
>       "Pre-trained language models advanced rerank models."
>     ],
>     "top_n": 2,
>     "return_documents": true
>   }'

El cambio opcional de parámetros de instruct entre recuperación de preguntas y respuestas (por defecto) y ordenación pura por similitud semántica - véase la página del modelo qwen3-rerank para la tabla completa de parámetros.

Objeto de uso

Cada endpoint que factura el uso devuelve un campo de usage en la respuesta (y en el fragmento de streaming del terminal). Forma de la base:

cost_usd - cantidad exacta que se te cobró a tu cuenta por la solicitud. Autoritario.
prompt_tokens / completion_tokens / total_tokens - para modelos de chat.
Campos de caché (cache_read_input_tokens, cache_creation_input_tokens) - cuando se aplica la caché de prompts.

Los modelos con precios ascendentes escalonados, por llamada o variantes imprimen campos adicionales en usage para que puedas ver qué tipo de interés se aplicó:

Precio por niveles / variantes. Los trabajadores imprimen un discriminador por nivel en usage cuando la misma dimensión tiene más de una tarifa. El campo principal es pricing_tier_label (legible por humanos, por ejemplo, "Medium context" / "Pro" / "2K"). Los trabajadores mayores pueden estampar directamente la dimensión en bruto (resolution, quality, mode, rate_tier). El salpicadero muestra la insignia desde el que esté presente.
Precio por llamada. Los trabajadores que facturan por invocación de herramienta (búsqueda, obtención, ejecución de código, etc.) cuentan bajo tool_calls_details.<tool>.invocation o tool_usage.<tool>. El panel de control los amplía automáticamente en un desglose por herramienta.
Tarificación por dimensión. Los trabajadores que facturan múltiples dimensiones en una sola solicitud (por ejemplo, tokens de citación + tokens de razonamiento + consultas de búsqueda en modelos de investigación profunda) escriben cada dimensión como un campo propio (citation_tokens, reasoning_tokens, num_search_queries, etc.).

Los mismos campos controlan el desglose de la insignia de nivel y herramienta en los registros de uso del panel, y también se devuelven el extremo de historial GET /v1/account/usage bajo la metadata.worker_usage de cada evento (además de un array de tool_breakdown estructurado para modelos por llamada). Así que, ya sea que leas el uso de respuestas en vivo, el historial de uso de cuentas o tu panel de control, el desglose de nivel y facturación coincide exactamente.

URLs de archivos

EmpirioLabs no aloja las subidas de usuarios. Pasa cualquier URL pública directamente al campo de entrada del endpoint del modelo:

Familia de extremos	Campo de entrada	Acepta
Completados de chat (visión)	`content[].image_url.url`	Cualquier URL de imagen pública o `data:` URI
Completados de chat (audio)	`content[].audio_url.url`	Cualquier URL de audio pública
Generación de imágenes (editar / variación)	`image: ["https://..."]`	Hasta N URLs (límite específico del modelo)
Generación de vídeo (i2v / r2v / edit)	`image: "https://..."` / `video: "https://..."`	URLs públicas
Audio TTS / música	n/a (entrada solo de texto)	-
Transcripción de audio	`file_url: "https://..."` o `file=@local.mp3` multiparte	URL pública o subida directa de clips cortos
Búsqueda	n/a (texto de consulta)	-
Embeddings (multimodales)	`input[].url` (image/video artículo)	URLs públicas
Reclasificaciones	n/a (consulta de texto + documentos de texto)	-

Para la transcripción de audio específicamente, la subida directa multiparte en /v1/audio/transcriptions es el camino soportado para clips privados que no están en una URL - esos bytes fluyen directamente al trabajador speech-to-text sin almacenamiento persistente.

Las URLs de salida generadas se firman y expiran 7 días después de la creación. No hay un punto final de re-firma. Guarda todo lo que necesites conservar - tanto la URL como el binario - dentro de esa ventana.

Trabajos asincrónicos

GET /v1/jobs/<job-id> - encuesta el estado o resultado final de cualquier trabajo de generación o transcripción asíncrona.

El estado del puesto se mantiene 1 hora después de completarlo.

Job state shape

1 {
2   "job_id": "job_01HV...",
3   "status": "processing | completed | failed",
4   "progress": 0.42,
5   "created_at": "2026-05-02T17:11:32Z",
6   "completed_at": null,
7   "result": null,
8   "error": null
9 }

Cuando status es completed, el campo result lleva la respuesta completa en la misma forma que habría devuelto el extremo síncrono.

El tiempo de espera HTTP de entrada es 15 minutos. Las finalizaciones de chat síncronas cerca de ese límite deberían establecer stream=true para que parte de la salida fluya de vuelta y la conexión se mantenga caliente.

Modelos

GET /v1/models - enumera todos los modelos disponibles.

GET /v1/models/<model-id> - esquema completo para un modelo, incluyendo su tabla de parámetros.

GET /v1/models?format=openrouter devuelve la forma de listado de modelos de OpenRouter para modelos marcados listos para la ingestión de socios. Consulta OpenRouter Model Listing para los campos de respuesta exactos.

Cada modelo devuelve lo siguiente:

Campo	Descripción
`id`	Babosa canónica (por ejemplo, `wan-2-7-image`)
`description`	Breve descripción de marketing
`category`	texto / imagen / vídeo / audio / transcripción / investigación / herramientas / incrustación / reclasificador
`input_modalities`	Lo que acepta el modelo
`output_modalities`	Lo que emite el modelo
`context_window`	Tokens (chat) o null (medios)
`region`	Región del servidor
`logo`	URL de CDN al logotipo del modelo
`pricing_rows`	Tasas por token, por imagen, por segundo o por llamada
`supported_endpoints`	¿Qué `/v1/...` extremos aceptan este modelo
`parameters`	Esquema completo - nombre, tipo, predeterminado, min/max, valores permitidos, descripciones
`features`	Etiquetas como streaming, visión, tool_calling, voice_cloning

$ curl https://api.empiriolabs.ai/v1/models | jq '.data[0]'
$ curl https://api.empiriolabs.ai/v1/models/wan-2-7-image | jq '.parameters'

disable_formatting bandera

Muchos endpoints de chat, búsqueda, investigación y reclasificación aceptan una bandera de disable_formatting=true. Cuando se establece en un modelo de soporte, el trabajador omite el formato del servidor de EmpirioLabs (reescritura de citas, bloque de referencias, Markdown con bloque de pensamiento, etc.) y devuelve la forma de carga útil ascendente palabra por palabra.

La cobertura se anuncia por modelo. Consulta supports_passthrough en GET /v1/models/\{id\} para confirmar que un modelo específico honra la bandera. Los modelos que anuncian supports_passthrough: true también aceptan los alias raw=true, passthrough=true y raw_response=true. Los modelos sin ese campo aceptan solo la forma canónica de disable_formatting=true (o no respetan el paso en absoluto). La tarjeta de modelos indica qué alias acepta cada modelo.

Los endpoints de imagen, vídeo, generación de audio, transcripción e incrustación no aceptan esta bandera, ya que no hay una capa de formato que desactivar en esos endpoints.

Retención de medios generados

Las imágenes, vídeos y audio generados se devuelven como URLs firmadas válidas durante 7 días. Después de eso, la URL deja de funcionar y el activo desaparece - no hay un punto final de re-firma. Guarda lo que quieras conservar antes de que expire la ventana de 7 días.

Errores

Sobre OpenAI en chat / respuestas / imágenes / vídeos / audio / búsqueda / incrustaciones / reposiciones:

1 {
2   "error": {
3     "message": "Aspect ratio is not supported by this model. Allowed: 16:9, 9:16, 1:1, ...",
4     "type": "invalid_request_error",
5     "code": "invalid_parameter",
6     "param": "aspect_ratio"
7   }
8 }

Anthropic sobre en /v1/messages:

1 { "type": "error", "error": { "type": "invalid_request_error", "message": "..." } }

Referencia de cabeceras

Cabecera	Obligatorio	Propósito
`Authorization` / `x-api-key`	Sí	Autenticación por token portador
`Content-Type`	Sí, en POST	`application/json` o `multipart/form-data`
`Accept`	no	`text/event-stream` forzar SSE en los endpoints de chat
`anthropic-version`	al llamar a `/v1/messages`	Versión de la API Anthropic (por ejemplo, `2023-06-01`)

Explora los esquemas de parámetros por modelo en Proveedores y Modelos. Cuando haces clic en un modelo específico, cada parámetro que acepta el modelo - tipo, predeterminado, rango, valores permitidos, banderas condicionales - se documenta en una tabla generada desde la base de datos en vivo.