개요

엔드포인트

모든 엔드포인트는 하나의 기본 URL 아래에 있으며 HTTPS로 제공됩니다.

https://api.shannon-ai.com

텍스트를 생성하는 세 엔드포인트는 같은 모델에 연결됩니다. 코드가 이미 사용하는 형식의 엔드포인트를 고르세요.

요청 기본

• 모든 POST의 본문은 JSON 객체 하나이며 최대 32 MiB입니다.
• API가 모르는 필드는 오류를 일으키지 않으며 아무 효과도 없습니다. 다른 제공업체용으로 작성한 요청이 추가 필드 때문에 실패하지는 않습니다.
• 알려진 필드의 JSON 타입이 틀렸거나 필수 필드가 없으면 422로 응답합니다. 유효한 JSON이 아닌 본문은 400으로 응답합니다.
• model은 Models & pricing에 있는 id 중 하나입니다. 대소문자는 구분하지 않습니다.

응답은 JSON이거나, 요청에서 stream을 true로 설정한 경우 server-sent events 스트림입니다. 각 엔드포인트는 고유한 형식으로 응답합니다. 모든 응답에는 x-request-id 헤더가 있습니다.

요청이 거치는 검사

요청은 모델이 실행되기 전에 정해진 순서로 검사됩니다. 처음 실패한 검사가 응답하므로 401만으로는 본문에 대해 아직 아무것도 알 수 없습니다.

오류 형태

오류는 type과 message를 담은 error가 있는 JSON 객체입니다. /v1/messages는 Anthropic SDK가 기대하는 방식으로 감싸고, 다른 모든 경로는 OpenAI 형태를 사용합니다.

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

• type과 message를 읽으세요. code와 param은 일부 오류에만 있으므로 선택 사항으로 취급하세요. param은 항상 null입니다.
• 스트림이 시작된 뒤에는 상태가 이미 200입니다. 이후의 실패는 스트림 안의 오류 프레임으로 전달됩니다.
• 모든 오류 응답에는 x-request-id 헤더가 포함됩니다.

오류 처리

결제와 잔액

• 계정당 잔액은 하나이며 채팅과 API가 함께 사용합니다. 오늘의 플랜 할당량을 먼저 쓰고, 그다음에 구매한 크레딧을 씁니다. API에는 별도의 할당량이 없습니다.
• 요청은 출력 예산(max_tokens, 기본값 4,096)을 확보한 뒤, 실제로 사용한 토큰에 대해 모델의 가격으로 청구됩니다.
• 모든 응답은 usage에 토큰 수를 보고합니다. Keys & usage 페이지에서 잔액과 요청별 비용을 볼 수 있습니다.
• 모든 요청은 동등하게 처리됩니다. 요청 속도에 대한 유일한 제한은 플러드 보호로, 계정당 분당 120개 요청입니다. 병렬로 보낸 요청은 대기열에서 기다립니다.

한도 및 잔액 모델 및 가격 Keys & usage

모델에 따라 달라지는 필드

모든 모델이 같은 요청을 받습니다. 일부 필드는 특정 모델에서만 적용되며, 표에 해당 모델이 나와 있습니다. 엔드포인트 페이지에는 모든 필드가 나열되어 있습니다.

Chat Completions

OpenAI SDK에서 넘어올 때

• 기본 URL을 https://api.shannon-ai.com/v1로, 키를 Shannon 키로 설정하세요. 그러면 Chat Completions와 Responses 호출이 SDK에서 그대로 동작합니다.
• model은 Shannon id여야 합니다. gpt-4o 같은 다른 제공업체의 모델 이름은 400과 unknown model로 응답합니다.
• 추론은 별도의 필드로 제공됩니다: 메시지와 스트림 델타 모두에서 content 옆에 reasoning_content가 있습니다.
• 스트림은 항상 마지막 청크에 finish_reason과 함께 usage를 담아 보냅니다.
• 스트림에서 도구 호출은 완전한 arguments 문자열을 담은 하나의 청크로 도착합니다.
• 응답에는 choice가 하나 있습니다.
• /v1/embeddings처럼 위 표에 없는 OpenAI API 경로는 404로 응답합니다.

Anthropic SDK에서 넘어올 때

• 기본 URL을 /v1 없이 https://api.shannon-ai.com로 설정하고 키는 Shannon 키로 설정하세요. SDK가 이를 x-api-key로 보냅니다.
• model은 Shannon id여야 합니다.
• 이 API에서 max_tokens는 선택 사항입니다. 기본값은 4,096입니다.
• 응답에는 type이 thinking, text, tool_use인 콘텐츠 블록이 들어 있습니다. 첫 블록이 항상 텍스트는 아니므로 type으로 블록을 골라야 합니다.
• stop_reason은 end_turn 또는 tool_use입니다. Shannon 모델의 스트림은 max_tokens로 끝날 수도 있습니다.
• anthropic-version과 anthropic-beta는 허용되므로 SDK가 변경 없이 동작합니다. 요청에 꼭 필요하지는 않습니다.
• /v1/messages의 오류는 Anthropic 형태를 따릅니다: {"type": "error", "error": {…}}.

이 형식을 사용하는 코딩 도구도 같은 방식으로 설정합니다: 기본 URL, 키, 그리고 모델로 Shannon id. CLI 코딩 도구