API 개요 - OpenModex

기본 URL

환경	URL
프로덕션	`https://api.openmodex.com/v1`
샌드박스	`https://api-sandbox.openmodex.com/v1`

개발 및 테스트에는 샌드박스 환경을 사용하세요. 프로덕션과 동일하게 동작하지만 요금이 부과되지 않습니다. 모든 API 엔드포인트는 OpenAI 호환입니다. 이미 OpenAI API를 사용하고 있다면 기본 URL과 API 키만 변경하여 전환할 수 있습니다.

인증

Authorization 헤더에 API 키를 포함하세요:

Authorization: Bearer omx_sk_YOUR_API_KEY

엔드포인트

메서드	엔드포인트	설명
`POST`	`/chat/completions`	채팅 완성 생성
`POST`	`/completions`	텍스트 완성 생성 (레거시)
`POST`	`/embeddings`	임베딩 생성
`GET`	`/models`	사용 가능한 모델 목록
`GET`	`/models/:id`	모델 조회
`GET`	`/models/compare`	모델 비교

요청 형식

모든 POST 요청은 Content-Type: application/json으로 JSON 본문을 받습니다.

응답 형식

모든 응답은 JSON으로 반환됩니다. 성공 응답은 데이터를 직접 포함합니다. 오류 응답은 다음 형식을 따릅니다:

{
  "error": {
    "message": "Human-readable error message",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

HTTP 상태 코드

코드	설명
`200`	성공
`400`	잘못된 요청 — 파라미터를 확인하세요
`401`	인증 실패 — API 키가 유효하지 않거나 누락됨
`403`	금지됨 — 권한이 부족함
`404`	찾을 수 없음 — 유효하지 않은 엔드포인트 또는 모델
`429`	요청 제한 — 속도를 줄이거나 플랜을 업그레이드하세요
`500`	서버 오류 — 백오프와 함께 재시도하세요
`502`	잘못된 게이트웨이 — 업스트림 제공업체 오류
`503`	서비스 불가 — 일시적 장애

OpenModex 응답 메타데이터

모든 응답에는 라우팅 및 성능 메타데이터를 포함하는 선택적 openmodex 필드가 포함됩니다:

{
  "id": "chatcmpl-abc123",
  "choices": [...],
  "usage": {...},
  "openmodex": {
    "request_id": "req_abc123",
    "model_used": "gpt-4o-2024-08-06",
    "provider": "openai",
    "cache_hit": false,
    "routing_strategy": "cost_optimized",
    "fallback_used": false,
    "latency_ms": 1250
  }
}

멱등성

POST 요청의 경우 Idempotency-Key 헤더를 전달하여 동일한 요청이 두 번 처리되지 않도록 할 수 있습니다:

curl https://api.openmodex.com/v1/chat/completions \
  -H "Authorization: Bearer omx_sk_..." \
  -H "Idempotency-Key: my-unique-key-123" \
  -H "Content-Type: application/json" \
  -d '...'

멱등성 키는 24시간 동안 유효합니다.

​기본 URL

​인증

​엔드포인트

​요청 형식

​응답 형식

​HTTP 상태 코드

​OpenModex 응답 메타데이터

​멱등성