API Reference

EmpirioLabs speaks OpenAI-, Anthropic-, and Google Gemini-compatible request shapes. Drop in any of those SDKs, point it at https://api.empiriolabs.ai, and authenticate with your EmpirioLabs API key. Every endpoint below works against the matching client unchanged.

Authentication

Every request requires a bearer token. Either header is accepted on every endpoint:

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

Gemini-compatible routes additionally accept the key in the x-goog-api-key header or the ?key= query parameter, matching Gemini client defaults.

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
)

Endpoint surface

Chat completions

POST /v1/chat/completions

Pass any chat-capable model from the catalog as model. Streaming uses Server-Sent Events with data: ... lines and a final data: [DONE].

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

Responses API

POST /v1/responses

OpenAI Responses-compatible. The same models available on /v1/chat/completions accept the Responses request shape: input, instructions, streaming, tool calling, and structured output via text.format.

$
curl https://api.empiriolabs.ai/v1/responses \
>
  -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "model": "seed-2-0-pro",
>
    "input": "Write a one-line launch checklist.",
>
    "instructions": "Be concise."
>
  }'

Model parameters across endpoints

Model-specific parameters advertised on the model page and in GET /v1/models/{id} can be sent to /v1/chat/completions, /v1/responses, and /v1/messages when that model supports the endpoint. The gateway adapts request shapes so the same controls reach the underlying model.

For thinking-capable models, enable_thinking and thinking_budget are accepted on all three text endpoints. On /v1/messages, you can also use Anthropic-style thinking:

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

That maps to the same enable_thinking=true and thinking_budget=1024 controls used by Chat Completions and Responses.

Legacy completions

POST /v1/completions

Use this endpoint for OpenAI-compatible clients that still send a raw prompt instead of chat messages. Only models that list POST /v1/completions in supported_endpoints accept this shape.

Streaming uses Server-Sent Events and includes usage when the model service reports it.

$
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 Messages

POST /v1/messages

Drop-in for any Anthropic SDK client: the same models accessible on /v1/chat/completions and /v1/responses are reachable here under the Anthropic Messages shape.

$
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 and tool_result blocks round-trip cleanly. Mixed text-plus-tool_use content arrays are preserved.

Gemini-compatible endpoint

POST /v1beta/models/{model}:generateContent

Native Google Gemini request and response shapes for any chat model. POST /v1beta/models/{model}:streamGenerateContent?alt=sse streams Server-Sent Events (each event is a partial GenerateContentResponse; there is no [DONE] sentinel), and POST /v1beta/models/{model}:countTokens returns a fast token estimate.

Authenticate with the x-goog-api-key header or the ?key= query parameter. The google-genai SDKs work by pointing their base URL at https://api.empiriolabs.ai; pricing, parameters, and billing match /v1/chat/completions.

$
curl "https://api.empiriolabs.ai/v1beta/models/qwen3-7-max:generateContent" \
>
  -H "x-goog-api-key: $EMPIRIOLABS_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "contents": [{ "role": "user", "parts": [{ "text": "Hello!" }] }],
>
    "generationConfig": { "temperature": 0.7, "maxOutputTokens": 256 }
>
  }'

Image generation

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

Image generation returns the async {job_id, poll_url} envelope by default; poll the jobs endpoint for the finished result. Pass sync: true (alias wait: true) to hold the request open and receive the finished OpenAI-shaped data[] body directly, which is what OpenAI SDK images.generate integrations expect. A sync request that outlasts the wait window falls back to the async envelope with the job still running.

Image-edit flows accept image: ["https://..."] with up to the model’s documented limit (3 for qwen-image-2-0, 9 for wan-2-7-image, 14 for seedream-5-0-lite). Image-set modes generate cohesive series; see each model’s page for the toggle.

Returned URLs live on https://media.empiriolabs.ai and expire after 7 days. Save anything you want to keep before the URL expires.

POST /v1/images/analysis runs vision-only analysis (no generation) on one or more input images. Use for layout extraction, object detection, OCR, and similar inspection tasks where the model returns text or JSON describing the image rather than a new picture.

Video generation

POST /v1/videos/generations

Always async: the endpoint returns a job_id and a polling URL.

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

Generation templates

Effect templates apply curated creative treatments to normal image and video generation requests.

GET /v1/templates lists the public template catalog. Use GET /v1/images/templates or GET /v1/videos/templates when you already know the modality.

GET /v1/videos/compose/recipes lists full-production video recipes, caption styles, input requirements, and recommended model options.

POST /v1/videos/compose starts a Compose recipe job:

• mode: "plan" returns an editable storyboard from a brief or script.
• mode: "render" takes a storyboard and produces the final MP4.
• mode: "edit" takes a prior render manifest plus scene edit instructions.

$
curl https://api.empiriolabs.ai/v1/videos/compose \
>
  -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "recipe": "custom",
>
    "mode": "plan",
>
    "brief": "Explain why cold plunge clips went viral.",
>
    "aspect_ratio": "9:16",
>
    "scene_count": 5
>
  }'

Compose returns the same async job envelope as video generation. Poll GET /v1/jobs/{job_id} until the result is ready. See Generation Templates for the end-to-end plan, render, edit, and usage workflow.

Audio generation

POST /v1/audio/speech synchronous, returns a hosted URL by default; pass response_format: "b64_json" for inline audio bytes.

POST /v1/audio/speech:stream real-time TTS. Returns Server-Sent Events as the model synthesizes. Sub-130ms time-to-first-byte on Inworld TTS Mini, sub-250ms on Max. Use for voice agents and interactive playback. Currently supported on Inworld TTS Mini / Max; other TTS models use the synchronous endpoint.

POST /v1/audio/generations music, podcast, and sound-effect generation. Covers Stable Audio, GLM TTS, MOSS, SoulX Podcast where the prompt-to-audio shape differs from TTS.

GET /v1/voices list and manage voices, including custom voice clones for Inworld TTS. Use the returned voice_id on either speech endpoint.

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

Transcription

POST /v1/audio/transcriptions

Accepts either a multipart file upload or a JSON payload with 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"

Long files (over 5 minutes) auto-route to the async job system: the response includes a job_id instead of inline text. Poll the jobs endpoint to retrieve the final transcript.

Search and research

POST /v1/search unified search surface for retrieval-style models. The exact accepted params per model live on each model’s page (e.g. exa-search exposes 28 params including category, livecrawl, subpages, summary_query, code_tokens).

POST /v1/research deep research / multi-step retrieval models (Exa Research, Perplexity Deep Research, Linkup Deep Search). Generates a structured research report with cited sources.

POST /v1/answer direct question-answering models (Exa Answer). Returns a concise answer plus citations without the full report shape.

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

Agents

Long-running, tool-using agent tasks (currently routed to Manus). Submit once, then poll for status and step-by-step messages, or stop early.

POST /v1/agents/run does double duty:

• With no task_id it starts a fresh task. The response carries the new task_id.
• With task_id it sends a follow-up message to an existing task. The agent picks it up on its next reasoning step.

GET /v1/agents/{task_id} retrieve the task’s current status and final result.

GET /v1/agents/{task_id}/messages list every step the agent has emitted so far. Useful for rendering a live reasoning trace alongside the final answer.

POST /v1/agents/{task_id}/stop stop a running task. Billing settles for the work the agent already completed.

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

3D Generation

POST /v1/3d/generations

Image-to-3D generation is async. The endpoint returns a job_id and a polling URL; poll the jobs endpoint to retrieve the final signed GLB URL.

$
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 exposes the full image, resolution, sampler, texture, and mesh export parameter surface on its model page.

Detection

POST /v1/detect

Specialized text-classification endpoint. Currently powers GPTZero (AI-detection, bibliography scan, source analysis). Each model’s scan_type enum picks the upstream path; see the per-model docs for the full parameter surface.

$
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 is also reachable via /v1/chat/completions and /v1/responses: pass the text on the message body and the gateway adapts the call. The detection summary comes back as the assistant message; pass disable_formatting: true to receive the raw upstream JSON instead.

Embeddings

POST /v1/embeddings

OpenAI-compatible embeddings. Multilingual text and multimodal (text + image + video) embedders are available.

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

Reranks

POST /v1/reranks

Sort candidate documents by semantic relevance to a query. Returns each document’s original index plus a 0-1 relevance score (higher = more relevant). Use this to tighten the output of a vector store / BM25 / hybrid retriever before passing the top hits to a language model, the standard last step in a RAG pipeline.

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

The optional instruct parameter swaps between Q&A retrieval (default) and pure semantic-similarity sorting; see the qwen3-rerank model page for the full parameter table.

Batch API

Process large request sets asynchronously at 35% off each model’s list price. Batch runs chat and embeddings requests for batch-eligible models; check the batch_supported field on GET /v1/models (eligible model pages also show a Batch API pill).

1. Upload a JSONL input file with POST /v1/files (multipart, purpose=batch). Each line is {"custom_id": "...", "method": "POST", "url": "/v1/chat/completions", "body": {...}}; /v1/embeddings lines work the same way. Up to 50,000 requests per file.
2. Create the batch with POST /v1/batches, passing the returned input_file_id.
3. Poll GET /v1/batches/{batch_id} until the batch reaches a terminal status. GET /v1/batches lists recent batches, and POST /v1/batches/{batch_id}/cancel cancels one.
4. Download results with GET /v1/files/{output_file_id}/content. Each output line carries the custom_id plus the full response body; failed lines land in the error file.

$
curl https://api.empiriolabs.ai/v1/files \
>
  -H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
>
  -F "purpose=batch" \
>
  -F "file=@requests.jsonl"

Usage object

Every endpoint that bills usage returns a usage field on the response (and on the terminal streaming chunk). Base shape:

• cost_usd: exact amount your account was billed for the request. Authoritative.
• prompt_tokens / completion_tokens / total_tokens: for chat-style models.
• Cache fields (cache_read_input_tokens, cache_creation_input_tokens): when prompt caching applies.

Models with tiered, per-call, or variant pricing stamp extra fields on usage so you can see which rate was applied:

• Tier / variant pricing. A tier discriminator appears on usage when the same dimension has more than one rate. The primary field is pricing_tier_label (human-readable, e.g. "Medium context" / "Pro" / "2K"). Some models stamp the raw dimension directly instead (resolution, quality, mode, rate_tier). The dashboard renders the badge from whichever is present.
• Per-call pricing. Models that bill per tool invocation (search, fetch, code execution, etc.) report counts under tool_calls_details.<tool>.invocation or tool_usage.<tool>. The dashboard expands these into a per-tool breakdown automatically.
• Per-dimension pricing. Models that bill multiple dimensions in one request (e.g. citation tokens + reasoning tokens + search queries on deep-research models) report each dimension as its own field (citation_tokens, reasoning_tokens, num_search_queries, etc.).

The same fields drive the tier badge and per-tool breakdown on the dashboard usage logs, and they are also returned by the GET /v1/account/usage history endpoint under each event’s metadata.worker_usage, plus a structured top-level tool_breakdown array on events from per-call models. So whether you read live response usage, account-usage history, or your dashboard, the tier and billing breakdown match exactly. See Account Usage API for the full response shape, including the account balance, per-product spend, and page-level cache_hit_rate.

File URLs

EmpirioLabs does not host user uploads. Pass any public URL directly on the input field of the model endpoint:

For audio transcription specifically, the multipart-direct upload on /v1/audio/transcriptions is the supported path for private clips that aren’t on a URL; those bytes flow straight to the speech-to-text model service without persistent storage.

Async jobs

GET /v1/jobs/<job-id> polls the status / final result of any async generation or transcription job. GET /v1/jobs lists your last 100 jobs, filterable by status.

Job state is retained for 1 hour after completion.

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
}

When status is completed, the result field carries the full response in the same shape the synchronous endpoint would have returned.

Models

GET /v1/models lists every available model.

GET /v1/models/<model-id> returns the full schema for one model, including its parameter table.

GET /v1/models?format=openrouter returns the OpenRouter model-listing shape for models marked ready for partner ingestion. See OpenRouter Model Listing for the exact response fields.

Each model returns:

$
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 flag

Many chat, search, research, and rerank endpoints accept a disable_formatting=true flag. When set on a supporting model, the worker skips EmpirioLabs server-side formatting (citation rewriting, References block, thinking-block Markdown, etc.) and returns the upstream payload shape verbatim.

Coverage is advertised per-model. Check supports_passthrough in GET /v1/models/{id} to confirm a specific model honors the flag. Models that advertise supports_passthrough: true also accept the aliases raw=true, passthrough=true, and raw_response=true. Models without that field accept only the canonical disable_formatting=true form (or do not honor passthrough at all). The model card lists which aliases each model accepts.

Image, video, audio-generation, transcription, and embedding endpoints do not accept this flag, since there is no formatting layer to disable on those endpoints.

Generated media retention

Generated images, videos, and audio are returned as signed URLs that are valid for 7 days. After that, the URL stops working and the asset is gone; there is no re-sign endpoint. Save anything you want to keep before the 7-day window expires.

Errors

OpenAI envelope on chat / responses / images / videos / audio / search / 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 on /v1/messages:

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

Headers reference