API 개요

OfoxAI는 세 가지 프로토콜을 통한 API 접속 방식을 제공하며, 각 제공사의 공식 SDK와 완벽하게 호환됩니다. OpenAI의 최신 Responses API도 지원합니다.

프로토콜 권장 사항: OpenAI 프로토콜에서는 네이티브 Prompt Caching 지원이 더 우수한 Responses API를 권장합니다. Claude 모델을 호출할 때는 전체 기능과 네이티브 캐싱 이점을 활용할 수 있는 Anthropic 네이티브 프로토콜을 권장합니다.

Base URL

프로토콜	Base URL	설명
OpenAI 호환	`https://api.ofox.ai/v1`	OpenAI SDK 호환, Chat Completions 및 Responses API 지원
Anthropic 네이티브	`https://api.ofox.ai/anthropic`	Anthropic SDK 호환, 네이티브 Claude 경험
Gemini 네이티브	`https://api.ofox.ai/gemini`	Google GenAI SDK 호환

인증

모든 프로토콜은 동일한 OfoxAI API Key를 사용하지만, Header 형식은 프로토콜에 따라 다릅니다:

프로토콜	Header	형식
OpenAI	`Authorization`	`Bearer sk-xxx`
Anthropic	`x-api-key`	`sk-xxx`
Gemini	`x-goog-api-key`	`sk-xxx`

자세한 내용은 API Key 발급과 사용을 참조하십시오.

사용 가능한 엔드포인트

OpenAI 호환 프로토콜

엔드포인트	메서드	설명
`/v1/chat/completions`	POST	대화 완성 생성
`/v1/responses`	POST	모델 응답 생성(Responses API, 권장)
`/v1/embeddings`	POST	텍스트 임베딩 생성
`/v1/images/generations`	POST	이미지 생성
`/v1/models`	GET	사용 가능한 모든 모델 목록
`/v1/models/{provider}`	GET	공급자별 모델 필터링
`/v1/models/{provider}/{model_id}`	GET	모델 상세 정보 조회
`/v1/models/count`	GET	모델 수 통계 조회

Anthropic 네이티브 프로토콜

엔드포인트	메서드	설명
`/anthropic/v1/messages`	POST	Messages 생성(권장)
`/anthropic/v1/models`	GET	사용 가능한 모든 모델 목록
`/anthropic/v1/models/{provider}`	GET	공급자별 모델 필터링
`/anthropic/v1/models/{provider}/{model_id}`	GET	모델 상세 정보 조회
`/anthropic/v1/models/count`	GET	모델 수 통계 조회

Gemini 네이티브 프로토콜

엔드포인트	메서드	설명
`/gemini/v1beta/models/{model}:generateContent`	POST	콘텐츠 생성
`/gemini/v1beta/models/{model}:streamGenerateContent`	POST	스트리밍 콘텐츠 생성
`/gemini/v1beta/models`	GET	사용 가능한 모든 모델 목록
`/gemini/v1beta/models/{provider}`	GET	공급자별 모델 필터링
`/gemini/v1beta/models/{provider}/{model_id}`	GET	모델 상세 정보 조회
`/gemini/v1beta/models/count`	GET	모델 수 통계 조회

유형화된 판단 (Decisions)

콘텐츠에 대해 예/아니요, 단일 선택, 점수 판단을 수행하고 확률이 포함된 구조화된 답변을 반환합니다. Decisions API 문서를 참조하세요.

엔드포인트	메서드	설명
`/v1/decisions`	POST	통합 형식, OpenAI SDK로도 호출 가능
`/openai/v1/decisions`	POST	위와 동일, base URL이 `/openai/v1`인 OpenAI SDK용
`/typesafe/v1/systemone`	POST	TypeSafe 공식 형식, TypeSafe SDK 호환

Video Generation (OpenRouter 호환)

통합 비동기 비디오 생성 API입니다. Video API 문서를 참조하세요.

엔드포인트	메서드	설명
`/v1/videos`	POST	비디오 생성 작업 생성
`/v1/videos/{id}`	GET	작업 상태와 결과 조회
`/v1/videos/{id}`	DELETE	작업 취소

OfoxAI OpenAPI (계정)

프로토콜과 무관한 플랫폼 엔드포인트로, OfoxAI API Key로 인증합니다.

엔드포인트	메서드	설명
`/v1/user/balance`	GET	잔액 조회, cc-switch 호환

속도 제한

OfoxAI는 종량제로 운영되며, 모든 사용자에게 동일한 속도 제한 정책이 적용됩니다:

제한 항목	할당량
RPM (요청/분)	100 (팀 단위 집계)
TPM (토큰/분)	무제한

RPM은 팀 단위로 집계되며, 동일 팀의 여러 API Key가 같은 할당량을 공유합니다. 더 높은 RPM 할당량이 필요한 경우, hi@ofox.ai에 문의하여 조정을 요청하십시오. 자세한 내용은 Rate Limits를 참조하십시오.

속도 제한에 도달하면 API는 429 Too Many Requests를 반환하며, 응답 Header에 다음이 포함됩니다:


x-ratelimit-limit-requests: 100
x-ratelimit-remaining-requests: 0
x-ratelimit-reset-requests: 1s

에러 코드

모든 프로토콜은 통일된 HTTP 상태 코드를 반환합니다:

상태 코드	설명	일반적인 원인
`200`	성공	—
`400`	잘못된 요청	파라미터 형식 오류, 필수 필드 누락
`401`	인증 실패	API Key가 유효하지 않거나 만료됨
`403`	권한 부족	해당 모델에 대한 접근 권한 없음
`404`	리소스 없음	모델 ID 오류
`429`	속도 제한	속도 제한 초과
`500`	서버 오류	내부 오류, 재시도 필요
`502`	업스트림 오류	모델 공급자 서비스 이상
`503`	서비스 불가	서비스 점검 중

에러 응답 형식


{
  "error": {
    "code": "invalid_api_key",
    "message": "제공된 API Key가 유효하지 않습니다. 확인 후 다시 시도해 주세요.",
    "type": "authentication_error"
  }
}

OfoxAI 확장 파라미터

OfoxAI는 표준 프로토콜에 더하여 고급 라우팅 및 장애 복구를 위한 확장 파라미터를 제공합니다:


{
  "model": "openai/gpt-6.1-sol",
  "messages": [...],
  "extra_body": {
    "provider": {
      "fallback": ["anthropic/claude-sonnet-5.5", "google/gemini-3.8-flash"]
    }
  }
}

provider는 요청 본문의 extra_body 안에 넣어야 하며, 최상위에 두면 400이 반환됩니다. 자세한 내용은 공급자 라우팅과 장애 복구를 참조하십시오.