본문으로 건너뛰기
Chat Completions

Chat Completions

POST /v1/chat/completions는 대화를 받아 모델의 다음 메시지를 OpenAI Chat Completions 형식으로 반환합니다. 모든 OpenAI SDK에서 또는 일반 HTTP로 사용할 수 있으며, 이 페이지는 필드별 레퍼런스입니다.

POST https://api.shannon-ai.com/v1/chat/completions

가장 작은 요청은 모델 id와 사용자 메시지 하나입니다.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1",
)

response = client.chat.completions.create(
    model="shannon-3",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)

print(response.choices[0].message.content)

응답은 하나의 JSON 객체입니다:

200 JSON
{
  "id": "chatcmpl-5f0c1e7a9b3d4c62a8e1f07d2b46c9a3",
  "object": "chat.completion",
  "created": 1791625200,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello, it is good to meet you.",
        "reasoning_content": "The user wants a greeting in one sentence. Keep it short and friendly."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1184,
    "completion_tokens": 46,
    "total_tokens": 1230
  }
}

헤더

요청 헤더

헤더 값 설명
Authorization Bearer YOUR_API_KEY API 키입니다. 모든 엔드포인트에서 대신 x-api-key: YOUR_API_KEY도 사용할 수 있습니다.
Content-Type application/json 필수. 다른 값은 415를 반환합니다.
x-request-id 선택 사항. 요청에 붙이는 사용자 고유의 id입니다. 응답에 그대로 반환됩니다.

응답 헤더

헤더 설명
x-request-id 오류와 스트림을 포함한 모든 응답에 포함됩니다. 보낸 값이며, 보내지 않았다면 십육진수 문자 12개입니다. 문제를 보고할 때 함께 알려 주세요.
content-type application/json, 또는 stream이 true일 때 text/event-stream.

요청 필드

필수 필드는 messages뿐입니다. 적용 대상 열에는 해당 필드가 응답을 바꾸는 모델이 나와 있습니다. 호스팅 오픈 웨이트 모델은 모델 목록의 열두 개 id이며, Shannon 3 제품군은 shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro입니다. 모델 및 가격

필드 유형 기본값 설명 적용 대상
model string shannon-1.6-lite 응답할 모델로, 모델 목록에 있는 id입니다. 모든 요청에 보내세요. 대소문자를 구분하지 않고 일치시킵니다. 공개되지 않은 id는 400 unknown model을 반환합니다. 모든 모델
messages array 필수. 가장 오래된 메시지부터 순서대로 나열한 대화입니다. 아래의 메시지를 참조하세요. 모든 모델
stream boolean false true이면 응답을 작성되는 대로 server-sent events로 보냅니다. 모든 모델
max_tokens integer 4096 응답의 상한(토큰 단위)입니다. 1에서 65,536 범위를 벗어난 값은 해당 범위로 조정됩니다. 요청이 실행되는 동안 잔액에서 따로 확보해 두는 양이기도 합니다. 아래의 출력 길이를 참조하세요. 호스팅 오픈 웨이트 모델, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
max_completion_tokens integer max_tokens와 같습니다. 둘 다 보내면 max_tokens가 사용됩니다. 호스팅 오픈 웨이트 모델, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
temperature number 샘플링 temperature. 호스팅 오픈 웨이트 모델에서 기본값은 1이며 값은 0에서 2 사이로 유지됩니다. 호스팅 오픈 웨이트 모델, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
top_p number 0.95 Nucleus 샘플링. 값은 0에서 1 사이로 유지됩니다. 호스팅 오픈 웨이트 모델
seed integer 샘플러의 시드이며 임의의 정수입니다. 없으면 시드는 모델과 대화에서 도출되므로, 같은 요청을 두 번 보내면 같은 시드가 사용됩니다. 호스팅 오픈 웨이트 모델
stop string | array 문자열 또는 문자열 배열입니다. 최대 4개가 사용됩니다. 가장 먼저 나타나는 문자열 앞에서 답변이 끝나며, 중단 텍스트 자체는 반환되지 않습니다. 호스팅 오픈 웨이트 모델
reasoning_effort string high 모델이 답하기 전에 얼마나 추론할지 정합니다: off, low, medium, high. none과 minimal은 off, default는 medium, max는 high를 뜻합니다. 그 외의 값은 400을 반환합니다. 호스팅 오픈 웨이트 모델
reasoning object 같은 설정의 객체 형태입니다: {"effort": "low"}. 둘 다 보내면 reasoning_effort가 사용됩니다. 호스팅 오픈 웨이트 모델
tools array 모델이 호출할 수 있는 함수이며, 각각 {"type": "function", "function": {"name", "description", "parameters"}} 형태입니다. 모델의 호출은 tool_calls로 돌아오며, 사용자의 코드가 이를 실행합니다. 모든 모델
tool_choice string | object auto "auto"는 모델이 결정하게 합니다. "required"는 모델이 도구를 호출하게 합니다. {"type": "function", "function": {"name": "…"}}는 모델이 해당 도구를 호출하게 합니다. 호스팅 오픈 웨이트 모델
response_format object JSON 답변에는 {"type": "json_object"}, 사용자의 스키마를 따르는 답변에는 {"type": "json_schema", "json_schema": {…}}를 사용합니다. 모든 Shannon 티어, 호스팅 오픈 웨이트 모델은 id별 목록에 따름
web_search boolean false true이면 모델이 답하기 전에 웹을 검색합니다. shannon-1.6-*, shannon-2-*, Shannon 3 제품군

n, user, stream_options, parallel_tool_calls, presence_penalty, frequency_penalty, logit_bias, logprobs, metadata, store, prompt_cache_key 같은 다른 OpenAI 필드는 기존 클라이언트 코드가 변경 없이 실행되도록 허용됩니다. 이들은 응답을 바꾸지 않습니다. choice는 항상 하나이고, 스트림은 항상 usage와 함께 끝납니다.

"max_tokens": "100"처럼 JSON 타입이 잘못된 필드는 422를 반환합니다. messages가 없는 요청도 마찬가지입니다.

도구, 구조화된 출력, 추론, 웹 검색은 각각 별도 페이지가 있습니다: 함수 호출, 구조화된 출력, 추론 effort, 내장 웹 검색.

옵션이 있는 요청

이 요청은 시스템 메시지, 샘플링 필드, 추론 effort를 설정합니다. 이 모두를 적용하는 호스팅 오픈 웨이트 모델을 사용합니다.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1",
)

response = client.chat.completions.create(
    model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    messages=[
        {"role": "system", "content": "You are a physics teacher. Answer in two sentences."},
        {"role": "user", "content": "Why is the sky blue?"},
    ],
    max_tokens=512,
    temperature=0.3,
    top_p=0.9,
    seed=7,
    stop=["\n\n"],
    reasoning_effort="low",
)

message = response.choices[0].message
print(message.reasoning_content)  # the reasoning
print(message.content)            # the answer
print(response.usage)

응답은 위와 같은 구조입니다. 호스팅 오픈 웨이트 모델에서는 usage에 두 가지 세부 정보가 추가됩니다: 캐시에서 읽은 프롬프트 토큰과 추론에 사용한 토큰.

200 JSON
{
  "usage": {
    "prompt_tokens": 31,
    "completion_tokens": 62,
    "total_tokens": 93,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 21
    }
  }
}

출력 길이

max_tokens는 두 가지 역할을 합니다. 첫째, 요청이 시작될 때 잔액에서 확보해 두는 토큰 수입니다. 응답이 완료되면 그 양은 요청이 실제로 사용한 토큰으로 대체됩니다. max_tokens가 남은 잔액보다 크면, 응답 자체는 잔액에 들어맞더라도 요청은 429 Quota exceeded를 반환합니다. 확보하는 양을 줄이려면 더 낮은 max_tokens를 보내세요.

shannon-coder-1은 이 엔드포인트에서 다르게 집계됩니다. 각 요청이 플랜의 Shannon Coder 호출 한 번이며, 따로 확보해 두는 토큰은 없습니다. 한도 및 잔액

둘째, 다음 모델에서는 응답 길이를 제한합니다:

모델 max_tokens의 작동 방식
shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 한도에 도달하면 응답이 멈춥니다. 이때 스트림은 finish_reason length로 끝납니다.
호스팅 오픈 웨이트 모델 답변 텍스트는 max_tokens에서 멈춥니다. 추론은 여기에 포함되지 않습니다. 256 미만의 값은 256으로 처리됩니다.

max_tokens나 max_completion_tokens가 없으면 값은 4,096입니다. shannon-coder-1에서는 65,536입니다.

메시지

각 메시지는 role과 content가 있는 객체입니다. content는 문자열이거나, 메시지가 텍스트 외의 내용을 담을 때는 파트 배열입니다.

역할 설명 적용 대상
system 모델에 대한 지침입니다. 가장 앞에 두세요. Shannon 티어에서는 첫 번째 system 메시지가 사용됩니다. 호스팅 오픈 웨이트 모델, shannon-1.6-*, shannon-2-*, shannon-coder-1
developer system으로 읽힙니다. 호스팅 오픈 웨이트 모델
user 사용자의 질문입니다. Shannon 티어에서는 마지막 user 메시지가 프롬프트이고 그 앞의 메시지는 기록입니다. 모든 모델
assistant 모델의 이전 응답입니다. 그 뒤에 도구 결과를 보낼 때는 해당 응답의 tool_calls를 유지하세요. 모든 모델
tool 도구 호출의 결과입니다. tool_call_id에는 호출의 id가, content에는 문자열로 된 결과가 들어갑니다. 모든 모델

Shannon 3 제품군 id에서는 반드시 지켜야 하는 지침을 user 메시지에 넣으세요.

Shannon 티어에서 사용자 텍스트도 tools도 없는 요청은 400 No user message provided를 반환합니다.

콘텐츠 파트

파트 설명 사용 가능 대상
{"type": "text", "text": "…"} 일반 텍스트. 모든 모델
{"type": "image_url", "image_url": {"url": "…"}} base64 콘텐츠가 있는 data: URL 또는 http(s) URL로 전달하는 이미지. Shannon 3 제품군, shannon-1.6-lite, shannon-1.6-pro, 그리고 이미지 입력을 지원하는 호스팅 오픈 웨이트 모델
{"type": "file", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} 문서 파일(PDF, Word, PowerPoint, Excel)을 base64 또는 URL 형태로 전달합니다. Shannon 3 제품군

크기, 제한, 전체 형식 목록은 별도 페이지에 있습니다. 이미지와 파일

응답 객체

필드 유형 설명
id string chatcmpl- 뒤에 십육진수 문자 32개가 붙습니다.
object string 항상 chat.completion입니다.
created integer 응답 시각이며 Unix 초 단위입니다.
model string 응답한 모델의 정식 id입니다. 보낸 id와 철자가 다를 수 있습니다.
choices array index가 0인 choice가 항상 정확히 하나 있습니다.
choices[0].message.role string 항상 assistant입니다.
choices[0].message.content string | null 답변 텍스트입니다. tool_calls가 있으면 Shannon 티어에서는 null이며, 호스팅 오픈 웨이트 모델은 호출과 함께 텍스트를 보낼 수 있습니다.
choices[0].message.reasoning_content string | null 모델이 답변 전에 작성한 추론이며, 없으면 null입니다.
choices[0].message.tool_calls array 모델이 도구를 호출할 때만 있습니다. 각 항목에는 id, type function, 그리고 name과 JSON 문자열인 arguments가 있는 function이 들어 있습니다.
choices[0].message.annotations array web_search: true로 보낸 요청에서 검색이 결과를 찾았을 때만 있습니다. content의 표시가 가리키는 출처마다 url_citation이 하나씩 있으며 url, title, start_index, end_index를 포함합니다(표시의 위치를 문자 수로 센 값이며 끝 값은 포함되지 않습니다).
choices[0].finish_reason string 응답이 끝난 이유입니다. 종료 이유를 참조하세요.
usage object 요청의 토큰입니다. 사용량을 참조하세요.
sources array web_search: true로 보낸 요청에서 검색이 결과를 찾았을 때만 있습니다. 모델에 전달된 결과이며 각각 index, title, url을 포함합니다. 답변의 [1]은 index가 1인 항목입니다.

종료 이유

finish_reason 설명
stop 모델이 답변을 마쳤거나, stop 문자열이 나타났습니다.
tool_calls 모델이 하나 이상의 도구를 호출합니다. 이를 실행하고 결과를 tool 메시지로 보내세요.
length 출력 한도에서 응답이 잘렸습니다. shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1, Shannon 3 제품군의 스트림에서 보고됩니다.

스트리밍이 아닌 응답은 stop 또는 tool_calls를 보고합니다.

사용량

필드 유형 설명 사용 가능 대상
usage.prompt_tokens integer 입력 토큰. 모든 모델
usage.completion_tokens integer 출력 토큰: 추론, 답변, 도구 호출을 합한 것입니다. 모든 모델
usage.total_tokens integer prompt_tokens와 completion_tokens의 합입니다. 모든 모델
usage.prompt_tokens_details.cached_tokens integer prompt_tokens 중 프롬프트 캐시에서 읽은 부분입니다. 호스팅 오픈 웨이트 모델
usage.completion_tokens_details.reasoning_tokens integer completion_tokens 중 추론에 사용한 부분입니다. 호스팅 오픈 웨이트 모델

호스팅 오픈 웨이트 모델에서 prompt_tokens는 메시지와 도구 정의를 모델 자체의 토크나이저로 센 값에 이미지의 토큰을 더한 것입니다. 토큰 계산 엔드포인트는 보내기 전에 같은 수를 반환합니다. 토큰 수 계산

Shannon 티어에서 prompt_tokens는 모델이 응답을 작성하기 위해 읽은 모든 것을 센 값이므로, 메시지 텍스트만의 값보다 큽니다.

스트리밍

stream을 true로 설정하면 응답이 chat.completion.chunk 이벤트로 도착하고 data: [DONE]으로 끝납니다. 그 직전의 마지막 청크에 finish_reason과 usage가 담기며, stream_options는 필요 없습니다. 청크 구조, keep-alive 줄, 스트림 안의 오류는 별도 페이지에서 설명합니다. 스트리밍

오류

오류는 error 멤버가 있는 JSON 객체입니다. 확인은 API 키, 요청 본문, 모델 id, 잔액 순서로 진행됩니다. 표에는 이 엔드포인트가 가장 자주 반환하는 오류가 나와 있습니다. 재시도해야 하는 경우를 포함한 전체 목록은 별도 페이지에 있습니다. 오류 처리

400 JSON
{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}
상태 유형 메시지 시점
401 authentication_error Missing authentication
Invalid API key
API 키를 보내지 않았거나, 키를 알 수 없거나 폐기되었습니다.
400 invalid_request_error unknown model: <id> model이 공개된 id가 아닙니다.
400 invalid_request_error No user message provided Shannon 티어: 요청에 사용자 텍스트도 tools도 없습니다.
400 invalid_request_error <id> does not accept image input 이미지 입력을 지원하지 않는 호스팅 오픈 웨이트 모델에 이미지 파트를 보냈습니다.
400 invalid_request_error <id> does not accept response_format 구조화된 출력을 지원하지 않는 호스팅 오픈 웨이트 모델에 response_format을 보냈습니다.
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high reasoning_effort에 목록에 없는 값이 들어 있습니다.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … messages가 없거나, 필드의 JSON 타입이 잘못되었습니다.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan max_tokens가 남은 잔액보다 큽니다.
429 rate_limit_error Too many requests. Retry in <n>s. 플러드 보호: 계정에서 분당 120건을 초과하는 요청이 있었습니다.
500 server_error The model backend failed to answer. Please retry. 모델이 응답을 생성하지 못했습니다. 요청을 다시 보내세요.
502 api_error The model backend failed to answer. Please retry. Shannon 3 제품군과 호스팅 오픈 웨이트 모델에서도 동일합니다.