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) import OpenAI from "openai";
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com/v1",
});
const response = await client.chat.completions.create({
model: "shannon-3",
messages: [{ role: "user", content: "Say hello in one sentence." }],
});
console.log(response.choices[0].message.content); curl https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "shannon-3",
"messages": [{"role": "user", "content": "Say hello in one sentence."}]
}' 응답은 하나의 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) import OpenAI from "openai";
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com/v1",
});
const response = await 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",
});
const message = response.choices[0].message;
console.log(message.reasoning_content); // the reasoning
console.log(message.content); // the answer
console.log(response.usage); curl https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}' 응답은 위와 같은 구조입니다. 호스팅 오픈 웨이트 모델에서는 usage에 두 가지 세부 정보가 추가됩니다: 캐시에서 읽은 프롬프트 토큰과 추론에 사용한 토큰.
{
"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, 잔액 순서로 진행됩니다. 표에는 이 엔드포인트가 가장 자주 반환하는 오류가 나와 있습니다. 재시도해야 하는 경우를 포함한 전체 목록은 별도 페이지에 있습니다. 오류 처리
{
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} | 상태 | 유형 | 메시지 | 시점 |
|---|---|---|---|
401 | authentication_error | Missing authenticationInvalid 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 제품군과 호스팅 오픈 웨이트 모델에서도 동일합니다. |