Référence API | EmpirioLabs AI Docs

EmpirioLabs parle des formes de requêtes compatibles OpenAI et Anthropics. Insérez n’importe quel SDK, pointez-le vers https://api.empiriolabs.ai, et authentifiez-vous avec votre clé API EmpirioLabs. Chaque terminaison ci-dessous fonctionne contre n’importe quel client OpenAI ou Anthropic sans changement.

Authentification

Chaque demande nécessite un jeton porteur. L’un ou l’autre des en-têtes est accepté sur chaque terminaison:

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 )

Surface de point final

Complétions de discussion

Discussion compatible OpenAI. Streaming, appel d’outils, vision, entrée audio, mode JSON, sortie structurée, contrôles de raisonnement.

Achèvements hérités

Des complétions d’invites compatibles OpenAI pour les modèles qui annoncent POST /v1/completions.

Anthropic Messages

Rendez-vous sans rendez-vous pour les clients SDK d’Anthropic. tool_use / tool_result blocs aller-retour proprement.

Images

Générer, éditer, inpainter, variations d’images. URL CDN hébergées, signé depuis 7 jours.

Vidéo

Génération vidéo asynchrone. En retour un job_id; Interrogez le point de terminaison des jobs pour obtenir l’URL.

Audio (TTS, musique, voix)

TTS plus streaming en temps réel TTS (Inworld), génération de musique / podcast / effets spéciaux, gestion de clones de voix.

Agents

Tâches d’agent utilisant des outils de longue durée. Démarrez, sonde, diffusez les messages, arrêtez tôt.

Transcription

Murmure / Deepgram / Perruche. Téléversement en plusieurs parties ou file_url.

Recherche et recherche

Exa, Tavily, Linkup, Perplexity Cherchez. Filtres de domaine, plages de dates, biais géographique.

Génération 3D

Génération asynchrone d’images vers 3D. En retour un job_id; poll pour l’URL GLB signée.

Détection

POST /v1/detect - Détection IA GPTZero, scan de bibliographie, analyse de source.

Encastrements

Des embeddings compatibles OpenAI. Texte multilingue + embeddeurs multimodaux.

Reclassements

Reclassement sémantique des documents. Triez les candidats à la récupération par pertinence pour le raffinement RAG et de recherche.

URL des fichiers

Passez n’importe quelle URL publique sur les champs d’entrée. Pas de téléchargement, pas de re-signature - les sorties générées sont valables pendant 7 jours.

Emplois

Interrogez le statut / le résultat de toute génération asynchrone. State a conservé 1 heure après la fin de la partie.

Modèles

Catalogue en direct avec les prix, le schéma des paramètres, les indicateurs de capacité, les régions.

Erreurs

Enveloppes d’erreur compatibles OpenAI et Anthropic.

Complétions de discussion

POST /v1/chat/completions

Passez n’importe quel modèle capable de chat du catalogue comme model. Le streaming utilise des événements envoyés par serveur avec data: ... lignes et un 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
>   }'

Les paramètres acceptés de chaque modèle sont affichés sur sa page docs (par exemple temperature, top_p, enable_thinking, reasoning_effort, web_search_tier). Parcourez-les sous Fournisseurs et Modèles.

Modéliser les paramètres entre les points de terminaison

Les paramètres spécifiques au modèle annoncés sur la page du modèle et dans GET /v1/models/\{id\} peuvent être envoyés à /v1/chat/completions, /v1/responses et /v1/messages lorsque ce modèle prend en charge le point de terminaison. La passerelle adapte les formes de requête pour que les mêmes contrôles atteignent le modèle sous-jacent.

Pour les modèles capables de penser, enable_thinking et thinking_budget sont acceptés sur les trois points de terminaison textuels. Sur /v1/messages, vous pouvez aussi utiliser la pensée de style anthropique:

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

Cela correspond aux mêmes contrôles enable_thinking=true et thinking_budget=1024 utilisés par les Complétions et Réponses de Chat.

Achèvements hérités

POST /v1/completions

Utilisez ce point de terminaison pour les clients compatibles OpenAI qui envoient toujours un prompt brut au lieu de messages de chat. Seuls les modèles qui indiquent POST /v1/completions dans supported_endpoints acceptent cette forme.

Le streaming utilise les événements envoyés par le serveur et inclut l’utilisation lorsque le service modèle les rapporte.

$ 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

Disponible pour tout client SDK Anthropic - les mêmes modèles accessibles sur /v1/chat/completions et /v1/responses sont accessibles ici sous la forme 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 et tool_result blocs aller-retour proprement. Les tableaux de contenu mixte text-plus-tool_use sont préservés.

Génération d’images

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

Les flux d’édition d’images acceptent image: ["https://..."] jusqu’à la limite documentée du modèle (3 pour qwen-image-2-0, 9 pour wan-2-7-image, 14 pour seedream-5-0-lite). Les modes ensembles d’images génèrent des séries cohérentes - voir la page de chaque modèle pour le basculement.

Les URL retournées sont actives sur https://media.empiriolabs.ai et expirent après 7 jours. Sauvegardez tout ce que vous souhaitez garder avant que l’URL n’expire.

POST /v1/images/analysis exécute une analyse uniquement visuelle (sans génération) sur une ou plusieurs images d’entrée. À utiliser pour l’extraction de mise en page, la détection d’objets, l’OCR et des tâches d’inspection similaires où le modèle renvoie du texte ou du JSON décrivant l’image plutôt qu’une nouvelle image.

Génération vidéo

POST /v1/videos/generations

Toujours asynchrone - le point d’extrémité renvoie un job_id et une URL de sondage.

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

Génération audio

POST /v1/audio/speech synchrone, renvoie par défaut une URL hébergée; Passez response_format: "b64_json" pour des octets audio en ligne.

POST /v1/audio/speech:stream TTS en temps réel. Retourne des événements envoyés par le serveur pendant que le modèle synthétise. Moins de 130 ms time-to-first-byte sur Inworld TTS Mini, sous 250 ms sur Max. À utiliser pour les agents vocaux et la lecture interactive. Actuellement pris en charge sur Inworld TTS Mini / Max; d’autres modèles TTS utilisent l’extrémité synchrone.

POST /v1/audio/generations musique, podcast et génération d’effets sonores. Couvre Stable Audio, GLM TTS, MOSS, SoulX Podcast où la forme prompt-to-audio diffère de celle du TTS.

GET /v1/voices lister et gérer les voix, y compris des clones de voix personnalisés pour Inworld TTS. Utilisez les voice_id retournés sur l’un ou l’autre des points de terminaison de la parole.

$ 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

Accepte soit un upload de file en plusieurs parties, soit une charge utile JSON avec 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"

Les fichiers longs (plus de 5 minutes) sont automatiquement routés vers le système de tâches asynchrones - la réponse inclut un job_id au lieu d’un texte en ligne. Interrogez le point de terminaison des jobs pour récupérer la transcription finale.

Recherche et recherche

POST /v1/search surface de recherche unifiée pour les modèles de type récupération. Les params exacts acceptés par modèle sont présents sur la page de chaque modèle (par exemple, exa-search expose 28 params, dont category, livecrawl, subpages, summary_query, code_tokens).

POST /v1/research Recherche approfondie / modèles de récupération en plusieurs étapes (Exa Research, Perplexity Deep Research, Linkup Deep Search). Génère un rapport de recherche structuré avec des sources citées.

POST /v1/answer modèles directs de questions-réponses (Exa Answer). Donne une réponse concise plus des citations sans la forme complète du rapport.

$ 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

Tâches d’agent de longue durée, utilisant des outils (actuellement routées vers Manus). Soumettez une fois, puis interrogez le statut et step-by-step messages, ou arrêtez plus tôt.

POST /v1/agents/run fait double fonction:

Sans task_id cela commence une nouvelle tâche. La réponse porte la nouvelle task_id.
Avec task_id il envoie un message de suivi à une tâche existante. L’agent le prend à l’étape suivante de raisonnement.

GET /v1/agents/\{task_id\} récupérer l’état actuel de la tâche et le résultat final.

GET /v1/agents/\{task_id\}/messages lister chaque étape que l’agent a déjà émise. Utile pour tracer un raisonnement en temps réel à côté de la réponse finale.

POST /v1/agents/\{task_id\}/stop arrêter une tâche de course. La facturation se règle pour le travail déjà effectué par l’agent.

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

Génération 3D

POST /v1/3d/generations

La génération d’image en 3D est asynchrone. Le point de terminaison renvoie un job_id et une URL de sondage; interrogez le point de terminaison des jobs pour récupérer l’URL GLB signée finale.

$ 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 expose l’image complète, la résolution, l’échantillonneur, la texture et la surface des paramètres d’exportation du maillage sur sa page de modèle.

Détection

POST /v1/detect

Un point de terminaison spécialisé pour la classification de texte. Il alimente actuellement GPTZero (détection IA, analyse bibliographique, analyse de source). L’enum scan_type de chaque modèle choisit le chemin en amont; voir la documentation par modèle pour la surface complète des paramètres.

$ 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 est également joignable via /v1/chat/completions et /v1/responses - il faut passer le texte sur le corps du message et la passerelle adapte l’appel. Le résumé de la détection revient sous forme de message d’assistant; passer disable_formatting: true recevoir le JSON brut en amont à la place.

Encastrements

POST /v1/embeddings

Des embeddings compatibles OpenAI. Des textes multilingues et des embeddeurs multimodaux (texte + image + vidéo) sont 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"
>   }'

Reclassements

POST /v1/reranks

Triez les candidats documents par pertinence sémantique pour un query. Restitue l’index original de chaque document plus un score de pertinence de 0-1 (plus élevé = plus pertinent). Utilisez cela pour resserrer la sortie d’un magasin vectoriel / BM25 / récupérateur hybride avant de transmettre les meilleurs résultats à un modèle de langage - la dernière étape standard d’un 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
>   }'

L’échange optionnel de paramètres instruct entre la récupération Q&A (par défaut) et le tri par similarité sémantique pure - voir la page du modèle qwen3-rerank pour la table complète des paramètres.

Objet d’utilisation

Chaque terminaison qui facture l’utilisation renvoie un champ usage sur la réponse (et sur le segment de diffusion du terminal). Forme de base:

cost_usd - le montant exact que votre compte a été facturé pour la demande. Autoritaire.
prompt_tokens / completion_tokens / total_tokens - pour les mannequins de type chat.
Champs de cache (cache_read_input_tokens, cache_creation_input_tokens) - lorsque la mise en cache des invites s’applique.

Les modèles avec des tarifs en amont à niveaux, par appel ou à prix variant appliquent des champs supplémentaires sur usage afin que vous puissiez voir quel taux a été appliqué:

Tarif à palier / variant. Les travailleurs apposent un discriminateur de niveau sur usage lorsque la même dimension comporte plusieurs tarifs. Le champ principal est pricing_tier_label (lisible par l’humain, par exemple "Medium context" / "Pro" / "2K"). Les ouvriers plus âgés peuvent estampiller directement la dimension brute (resolution, quality, mode, rate_tier). Le tableau de bord affiche le badge à partir de la pièce présente.
Tarification par appel. Les travailleurs qui facturent chaque invocation d’outil (recherche, récupération, exécution de code, etc.) comptent sous tool_calls_details.<tool>.invocation ou tool_usage.<tool>. Le tableau de bord développe automatiquement ces informations en une répartition par outil.
Tarification par dimension. Les travailleurs qui facturent plusieurs dimensions dans une même requête (par exemple jetons de citation + jetons de raisonnement + requêtes de recherche sur des modèles de recherche approfondie) marquent chaque dimension comme un champ à part entière (citation_tokens, reasoning_tokens, num_search_queries, etc.).

Les mêmes champs dirigent la répartition du badge de niveau et par outil dans les journaux d’utilisation du tableau de bord, et ils sont également renvoyés par le point d’extrémité historique GET /v1/account/usage sous le metadata.worker_usage de chaque événement (plus un tableau tool_breakdown structuré pour les modèles par appel). Donc, que vous lisiez l’utilisation des réponses en direct, l’historique d’utilisation des comptes ou votre tableau de bord, la répartition des niveaux et des facturations correspondent exactement.

URL des fichiers

EmpirioLabs n’héberge pas les téléchargements des utilisateurs. Passez n’importe quelle URL publique directement sur le champ d’entrée du point de terminaison du modèle:

Famille de terminaux	Champ d’entrée	Accepte
Complétions de chat (vision)	`content[].image_url.url`	Toute URL d’image publique ou `data:` URI
Complétions de discussion (audio)	`content[].audio_url.url`	Toute URL audio publique
Génération d’images (modification / variation)	`image: ["https://..."]`	Jusqu’à N URL (limite spécifique au modèle)
Génération vidéo (i2v / r2v / montage)	`image: "https://..."` / `video: "https://..."`	URL publiques
Audio TTS / musique	n/a (entrée uniquement texte)	-
Transcription audio	`file_url: "https://..."` ou `file=@local.mp3` multiparties	URL publique ou téléversement direct de courts extraits
Recherche	n/a (texte de requête)	-
Embeddings (multimodal)	`input[].url` (image/video article)	URL publiques
Reclassements	n/a (requête texte + documents texte)	-

Pour la transcription audio spécifiquement, le téléchargement direct en plusieurs parties sur /v1/audio/transcriptions est le chemin pris en charge pour les clips privés qui ne sont pas sur une URL - ces octets sont directement dirigés vers le travailleur speech-to-text sans stockage persistant.

Les URL de sortie générées sont signées et expirent 7 jours après la création. Il n’y a pas de point de re-signation. Sauvegardez tout ce que vous devez conserver - à la fois l’URL et le binaire - dans cette fenêtre.

Emplois asynchrones

GET /v1/jobs/<job-id> - interrogez le statut / le résultat final de toute génération asynchrone ou travail de transcription.

L’état du poste est conservé 1 heure après l’achèvement.

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 }

Lorsque status est completed, le champ result porte la réponse complète sous la même forme que l’extrémité synchrone aurait retournée.

Le délai d’attente HTTP entrant est 15 minutes. Des complétions de chat synchrones proches de cette limite devraient stream=true de sorte que la sortie partielle revienne et que la connexion reste chaude.

Modèles

GET /v1/models - listez tous les modèles disponibles.

GET /v1/models/<model-id> - schéma complet pour un modèle, y compris sa table de paramètres.

GET /v1/models?format=openrouter renvoie la forme OpenRouter listant les modèles marqués prêts à l’ingestion du partenaire. Voir OpenRouter Model Listing pour les champs de réponse exacts.

Chaque modèle donne:

Terrain	Description
`id`	Projecteur canonique (par exemple `wan-2-7-image`)
`description`	Description marketing courte
`category`	Texte / image / vidéo / audio / transcription / recherche / outils / intégration / reclassement
`input_modalities`	Ce que le modèle accepte
`output_modalities`	Ce que le modèle émet
`context_window`	Jetons (chat) ou null (média)
`region`	Région serveur
`logo`	URL CDN du logo du modèle
`pricing_rows`	Débits par jeton, par image, par seconde ou par appel
`supported_endpoints`	Quels `/v1/...` terminaux acceptent ce modèle
`parameters`	Schéma complet - nom, type, défaut, min/max, valeurs autorisées, descriptions
`features`	Tags comme streaming, vision, 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 drapeau

De nombreux sites de chat, recherche, recherche et reclassement acceptent un drapeau disable_formatting=true. Lorsqu’il est défini sur un modèle de support, le travailleur saute la mise en forme côté serveur EmpirioLabs (réécriture de citations, bloc Références, Markdown en bloc de réflexion, etc.) et renvoie la forme de la charge utile en amont mot pour mot.

La couverture est annoncée par modèle. Vérifiez supports_passthrough dans GET /v1/models/\{id\} pour confirmer qu’un modèle spécifique honore le drapeau. Les modèles qui font de la publicité supports_passthrough: true acceptent également les alias raw=true, passthrough=true et raw_response=true. Les modèles sans ce champ n’acceptent que la forme canonique disable_formatting=true (ou ne respectent pas du tout le passthrough). La carte modèle indique quels alias chaque modèle accepte.

Les terminaux d’image, de vidéo, de génération audio, de transcription et d’intégration n’acceptent pas ce drapeau, car il n’y a pas de couche de mise en forme à désactiver sur ces points.

Rétention des médias générés

Les images, vidéos et audio générés sont renvoyés sous forme d’URL signée valables 7 jours. Après cela, l’URL cesse de fonctionner et l’asset disparaît - il n’y a pas de point de re-sign. Sauvegardez tout ce que vous souhaitez garder avant l’expiration de la fenêtre de 7 jours.

Erreurs

Enveloppe OpenAI sur le chat / réponses / images / vidéos / audio / recherche / embeddings / reclassements:

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 enveloppe sur /v1/messages:

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

Référence des en-têtes

En-tête	Obligatoire	Objectif
`Authorization` / `x-api-key`	Oui	Authentification par jeton porteur
`Content-Type`	Oui, sur POST	`application/json` ou `multipart/form-data`
`Accept`	non	`text/event-stream` forcer SSE sur les points de terminaison du chat
`anthropic-version`	Quand on appelle `/v1/messages`	Version de l’API Anthropic (par exemple `2023-06-01`)

Parcourez les schémas de paramètres par modèle sous Providers and Models. Lorsque vous cliquez sur un modèle spécifique, chaque paramètre accepté par le modèle - type, défaut, plage, valeurs autorisées, drapeaux conditionnels - est documenté dans une table générée à partir de la base de données en ligne.