API 문서
상세한 연동 가이드와 API 참고 자료로 SiCore TokenWorks AI API 서비스를 빠르게 통합하실 수 있습니다
1빠른 시작
SiCore TokenWorks API를 사용하려면 세 가지 간단한 단계만 거치면 됩니다:
- SiCore TokenWorks 계정을 등록하고 콘솔에 로그인하세요
- 콘솔에서 API Key를 생성하세요
- API Key를 사용하여 인터페이스를 호출하세요
Tip: 신규 사용자는 가입 후 무료 체험 할당량을 받게 되며, 신용카드 등록 없이 바로 사용할 수 있습니다.
2인터페이스 주소
API 기본 주소는 다음과 같으며, 모든 요청은 HTTPS 프로토콜을 사용합니다:
text
https://www.token8341.com/v1채팅 완성 인터페이스:
text
POST https://www.token8341.com/v1/chat/completionsNote: 이 인터페이스는 OpenAI의 Chat Completions 인터페이스 형식과 완전히 호환되므로, OpenAI SDK를 직접 사용하여 호출할 수 있습니다.
3인증 방식
SiCore TokenWorks는 Bearer Token을 사용하여 API 인증을 수행합니다. 요청 헤더에 API Key를 포함하세요:
text
Authorization: Bearer sk-your-api-key-here콘솔의 'API Keys' 페이지에서 키를 생성하고 관리할 수 있습니다. API Key를 안전하게 보관하고, 공개 코드 저장소나 클라이언트 코드에 노출하지 마세요.
4지원 모델 목록
| 모델 ID | 모델 이름 | 공급업체 |
|---|---|---|
| gpt-4o | GPT-4o | OpenAI |
| gpt-4o-mini | GPT-4o Mini | OpenAI |
| claude-3-5-sonnet | Claude 3.5 Sonnet | Anthropic |
| claude-4-sonnet | Claude 4 Sonnet | Anthropic |
| gemini-2-0-pro | Gemini 2.0 Pro | |
| deepseek-v4-pro | DeepSeek-V4-Pro | DeepSeek |
| qwen-max | Qwen-Max | Alibaba Cloud |
더 많은 모델이 지속적으로 연동되고 있습니다. 업데이트 공지를 확인해 주세요.
5예제 코드
curl
bash
curl https://www.token8341.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-your-api-key-here" \
-d '{
"model": "gpt-4o",
"messages": [
{"role": "user", "content": "Hello!"}
]
}'Python (openai SDK)
python
from openai import OpenAI
client = OpenAI(
base_url="https://www.token8341.com/v1",
api_key="sk-your-api-key-here"
)
response = client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "user", "content": "Hello!"}
]
)
print(response.choices[0].message.content)Node.js (openai SDK)
javascript
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://www.token8341.com/v1",
apiKey: "sk-your-api-key-here",
});
const response = await client.chat.completions.create({
model: "gpt-4o",
messages: [
{ role: "user", content: "Hello!" },
],
});
console.log(response.choices[0].message.content);6오류 코드 설명
API 요청 실패 시 해당 HTTP 상태 코드와 오류 정보가 반환되며, 형식은 다음과 같습니다:
json
{
"error": {
"message": "Insufficient balance",
"type": "insufficient_balance",
"code": 402
}
}| 상태 코드 | 이름 | 설명 |
|---|---|---|
| 400 | Bad Request | 请求参数错误，请检查请求体格式 |
| 401 | Unauthorized | API Key 无效或缺失，请检查 Authorization 请求头 |
| 402 | Insufficient Balance | 账户余额不足，请充值后重试 |
| 404 | Not Found | 请求的模型或接口不存在 |
| 429 | Rate Limit | 请求频率过高，请稍后重试 |
| 500 | Internal Server Error | 服务内部错误，请联系技术支持 |
| 503 | Service Unavailable | 模型服务暂时不可用，请稍后重试 |
연동 자주 묻는 질문
API Key, 모델 전환 및 연동 언어에 관한 자주 묻는 질문
하나의 API Key로 모든 모델을 호출할 수 있나요?
가능합니다. 이것이 SiCore TokenWorks의 핵심 특징입니다. 개발자는 한 번만 연동하면 플랫폼의 모든 모델을 호출할 수 있으며, 각 제공업체마다 별도로 계정을 신청하고 Key를 관리할 필요가 없습니다.
모델을 전환하려면 코드를 수정해야 하나요?
로직 코드를 수정할 필요 없이 모델 ID 파라미터 하나만 변경하면 국산과 해외 모델 간에 전환할 수 있습니다.
어떤 프로그래밍 언어를 지원하나요?
cURL, Python, Node.js 등 주요 연동 예시를 제공하며, HTTP 요청을 지원하는 모든 언어와 OpenAI 공식 SDK와 호환됩니다.
API는 어떻게 인증하나요?
인증 방식은 Bearer Token이며, 요청 헤더에 API Key를 포함하면 됩니다. 인터페이스는 OpenAI의 Chat Completions 형식과 완전히 호환되므로 OpenAI 공식 SDK로 바로 호출할 수 있고 별도의 추가适配가 필요 없습니다.
사용 가능한 SDK나 코드 예제가 있나요?
있습니다. 플랫폼은 cURL, Python, Node.js 등 주요 연동 예제를 제공하므로 개발자는 자신의 언어에 맞게 선택해 빠르게 통합할 수 있습니다.
모델이 계속 추가되나요? 새 모델은 코드를 수정해야 하나요?
그렇습니다. 플랫폼은 새로운 국산 및 국제 주요 모델을 지속적으로 연동하며, 연동 방식과 과금 체계는 동일하게 유지되므로 새 모델이 출시되어도 코드 수정 없이 바로 선택해 사용할 수 있습니다.
대규모 모델 API의 캐시 메커니즘은 어떻게 사용하나요? 어떤 상황에서 적중되나요?
플랫폼은 동일한 prompt를 사용자 간에 공유 캐시로 운영하며, 적중 시 가격이 90% 이상 추가 인하됩니다. 캐시 적중 가격은 최저 ¥0.010 / 백만 Token이며, 적중된 부분은 캐시 가격으로 과금됩니다. 여러 사용자가 동일한 접두사 prompt를 반복 사용하는 시나리오에 적합합니다. 예를 들어 고정된 시스템 프롬프트, 공용 지식 접두사 등이 있으며, 변하지 않는 부분을 앞에 배치할수록 적중률이 높아집니다.
API 호출이 실패하거나 타임아웃될 때 자동 재시도와 폴백은 어떻게 하나요?
일반적인 방법은 타임아웃 및 재시도 가능한 오류에 대해 지수 백오프 재시도를 적용하고 최대 재시도 횟수를 설정하는 것입니다. 그래도 실패하면 대체 모델로 폴백합니다. 플랫폼에서 모델을 전환하려면 모델 ID만 수정하면 되고 코드 변경은 전혀 필요 없으며, 폴백 대상을 다른 모델 ID로 작성하면 됩니다. 플랫폼 측에는 다중 노드 이중화와 리전 간 지능형 라우팅이 있어 단일 노드 이상 시 자동으로 전환됩니다.
서로 다른 모델의 효과와 비용을 어떻게 비교하나요?
하나의 API Key로 모든 모델을 호출할 수 있으며, 모델 전환 시 모델 ID만 변경하면 되고 코드 변경은 전혀 필요 없으므로 횡적 비교 시 각 모델을 개별적으로 연동할 필요가 없습니다. 동일한 업무 샘플 세트로 각각 호출하여 출력 품질과 사용량을 기록한 뒤, 공식 웹사이트의 「전체 모델 가격 비교표」와 함께 공식 가격과 본 사이트 가격을 항목별로 비교하는 것을 권장합니다.
서버 측 API Key는 어떻게 안전하게 보관하나요?
API Key는 서버 측에만 저장하고, 요청 헤더를 통해 Bearer Token 방식으로 전달하며, 프런트엔드나 클라이언트 코드에 작성하지 않는 것을 권장합니다. 플랫폼의 요청 및 응답 데이터는 전 구간 HTTPS로 암호화 전송되며, 엔터프라이즈급 권한 관리와 감사 로그를 제공하여 호출 기록을 추적할 수 있습니다.
고동시성 시나리오에서 호출 안정성과 저지연을 어떻게 보장하나요?
플랫폼은 내몽골 허린거얼, 신장 하미, 닝샤 중웨이 등의 컴퓨팅 센터를 기반으로 자체 개발한 스케줄링 알고리즘을 통해 리전 간 지능형 라우팅과 동적 로드 밸런싱을 수행하며, 단일 노드 이상 시 자동으로 전환됩니다. 핵심 도시 사용자는 밀리초 수준의 지연을 얻을 수 있고, 서비스 가용성은 99.9%를 보장합니다. 클라이언트 측에서도 백오프 재시도와 다중 모델 폴백을 함께 적용하는 것을 권장합니다.
호출량, 비용, 이상을 어떻게 모니터링하나요?
플랫폼은 통합 계정과 단일 과금 체계를 제공하며, 사용량이 투명하고 잔액이 실시간으로 반영되며 소비 내역을 언제든지 확인할 수 있습니다. 또한 API 호출의 감사 로그 기능을 제공하여 호출 기록을 추적할 수 있습니다. 기업 사용자가 더 엄격한 컴플라이언스 요구사항(권한 관리, 감사 로그 등)이 필요한 경우 고객센터에 문의하여 비즈니스 상담을 진행할 수 있습니다.