Referência API | EmpirioLabs AI Docs

EmpirioLabs fala formulários de solicitação compatíveis com OpenAI e Anthropic. Coloque qualquer SDK, aponte para https://api.empiriolabs.ai e autentique com sua chave API do EmpirioLabs. Todos os endpoints abaixo funcionam contra qualquer cliente OpenAI ou Anthropic sem alterações.

Autenticação

Cada solicitação requer um token de portador. Qualquer um dos cabeçalhos é aceito em todos os endpoints:

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 )

Superfície de ponto final

Conclusãos de chat

Chat compatível com OpenAI. Streaming, chamada de ferramentas, visão, entrada de áudio, modo JSON, saída estruturada, controles de raciocínio.

Finalizações legadas

Prompts compatíveis com OpenAI para modelos que anunciam POST /v1/completions.

Anthropic Mensagens

Atendimento sem marcação para clientes do SDK Anthropic. tool_use / tool_result bloqueia a ida e volta de forma limpa.

Imagens

Gerar, editar, fazer o inpaint, variações de imagem. URLs CDN hospedadas, assinados por 7 dias.

Vídeo

Geração de vídeo assíncrona. Retorna um job_id; Consulte o endpoint de empregos para obter a URL.

Áudio (TTS, música, vozes)

TTS mais streaming em tempo real TTS (Inworld), geração de música/podcast/SFX, gerenciamento de clones de voz.

Agentes

Tarefas de agente que usam ferramentas de longa duração. Comece, enquete, transmita mensagens, pare cedo.

Transcrição

Sussurro / Deepgram / Periquito. Upload ou file_url multipartes.

Busca e pesquisa

Exa, Tavily, Linkup, Perplexity Busca. Filtros de domínio, intervalos de data, viés geográfico.

Geração 3D

Geração de ativos de imagem assíncrona para 3D. Retorna um job_id; enquétria para a URL GLB assinada.

Detecção

POST /v1/detect - Detecção de IA GPTZero, varredura bibliográfica, análise de fonte.

Incorporações

Embeddings compatíveis com OpenAI. Texto multilíngue + embedders multimodais.

Reclassificações

Reclassificação semântica de documentos. Ordene candidatos à recuperação por relevância para o refinamento do RAG e busca.

URLs de arquivos

Passe qualquer URL pública nos campos de entrada. Sem upload, sem re-assinatura - as saídas geradas são válidas por 7 dias.

Empregos

Consulte o status/resultado de qualquer geração assíncrona. A State reteve 1 hora após a conclusão.

Modelos

Catálogo ao vivo com preços, esquema de parâmetros, flags de capacidade, regiões.

Erros

Envelopes de erro compatíveis com OpenAI e Anthropic.

Conclusãos de chat

POST /v1/chat/completions

Passe qualquer modelo com capacidade de chat do catálogo como model. O streaming utiliza Eventos Enviados pelo Servidor com data: ... linhas e um 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
>   }'

Os parâmetros aceitos de cada modelo estão disponíveis em sua página de documentação (por exemplo, temperature, top_p, enable_thinking, reasoning_effort, web_search_tier). Navegue por eles em Providers and Models.

Parâmetros do modelo entre os pontos finais

Parâmetros específicos do modelo anunciados na página do modelo e em GET /v1/models/\{id\} podem ser enviados para /v1/chat/completions, /v1/responses e /v1/messages quando esse modelo suporta o endpoint. O gateway adapta as formas de requisição para que os mesmos controles cheguem ao modelo subjacente.

Para modelos capazes de pensar, enable_thinking e thinking_budget são aceitos nos três endpoints de texto. Sobre /v1/messages, você também pode usar o pensamento no estilo antrópico:

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

Isso corresponde aos mesmos controles de enable_thinking=true e thinking_budget=1024 usados pelas Completas e Respostas de Chat.

Finalizações legadas

POST /v1/completions

Use esse endpoint para clientes compatíveis com OpenAI que ainda enviam um prompt bruto em vez de messages de chat. Apenas modelos que listam POST /v1/completions em supported_endpoints aceitam esse formato.

O streaming utiliza Eventos Enviados pelo Servidor e inclui o uso quando o serviço modelo os 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 Mensagens

POST /v1/messages

Disponível para qualquer cliente do SDK Anthropic - os mesmos modelos acessíveis em /v1/chat/completions e /v1/responses estão disponíveis aqui sob o formato Anthropic Messages.

$ 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 e tool_result blocos de ida e volta de forma limpa. Arranjos de conteúdo misto text-plus-tool_use são preservados.

Geração de imagens

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

Fluxos de edição de imagem aceitam image: ["https://..."] com até o limite documentado do modelo (3 para qwen-image-2-0, 9 para wan-2-7-image, 14 para seedream-5-0-lite). Modos de conjunto de imagem geram séries coesas - veja a página de cada modelo para a opção de alternância.

URLs retornadas ficam ativas no https://media.empiriolabs.ai e expiram após 7 dias. Salve tudo o que quiser manter antes que a URL expire.

POST /v1/images/analysis executa análise apenas de visão (sem geração) em uma ou mais imagens de entrada. Use para extração de layout, detecção de objetos, OCR e tarefas de inspeção similares, onde o modelo retorna texto ou JSON descrevendo a imagem em vez de uma nova imagem.

Geração de vídeo

POST /v1/videos/generations

Sempre assíncrono - o endpoint retorna um job_id e uma URL de polling.

$ 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
>   }'

Geração de áudio

POST /v1/audio/speech síncrono, retorna uma URL hospedada por padrão; Passe response_format: "b64_json" para bytes de áudio inline.

POST /v1/audio/speech:stream TTS em tempo real. Retorna eventos enviados pelo servidor enquanto o modelo sintetiza. Abaixo de 130ms time-to-first-byte no Inworld TTS Mini, abaixo de 250ms no máximo. Use para agentes de voz e reprodução interativa. Atualmente suportado no Inworld TTS Mini / Max; outros modelos TTS usam o ponto final síncrono.

POST /v1/audio/generations geração de música, podcast e efeitos sonoros. Cobre Stable Audio, GLM TTS, MOSS, SoulX Podcast, onde o formato prompt-to-audio difere do TTS.

GET /v1/voices listar e gerenciar vozes, incluindo clones de voz personalizados para o Inworld TTS. Use o voice_id retornado em qualquer um dos extremos de fala.

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

Transcrição

POST /v1/audio/transcriptions

Aceita um upload de file multiparte ou uma carga útil JSON com 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"

Arquivos longos (mais de 5 minutos) são roteados automaticamente para o sistema de trabalhos assíncronos - a resposta inclui um job_id em vez de texto inline. Consulte o endpoint de jobs para recuperar a transcrição final.

Busca e pesquisa

POST /v1/search superfície de busca unificada para modelos no estilo de recuperação. Os parâmetros exatos aceitos por modelo estão presentes na página de cada modelo (por exemplo, exa-search expõe 28 parâmetros, incluindo category, livecrawl, subpages, summary_query, code_tokens).

POST /v1/research modelos de pesquisa profunda / recuperação em múltiplas etapas (Exa Research, Perplexity Deep Research, Linkup Deep Search). Gera um relatório de pesquisa estruturado com fontes citadas.

POST /v1/answer modelos diretos de perguntas e respostas (Exa Answer). Retorna uma resposta concisa mais citações sem o formato completo do relatório.

$ 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

Tarefas de agente de longa duração que usam ferramentas (atualmente roteadas para Manus). Envie uma vez, depois consulte o status e step-by-step mensagens, ou pare cedo.

POST /v1/agents/run faz dupla função:

Sem task_id começa uma nova tarefa. A resposta carrega o novo task_id.
Com task_id ele envia uma mensagem de acompanhamento para uma tarefa existente. O agente o pega no próximo passo de raciocínio.

GET /v1/agents/\{task_id\} recuperar o status atual da tarefa e o resultado final.

GET /v1/agents/\{task_id\}/messages listar todos os passos que o agente emitiu até agora. Útil para renderizar um raciocínio em tempo real junto com a resposta final.

POST /v1/agents/\{task_id\}/stop parar uma tarefa em corrida. A cobrança se contenta com o trabalho que o agente já realizou.

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

Geração 3D

POST /v1/3d/generations

A geração de imagem para 3D é assíncrona. O endpoint retorna um job_id e uma URL de pesquisa; Consulte o endpoint de jobs para recuperar a URL final assinada do 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 expõe toda a imagem, resolução, sampler, textura e parámetro de exportação da malha na página do modelo.

Detecção

POST /v1/detect

Endpoint especializado em classificação de texto. Atualmente alimenta o GPTZero (detecção por IA, escaneamento bibliográfico, análise de fonte). O scan_type enum de cada modelo escolhe o caminho a montante; veja a documentação por modelo para a superfície completa do parâmetro.

$ 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
>   }'

O GPTZero também é acessível via /v1/chat/completions e /v1/responses - passe o texto no corpo da mensagem e o gateway adapta a chamada. O resumo da detecção retorna como a mensagem do assistente; passar disable_formatting: true para receber o JSON bruto a montante.

Incorporações

POST /v1/embeddings

Embeddings compatíveis com OpenAI. Texto multilíngue e incorporadores multimodais (texto + imagem + vídeo) estão disponíveis.

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

Reclassificações

POST /v1/reranks

Ordene documents candidatos por relevância semântica para um query. Retorna o índice original de cada documento mais uma pontuação de relevância de 0-1 (maior = mais relevante). Use isso para apertar a saída de um vetor store / BM25 / hybrid retriever antes de passar os tops hits para um modelo de linguagem - a etapa padrão final em um 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
>   }'

A troca opcional de parâmetros de instruct entre recuperação de Q&A (padrão) e ordenação pura por similaridade semântica - veja a página do modelo qwen3-rerank para a tabela completa de parâmetros.

Objeto de uso

Todo endpoint que fatura o uso retorna um campo usage na resposta (e no bloco de streaming do terminal). Formato da base:

cost_usd - valor exato que sua conta foi cobrada pelo pedido. Autoritário.
prompt_tokens / completion_tokens / total_tokens - para modelos no estilo chat.
Campos de cache (cache_read_input_tokens, cache_creation_input_tokens) - quando o cache de prompt se aplica.

Modelos com preços ascendentes em níveis, por chamada ou variantes carimbam campos extras na usage para que você possa ver qual taxa foi aplicada:

Preço por escalão / variante. Os trabalhadores carimbam um discriminador de nível em usage quando a mesma dimensão tem mais de uma taxa. O campo principal é pricing_tier_label (legível por humanos, por exemplo, "Medium context" / "Pro" / "2K"). Trabalhadores mais velhos podem carimbar diretamente a dimensão bruta (resolution, quality, mode, rate_tier). O painel renderiza o distintivo a partir do que estiver presente.
Precificação por chamada. Trabalhadores que cobram por invocação de ferramenta (busca, busca, execução de código, etc.) conta sob tool_calls_details.<tool>.invocation ou tool_usage.<tool>. O painel expande essas informações automaticamente para uma divisão por ferramenta.
Precificação por dimensão. Trabalhadores que faturam múltiplas dimensões em uma única solicitação (por exemplo, tokens de citação + tokens de raciocínio + consultas de busca em modelos de pesquisa profunda) marcam cada dimensão como um campo próprio (citation_tokens, reasoning_tokens, num_search_queries, etc.).

Os mesmos campos controlam a divisão do distintivo de tier e por ferramenta nos logs de uso do painel, e também são retornados pelo endpoint de histórico GET /v1/account/usage sob o metadata.worker_usage de cada evento (além de um array estruturado de tool_breakdown para modelos por chamada). Então, seja você lendo o uso de respostas ao vivo, histórico de uso de contas ou seu painel, o nível e a distribuição de cobrança coincidem exatamente.

URLs de arquivos

EmpirioLabs não hospeda uploads de usuários. Passe qualquer URL pública diretamente no campo de entrada do endpoint do modelo:

Família de endpoints	Campo de entrada	Aceita
Conclusão de chat (visão)	`content[].image_url.url`	Qualquer URL de imagem pública ou `data:` URI
Conclusão do chat (áudio)	`content[].audio_url.url`	Qualquer URL de áudio pública
Geração de imagem (editar / variação)	`image: ["https://..."]`	Até N URLs (limite específico do modelo)
Geração de vídeo (i2v / r2v / edit)	`image: "https://..."` / `video: "https://..."`	URLs públicas
Áudio TTS / música	n/a (entrada apenas de texto)	-
Transcrição de áudio	`file_url: "https://..."` ou múltiplas `file=@local.mp3`	URL pública ou upload direto de clipes curtos
Busca	n/a (texto da consulta)	-
Embeddings (multimodais)	`input[].url` (image/video item)	URLs públicas
Reclassificações	n/a (consulta de texto + documentos de texto)	-

Para transcrição de áudio especificamente, o upload direto multiparte no /v1/audio/transcriptions é o caminho suportado para clipes privados que não estão em uma URL - esses bytes fluem direto para o worker speech-to-text sem armazenamento persistente.

URLs de saída geradas são assinadas e expiram 7 dias após a criação. Não existe um ponto final de re-assinatura. Salve tudo o que você precisar manter - tanto a URL quanto o binário - dentro dessa janela.

Empregos assíncronos

GET /v1/jobs/<job-id> - consultar o status / resultado final de qualquer trabalho de geração ou transcrição assíncrona.

O estado do trabalho é mantido por 1 hora após a conclusão.

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 }

Quando status é completed, o campo result carrega a resposta completa na mesma forma que o ponto final síncrono teria retornado.

O tempo de espera HTTP de entrada é 15 minutos. Conclusãos de chat síncronos próximos a esse limite devem stream=true para que a saída parcial flua de volta e a conexão permaneça quente.

Modelos

GET /v1/models - liste todos os modelos disponíveis.

GET /v1/models/<model-id> - esquema completo para um modelo, incluindo sua tabela de parâmetros.

GET /v1/models?format=openrouter retorna a forma de listagem de modelos do OpenRouter para modelos marcados como prontos para ingestão de parceiros. Veja OpenRouter Model Listing para os campos de resposta exatos.

Cada modelo retorna:

Campo	Descrição
`id`	Slug canônico (por exemplo, `wan-2-7-image`)
`description`	Breve descrição de marketing
`category`	texto / imagem / vídeo / áudio / transcrição / pesquisa / ferramentas / incorporação / reclassificador
`input_modalities`	O que o modelo aceita
`output_modalities`	O que o modelo emite
`context_window`	Tokens (chat) ou null (mídia)
`region`	Região do servidor
`logo`	URL do CDN para o logo do modelo
`pricing_rows`	Taxas por token, imagem, segundo ou por chamada
`supported_endpoints`	Quais `/v1/...` endpoints aceitam esse modelo
`parameters`	Esquema completo - nome, tipo, padrão, min/max, valores permitidos, descrições
`features`	Tags como streaming, visão, 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 bandeira

Muitos endpoints de chat, busca, pesquisa e reranqueamento aceitam uma disable_formatting=true flag. Quando configurado em um modelo de suporte, o trabalhador pula a formatação do servidor do EmpirioLabs (reescrita de citações, bloco de referências, Markdown com bloco de pensamento, etc.) e retorna a forma da carga útil a montante literalmente.

A cobertura é anunciada por modelo. Verifique supports_passthrough em GET /v1/models/\{id\} para confirmar que um modelo específico honra a bandeira. Modelos que anunciam supports_passthrough: true também aceitam os apelidos raw=true, passthrough=true e raw_response=true. Modelos sem esse campo aceitam apenas a forma canônica disable_formatting=true (ou não respeitam o passthrough de forma alguma). A placa de modelos lista quais aliases cada modelo aceita.

Endpoints de imagem, vídeo, geração de áudio, transcrição e incorporação não aceitam essa flag, pois não há camada de formatação para desabilitar nesses endpoints.

Retenção de mídia gerada

Imagens, vídeos e áudios gerados são retornados como URLs assinadas válidas por 7 dias. Depois disso, a URL para de funcionar e o ativo desaparece - não há um endpoint de re-assinatura. Salve o que quiser antes do prazo de 7 dias acabar.

Erros

OpenAI envelope no chat / respostas / imagens / vídeos / áudio / busca / embeddings / reranks:

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 envelope no /v1/messages:

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

Referência de cabeçalhos

Cabeçalho	Obrigatório	Propósito
`Authorization` / `x-api-key`	sim	Autenticação por token de portador
`Content-Type`	Sim, no POST	`application/json` ou `multipart/form-data`
`Accept`	Não	`text/event-stream` forçar o SSE nos endpoints do chat
`anthropic-version`	Ao ligar `/v1/messages`	Versão da API Anthropic (por exemplo, `2023-06-01`)

Navegue pelos esquemas de parâmetros por modelo em Providers and Models. Quando você clica em um modelo específico, todos os parâmetros que o modelo aceitam - tipo, padrão, alcance, valores permitidos, flags condicionais - são documentados em uma tabela gerada a partir do banco de dados ativo.