API 참고 문헌

EmpirioLabs는 OpenAI 및 Anthropic 호환 요청 형태를 제공합니다. SDK를 넣고 https://api.empiriolabs.ai 방향으로 가리킨 후 EmpirioLabs API 키로 인증하세요. 아래 모든 엔드포인트는 변경 없이 어떤 OpenAI 또는 Anthropic 클라이언트에도 작동합니다.

인증

모든 요청은 베어러 토큰이 필요합니다. 모든 엔드포인트에서 어느 헤더든 허용됩니다:

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
)

종점 표면

채팅 완료

POST /v1/chat/completions

카탈로그에서 채팅이 가능한 모델을 model로 전달하세요. 스트리밍은 data: ... 대사와 최종 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
>
  }'

엔드포인트 간 모델 매개변수

모델 페이지와 GET /v1/models/\{id\}에 광고된 모델별 매개변수는 해당 모델이 엔드포인트를 지원할 때 /v1/chat/completions, /v1/responses, /v1/messages에 전송될 수 있습니다. 게이트웨이는 동일한 제어 장치가 기본 모델에 도달하도록 요청 형태를 조정합니다.

사고 능력 모델의 경우, 세 텍스트 엔드포인트 모두에서 enable_thinking와 thinking_budget가 모두 허용됩니다. /v1/messages에서는 인간 스타일의 사고도 사용할 수 있습니다:

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

이는 채팅 완료와 응답에서 사용하는 동일한 enable_thinking=true 및 thinking_budget=1024 컨트롤에 대응됩니다.

레거시 완성

POST /v1/completions

이 엔드포인트는 채팅 messages 대신 원시 prompt을 보내는 OpenAI 호환 클라이언트에 사용하세요. supported_endpoints POST /v1/completions 명시된 모델만 이 모양을 받아들입니다.

스트리밍은 서버 전송 이벤트를 사용하며, 모델 서비스가 보고할 때 사용량도 포함합니다.

$
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 메시지

POST /v1/messages

Anthropic SDK 클라이언트에 드롭인으로 접근할 수 있으며, /v1/chat/completions와 /v1/responses에서 접근 가능한 동일한 모델들은 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 블록과 tool_result 블록은 왕복 없이 깨끗합니다. 혼합 text-plus-tool_use 콘텐츠 배열은 보존됩니다.

이미지 생성

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

이미지 편집 플로우는 모델의 문서화된 한도(qwen-image-2-0 3, wan-2-7-image 9, seedream-5-0-lite 14)까지 image: ["https://..."]을 수용합니다. 이미지 세트 모드는 응집력 있는 직열을 생성합니다 - 토글은 각 모델의 페이지를 참조하세요.

반환된 URL은 https://media.empiriolabs.ai에서 실시간으로 사용되며 7일 후에 만료됩니다. URL이 만료되기 전에 보관하고 싶은 것은 모두 저장하세요.

POST /v1/images/analysis 하나 이상의 입력 이미지에 대해 시각 분석(생성 없음)을 실행합니다. 레이아웃 추출, 객체 감지, OCR 및 모델이 새 이미지 대신 텍스트나 JSON 반환하는 검사 작업에 사용됩니다.

비디오 생성

POST /v1/videos/generations

항상 비동기 - 엔드포인트는 job_id와 폴링 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
>
  }'

오디오 생성

POST /v1/audio/speech 동기식은 기본적으로 호스팅된 URL을 반환합니다; 인라인 오디오 바이트를 위해 response_format: "b64_json" 패스를 합니다.

POST /v1/audio/speech:stream 실시간 TTS. 모델이 합성될 때 서버에서 전송된 이벤트를 반환합니다. Inworld TTS Mini에서는 130ms 미만, Max는 250ms 미만으로 time-to-first-byte. 음성 에이전트와 인터랙티브 재생에 사용됩니다. 현재 Inworld TTS Mini / Max에서 지원되며; 다른 TTS 모델은 동기식 엔드포인트를 사용합니다.

POST /v1/audio/generations 음악, 팟캐스트, 그리고 효과음 생성. Stable Audio, GLM TTS, MOSS, SoulX Podcast prompt-to-audio 모양이 TTS와 다른 부분을 다룹니다.

GET /v1/voices Inworld TTS용 커스텀 음성 복제본을 포함해 음성 목록을 작성하고 관리할 수 있습니다. 반환된 voice_id 두 언어 중 어느 쪽 끝에 사용하세요.

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

전사

POST /v1/audio/transcriptions

멀티파트 file 업로드나 JSON 페이로드를 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"

5분 이상의 긴 파일들은 비동기 작업 시스템으로 자동 라우팅되며, 응답에는 인라인 텍스트 대신 job_id가 포함됩니다. 최종 성적표를 가져오기 위해 잡 엔드포인트를 폴링하세요.

검색 및 연구

POST /v1/search 검색 스타일 모델을 위한 통합 검색 표면입니다. 각 모델별 정확한 허용 매개변수는 각 모델 페이지에 존재합니다(예: exa-search category, livecrawl, subpages, summary_query, code_tokens 등 28개의 매개변수를 노출).

POST /v1/research 심층 연구/다단계 검색 모델(Exa Research, Perplexity Deep Research, Linkup Deep Search). 인용된 출처를 포함한 구조화된 연구 보고서를 생성합니다.

POST /v1/answer 직접 질문 답변 모델(Exa Answer). 전체 보고서 형태 없이 간결한 답변과 인용만 반환합니다.

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

에이전트

장기 실행 도구용 에이전트 작업(현재는 Manus로 라우팅됨). 한 번 제출한 후 상태와 step-by-step 메시지를 폴링하거나, 조기 중단하세요.

POST /v1/agents/run 두 가지 역할을 합니다:

• task_id 없으면 새로운 과제가 시작됩니다. 이 답변에는 새로운 task_id이 담겨 있습니다.
• task_id 있으면 기존 작업에 후속 메시지를 보냅니다. 에이전트는 다음 추론 단계에서 그것을 집어 든다.

GET /v1/agents/\{task_id\} 작업의 현재 상태와 최종 결과를 가져올 수 있습니다.

GET /v1/agents/\{task_id\}/messages 지금까지 에이전트가 내놓은 모든 단계를 나열하세요. 최종 답변과 함께 실시간 추론 트레이스를 제공하는 데 유용합니다.

POST /v1/agents/\{task_id\}/stop 진행 중인 작업을 멈추는 것. 청구는 에이전트가 이미 완료한 작업에 대해 합의합니다.

$
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 생성

POST /v1/3d/generations

이미지에서 3D로의 생성은 비동기 처리입니다. 엔드포인트는 job_id와 폴링 URL을 반환합니다; 작업 엔드포인트를 폴링하여 최종 서명된 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 모델 페이지에서 전체 이미지, 해상도, 샘플러, 텍스처, 메쉬 내보내기 파라미터 표면을 노출합니다.

탐지

POST /v1/detect

전문 텍스트 분류 엔드포인트. 현재 GPTZero(AI 감지, 참고문헌 탐색, 출처 분석)를 운영하고 있습니다. 각 모델의 scan_type 열거액은 상류 경로를 선택합니다; 전체 파라미터 표면은 모델별 문서를 참조하세요.

$
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는 /v1/chat/completions와 /v1/responses를 통해서도 접근 가능하며, 메시지 본문에 텍스트를 전달하면 게이트웨이가 통화를 자동으로 조정합니다. 탐지 요약은 보조 메시지로 돌아오고; disable_formatting: true 패스하여 원시 업스트림 JSON을 수신합니다.

임베딩

POST /v1/embeddings

OpenAI 호환 임베딩. 다국어 텍스트 및 다중 모달(텍스트 + 이미지 + 비디오) 임베더가 제공됩니다.

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

계급 변경

POST /v1/reranks

후보 documents를 query와의 의미적 관련성에 따라 정렬하세요. 각 문서의 원본 인덱스와 0-1의 관련성 점수(높을수록 더 관련성 높음)를 반환합니다. 이를 이용해 벡터 스토어 / BM25 / 하이브리드 리트리버의 출력을 더 좁히고, 상위 히트를 언어 모델에 전달하는 것이 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
>
  }'

선택적 instruct 매개변수는 Q&A 검색(기본값)과 순수 의미 유사도 정렬 사이를 전환합니다 - 전체 매개변수 표는 qwen3-rerank model page를 참조하세요.

사용 대상

사용량을 청구하는 모든 엔드포인트는 응답(및 터미널 스트리밍 청크)에 usage 필드를 반환합니다. 기본 형태:

• cost_usd - 요청 시 귀하의 계좌가 청구된 정확한 금액입니다. 권위 있는 말이야.
• prompt_tokens / completion_tokens / total_tokens - 채팅 스타일 모델용.
• 캐시 필드(cache_read_input_tokens, cache_creation_input_tokens) - 프롬프트 캐싱이 적용될 때.

계층화, 통화당 또는 변형 요금제의 상류 모델은 usage에 추가 필드를 찍어 어떤 요금이 적용되었는지 확인할 수 있습니다:

• 계층 / 변형 가격. 같은 차원에 여러 가지 요금이 있을 때 근로자들은 usage에 계층 판별기를 찍습니다. 주요 필드는 pricing_tier_label(사람이 읽을 수 있는 "Medium context" / "Pro" / "2K")입니다. 나이가 많은 작업자는 원시 치수를 직접 찍기도 합니다(resolution, quality, mode, rate_tier). 대시보드는 해당 차량의 배지를 렌더링합니다.
• 통화당 요금제. 도구 호출(검색, 가져오기, 코드 실행 등)당 청구하는 근로자들은 tool_calls_details.<tool>.invocation 또는 tool_usage.<tool> 아래에 스탬프를 매깁니다. 대시보드는 이 데이터를 도구별로 자동으로 분류 내역으로 확장합니다.
• **차원별 가격 책정. ** 한 번의 요청에서 여러 차원을 청구하는 작업자들(예: 인용 토큰 + 추론 토큰 + 심층 연구 모델의 검색 쿼리)은 각 차원을 별도의 필드(citation_tokens, reasoning_tokens, num_search_queries 등)로 표시합니다.

동일한 필드가 대시보드 사용 로그의 티어 배지와 도구별 내역을 담당하며, 각 이벤트 metadata.worker_usage 아래 GET /v1/account/usage 히스토리 엔드포인트(통화별 모델용 구조화된 tool_breakdown 배열)에서도 반환됩니다. 즉, 실시간 응답 사용량, 계정 사용 기록, 대시보드 등 어떤 정보를 읽든, 계층과 청구 내역이 정확히 일치합니다.

파일 URL

EmpirioLabs는 사용자 업로드를 호스팅하지 않습니다. 모델 엔드포인트의 입력 필드에 어떤 공개 URL이든 직접 전달하세요:

특히 오디오 전사의 경우, /v1/audio/transcriptions에서 다중 부분 직접 업로드가 URL에 없는 개인 클립에 대한 지원 경로입니다 - 해당 바이트는 영구 저장 없이 speech-to-text 작업자에게 바로 전달됩니다.

비동기 작업

GET /v1/jobs/<job-id> - 비동기 생성 또는 전사 작업의 상태/최종 결과를 폴링합니다.

작업 상태는 완료 후 1시간 동안 유지됩니다.

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
}

status가 completed 때, result 필드는 동기 종점이 반환했을 것과 동일한 형태로 전체 응답을 전달합니다.

모델

GET /v1/models - 이용 가능한 모든 모델을 나열하세요.

GET /v1/models/<model-id> - 하나의 모델에 대한 전체 스키마와 그 매개변수 테이블을 포함합니다.

GET /v1/models?format=openrouter 파트너 인제스팅 준비 완료 모델에 대해 OpenRouter 모델 목록 형태를 반환합니다. 정확한 응답 필드는 OpenRouter Model Listing을 참조하세요.

각 모델은 다음과 같은 조건을 반환합니다:

$
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 깃발

많은 채팅, 검색, 조사, 리랭킹 엔드포인트가 disable_formatting=true 플래그를 받아들입니다. 지원 모델에 설정되면 작업자는 EmpirioLabs의 서버 측 서식(인용 재작성, 참고문헌 블록, 생각 블록 마크다운 등)을 건너뛰고 상류 페이로드 형태를 그대로 반환합니다.

보장 범위는 모델별로 광고됩니다. GET /v1/models/\{id\}에서 supports_passthrough 확인해서 특정 모델이 국기를 존중하는지 확인하세요. supports_passthrough: true 광고하는 모델들은 raw=true, passthrough=true, raw_response=true 등 가명도 인정합니다. 해당 필드가 없는 모델은 정형적인 disable_formatting=true 형태만 허용하거나 패스스루를 전혀 인정하지 않습니다. 모델 카드에는 각 모델이 허용하는 별칭이 나와 있습니다.

이미지, 비디오, 오디오 생성, 전사 및 임베딩 엔드포인트는 이 플래그를 받지 않는데, 이는 해당 엔드포인트에서 비활성화할 포맷 계층이 없기 때문입니다.

생성된 미디어 유지율

생성된 이미지, 동영상, 오디오는 7일 동안 유효한 서명된 URL로 반환됩니다. 그 이후에는 URL이 작동하지 않고 자산도 사라집니다 - 재서명 엔드포인트가 없습니다. 7일 기간이 지나기 전에 보관하고 싶은 것은 모두 저장하세요.

오류

OpenAI 엔벨로프가 채팅 / 응답 / 이미지 / 동영상 / 오디오 / 검색 / 임베딩 / 재순위 설정:

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 /v1/messages 편지:

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

헤더 참조