API-Referenz

EmpirioLabs spricht OpenAI- und Anthropic-kompatible Anfrageformen. Fügen Sie ein beliebiges SDK ein, richten Sie es auf https://api.empiriolabs.ai und authentifizieren Sie sich mit Ihrem EmpirioLabs-API-Schlüssel. Jeder folgende Endpunkt arbeitet unverändert gegen jeden OpenAI- oder Anthropic-Client.

Authentifizierung

Jede Anfrage erfordert ein Inhaber-Token. Beide Header werden auf jedem Endpunkt akzeptiert:

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
)

Endpunktfläche

Chat-Abschlüsse

POST /v1/chat/completions

Geben Sie jedes chatfähige Modell aus dem Katalog als model durch. Streaming verwendet Server-Send-Events mit data: ... Zeilen und einem finalen 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
>
  }'

Modelliere Parameter über Endpunkte hinweg

Modellspezifische Parameter, die auf der Modellseite und in GET /v1/models/\{id\} beworben werden, können an /v1/chat/completions, /v1/responses und /v1/messages gesendet werden, wenn dieses Modell den Endpunkt unterstützt. Das Gateway passt Anfrageformen an, sodass dieselben Steuerungen das zugrunde liegende Modell erreichen.

Für denkfähige Modelle werden enable_thinking und thinking_budget auf allen drei Textendpunkten akzeptiert. Auf /v1/messages können Sie auch anthropisches Denken anwenden:

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

Das entspricht denselben enable_thinking=true und thinking_budget=1024 Steuerungen, die von Chat-Abschluss und -Antworten verwendet werden.

Vermächtnisabschlüsse

POST /v1/completions

Nutzen Sie diesen Endpunkt für OpenAI-kompatible Clients, die trotzdem eine rohe prompt senden, anstatt Chat-messages. Nur Modelle, die POST /v1/completions in supported_endpoints listen, akzeptieren diese Form.

Streaming verwendet Server-Send-Events und schließt die Nutzung ein, wenn der Modelldienst dies meldet.

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

POST /v1/messages

Drop-in für jeden Anthropic SDK-Client – die gleichen Modelle, die auf /v1/chat/completions und /v1/responses verfügbar sind, sind hier unter der Form Anthropic Messages erreichbar.

$
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 und tool_result Blocks sauber hin und zurück. Gemischte text-plus-tool_use Content-Arrays werden erhalten.

Bilderzeugung

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

Bildbearbeitungsflüsse akzeptieren image: ["https://..."] bis zur dokumentierten Grenze des Modells (3 für qwen-image-2-0, 9 für wan-2-7-image, 14 für seedream-5-0-lite). Bildset-Modi erzeugen kohärente Reihen – siehe die Seite jedes Modells für den Umschalter.

Zurückgegebene URLs sind auf https://media.empiriolabs.ai verfügbar und laufen nach 7 Tagen ab. Speichere alles, was du behalten möchtest, bevor die URL abläuft.

POST /v1/images/analysis führt eine reine visuelle Analyse (ohne Generierung) an einem oder mehreren Eingabebildern durch. Verwendung für Layout-Extraktion, Objekterkennung, OCR und ähnliche Inspektionsaufgaben, bei denen das Modell Text oder JSON zurückgibt, das das Bild beschreibt, anstatt ein neues Bild.

Videogenerierung

POST /v1/videos/generations

Immer asynchron – der Endpunkt liefert eine job_id und eine Abfrage-URL zurück.

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

Audioerzeugung

POST /v1/audio/speech synchron liefert standardmäßig eine gehostete URL zurück; Geben Sie response_format: "b64_json" für Inline-Audiobytes weiter.

POST /v1/audio/speech:stream Echtzeit-TTS. Gibt Server-Send-Events zurück, während das Modell synthesizert. Unter 130 ms time-to-first-byte auf Inworld TTS Mini, unter 250 ms auf Max. Verwendung für Sprachagenten und interaktive Wiedergabe. Derzeit unterstützt auf Inworld TTS Mini / Max; andere TTS-Modelle verwenden den synchronen Endpunkt.

POST /v1/audio/generations Musik-, Podcast- und Soundeffektgenerierung. Behandelt Stable Audio, GLM TTS, MOSS, SoulX Podcast, wobei sich die prompt-to-audio Form von TTS unterscheidet.

GET /v1/voices listen und verwalten Stimmen, einschließlich benutzerdefinierter Stimmklone für Inworld TTS. Verwenden Sie die zurückgegebene voice_id an einem der Sprachendpunkte.

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

Transkription

POST /v1/audio/transcriptions

Akzeptiert entweder einen mehrteiligen file-Upload oder einen JSON-Payload mit 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"

Lange Dateien (über 5 Minuten) werden automatisch an das asynchrone Job-System weitergeleitet – die Antwort enthält eine job_id statt Inline-Text. Abfrage des Endpunkts der Jobs, um das endgültige Transkript abzurufen.

Suche und Forschung

POST /v1/search einheitliche Suchoberfläche für Abrufmodelle. Die exakt akzeptierten Params pro Modell befinden sich auf der Seite jedes Modells (z. B. gibt exa-search 28 Params offen, darunter category, livecrawl, subpages, summary_query, code_tokens).

POST /v1/research Deep-Research- / mehrstufige Abrufmodelle (Exa Research, Perplexity Deep Research, Linkup Deep Search). Erstellt einen strukturierten Forschungsbericht mit zitierten Quellen.

POST /v1/answer direkte Frage-Antwort-Modelle (Exa Answer). Gibt eine prägnante Antwort plus Zitate zurück, ohne die vollständige Berichtsform.

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

Agenten

Langlaufende, tool-nutzende Agentenaufgaben (derzeit an Manus weitergeleitet). Reichen Sie einmal ein, dann fragen Sie nach Status und step-by-step Nachrichten ab oder hören Sie frühzeitig auf.

POST /v1/agents/run erfüllt doppelte Aufgaben:

• Ohne task_id beginnt eine neue Aufgabe. Die Antwort trägt die neue task_id.
• Mit task_id sendet es eine Folge-Nachricht an eine bestehende Aufgabe. Der Agent nimmt es bei seinem nächsten Überlegungsschritt auf.

GET /v1/agents/\{task_id\} den aktuellen Status und das Endergebnis der Aufgabe abrufen.

GET /v1/agents/\{task_id\}/messages liste jeden Schritt auf, den der Agent bisher gemacht hat. Nützlich, um neben der endgültigen Antwort eine Live-Schlussfolge zu erstellen.

POST /v1/agents/\{task_id\}/stop eine laufende Aufgabe stoppen. Die Abrechnung begleicht die bereits erledigte Arbeit, die der Agent bereits erledigt hat.

$
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

Die Bild-zu-3D-Generierung ist asynchron. Der Endpunkt liefert eine job_id und eine Abfrage-URL zurück; Abfrage des Jobs-Endpunkts, um die endgültige signierte GLB-URL abzurufen.

$
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 stellt das vollständige Bild, die Auflösung, den Sampler, die Textur und die Mesh-Exportparameter auf seiner Modellseite sichtbar.

Erkennung

POST /v1/detect

Spezialisiertes Textklassifikations-Endpunkt. Derzeit betreibt GPTZero (KI-Erkennung, Bibliografie-Scan, Quellanalyse). Jedes Modells scan_type Enum wählt den Upstream-Weg; Siehe die Pro-Model-Dokumentation für die vollständige Parameteroberfläche.

$
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 ist außerdem über /v1/chat/completions und /v1/responses erreichbar – der Text wird im Nachrichtentext weitergegeben und das Gateway passt den Anruf an. Die Erkennungszusammenfassung erscheint als Assistenten-Nachricht; passieren disable_formatting: true, um stattdessen das rohe Upstream-JSON zu erhalten.

Einbettungen

POST /v1/embeddings

OpenAI-kompatible Embeddings. Mehrsprachige Text- und multimodale (Text + Bild + Video) Einbettungen sind verfügbar.

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

Umstrukturierungen

POST /v1/reranks

Sortiere den Kandidaten documents nach semantischer Relevanz für eine query. Gibt den ursprünglichen Index jedes Dokuments plus einen Relevanzwert von 0-1 zurück (höher = relevanter). Nutzen Sie dies, um die Ausgabe eines Vektorspeichers / BM25 / Hybrid-Retrievers zu straffen, bevor Sie die Top-Hits an ein Sprachmodell weitergeben – den standardmäßigen letzten Schritt in einer 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
>
  }'

Der optionale instruct Parameter wechselt zwischen Q&A-Abruf (Standard) und reiner semantischer Ähnlichkeitssortierung – siehe die qwen3-rerank model-Seite für die vollständige Parametertabelle.

Nutzungsobjekt

Jeder Endpunkt, der den Verbrauch abrechnet, gibt in der Antwort (und im Terminal-Streaming-Chunk) ein usage Feld zurück. Grundform:

• cost_usd – der genaue Betrag, der auf Ihrem Konto für die Anfrage abgerechnet wurde. Autoritär.
• prompt_tokens / completion_tokens / total_tokens – für Chat-Models.
• Cache-Felder (cache_read_input_tokens, cache_creation_input_tokens) – wenn Prompt-Caching angewendet wird.

Modelle mit gestuften, pro Anruf oder variant preisierten Upstreams markieren zusätzliche Felder auf usage, damit Sie sehen können, welche Rate angewendet wurde:

• Stufen- / Variantepreis. Arbeiter setzen einen Stufendiskriminator auf usage, wenn dieselbe Dimension mehr als einen Tarif hat. Das Hauptfeld ist pricing_tier_label (menschenlesbar, z. B. "Medium context" / "Pro" / "2K"). Ältere Arbeiter stempeln die Rohmaße möglicherweise direkt (resolution, quality, mode, rate_tier). Das Armaturenbrett zeigt das Emblem von dem, was vorhanden ist.
• Preisgestaltung pro Aufruf. Arbeiter, die pro Werkzeugaufruf (Suche, Abruf, Codeausführung usw.) abrechnen, zählen Stempel unter tool_calls_details.<tool>.invocation oder tool_usage.<tool>. Das Dashboard erweitert diese automatisch zu einer Aufschlüsselung pro Werkzeug.
• Preisgestaltung pro Dimension. Arbeiter, die mehrere Dimensionen in einer Anfrage abrechnen (z. B. Zitationstoken + Argumentationstoken + Suchanfragen bei Deep-Research-Modellen), stempeln jede Dimension als eigenes Feld (citation_tokens, reasoning_tokens, num_search_queries usw.).

Dieselben Felder steuern das Tier-Badge und die Aufschlüsselung pro Werkzeug in den Dashboard-Nutzungsprotokollen und werden auch vom GET /v1/account/usage-History-Endpunkt unter dem metadata.worker_usage jedes Ereignisses zurückgegeben (plus einem strukturierten tool_breakdown-Array für Per-Call-Modelle). Egal, ob Sie Live-Response-Nutzung, Kontoverlauf oder Ihr Dashboard lesen – Tier- und Abrechnungsaufschlüsselung stimmen exakt überein.

Datei-URLs

EmpirioLabs hostet keine Nutzeruploads. Geben Sie eine beliebige öffentliche URL direkt auf das Eingabefeld des Modellendpunkts ein:

Speziell für Audiotranskription ist der Multipart-Direct-Upload auf /v1/audio/transcriptions der unterstützte Pfad für private Clips, die nicht auf einer URL sind – diese Bytes fließen direkt zum speech-to-text Worker ohne persistente Speicherfläche.

Asynchrone Jobs

GET /v1/jobs/<job-id> – befrage den Status / das Endergebnis eines asynchronen Generierungs- oder Transkriptionsjobs.

Der Jobstatus wird für 1 Stunde nach Abschluss beibehalten.

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
}

Wenn status completed ist, trägt das result Feld die vollständige Antwort in derselben Form, die der synchrone Endpunkt zurückgegeben hätte.

Modelle

GET /v1/models – listen Sie alle verfügbaren Modelle auf.

GET /v1/models/<model-id> – vollständiges Schema für ein Modell, einschließlich seiner Parametertabelle.

GET /v1/models?format=openrouter liefert die OpenRouter-Modelllisting-Form für Modelle zurück, die als bereit für Partneraufnahme gekennzeichnet sind. Siehe OpenRouter Model Listing für die genauen Antwortfelder.

Jedes Modell liefert:

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

Viele Chat-, Such-, Forschungs- und Reranking-Endpunkte akzeptieren eine disable_formatting=true-Markierung. Wenn er auf ein unterstützendes Modell gesetzt ist, überspringt der Worker die serverseitige Formatierung von EmpirioLabs (Zitationsumschreibung, Referenzblock, Thinking-Block Markdown usw.) und gibt die Upstream-Payload-Form wortwörtlich zurück.

Der Versicherungsschutz wird pro Modell beworben. Überprüfe supports_passthrough in GET /v1/models/\{id\}, um zu bestätigen, dass ein bestimmtes Modell die Flagge respektiert. Modelle, die supports_passthrough: true bewerben, akzeptieren auch die Aliase raw=true, passthrough=true und raw_response=true. Modelle ohne dieses Feld akzeptieren nur die kanonische disable_formatting=true Form (oder akzeptieren Passthrough überhaupt nicht). Die Modellkarte listet auf, welche Aliase jedes Modell akzeptiert.

Bild-, Video-, Audiogenerierungs-, Transkriptions- und Embedding-Endpunkte akzeptieren diese Flagge nicht, da es auf diesen Endpunkten keine Formatierungsschicht gibt, die deaktiviert werden kann.

Generierte Medienbindung

Generierte Bilder, Videos und Audiodateien werden als signierte URLs zurückgegeben, die für 7 Tage gültig sind. Danach funktioniert die URL nicht mehr und das Asset ist verschwunden – es gibt keinen Neusigning-Endpunkt. Spar alles, was du behalten möchtest, bevor das 7-Tage-Zeitfenster abläuft.

Fehler

OpenAI-Umschlag im Chat / Antworten / Bilder / Videos / Audio / Suche / Einbettungen / Rerankings:

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 Umschlag auf /v1/messages:

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

Header-Referenz