/v1이 포함되거나 누락된 경우, model 필드에 등록된 배포 이름이 올바르지 않은 경우, 해당 배포용 커넥터가 온라인 상태가 아닌 경우, 혹은 모델 자체이 클라이언트가 요청한 기능(예: 툴 호출)을 지원하지 않는 경우입니다. 더 심각한 문제가 있을 것이라 단정하기 전에 이 페이지의 내용을 처음부터 차근차근 살펴보시기 바랍니다.
내 클라이언트는 어떤 기본 URL을 사용하나요?
클라이언트가 사용하는 API 형태에 따라 기본 URL을 선택하시면 됩니다. 클라이언트가 나머지 경로(/chat/completions, /responses, 또는 /messages)를 자동으로 추가하므로 사용자는 루트 URL만 지정하면 됩니다.
curl에서는 작동하지만 제 에이전트에서는 실패합니다
일반적인curl 요청은 성공하는데 클라이언트, 프레임워크, 혹은 에이전트 내부에서 동일한 호출이 실패한다면 다음 순서대로 점검해보세요:
기본 URL에는 전체 요청 경로가 포함되어야 합니다
기본 URL에는 전체 요청 경로가 포함되어야 합니다
일부 클라이언트는 루트 주소인
https://api.tokios.com/v1만 입력하고 /chat/completions를 스스로 추가하려 합니다. 반면 다른 클라이언트는 전체 경로를 그대로 입력하길 원하죠. 만약 /chat/completions, /responses, 혹은 /messages로 끝나는 URL을 복사하여 자체 경로가 추가되는 필드에 입력한다면 경로가 중복되거나 형식이 어긋날 수 있습니다. 그러니 위 표에 나온 루트 주소만 기본 URL로 설정하고 나머지는 클라이언트가 처리하도록 하세요.클라이언트는 툴 호출 기능을 요구하는데 모델은 이를 지원하지 않습니다
클라이언트는 툴 호출 기능을 요구하는데 모델은 이를 지원하지 않습니다
에이전트 프레임워크와 코딩 어시스턴트들은 간단한 프롬프트일 때도 매번
tools 배열을 전송하는 경우가 많습니다. Tokios는 tools 구조를 모델에 그대로 전달하지만, 모델 자체가 함수 호출 기능을 지원해야만 합니다. 그렇지 않으면 요청이 실패하거나 툴 정보가 무시될 수 있으니 클라이언트를 추가로 디버깅하기 전에 해당 모델이 툴 호출을 지원하는지 먼저 확인하세요.모델 이름과 배포 이름은 서로 다릅니다
모델 이름과 배포 이름은 서로 다릅니다
The
model field must be the public deployment name you registered in the console’s Models tab (for example, gemma-tunnel) — not the upstream model id your backend serves (for example, gemma:7b). A curl request with the correct deployment name will work while a client still configured with the backend’s local id returns a 404.각 오류 코드가 의미하는 바
터널 상태를 별도로 확인하세요
클라이언트 측 설정 문제를 계속 진단하기 전에 문제의 원인이 클라이언트 자체인지 아니면 모델/커넥터에 있는지를 파악해야 합니다. 콘솔의 Playground 창을 열어 동일한 배포 대상으로 테스트 프롬프트를 전송해 보세요. 이 작업은 로그인된 세션을 기반으로 이루어지므로 API 키가 필요하지 않습니다. 플레이그라운드가 정상 작동한다면 터널과 모델에 문제가 없으며 클라이언트의 기본 URL, 모델 값 또는 요청 형식에 문제가 있는 것입니다. 반면 플레이그라운드 역시 실패한다면 문제는 클라이언트 이전 단계에 있으므로 커넥터와 배포 설정을 점검하시기 바랍니다.다음 절차
호환 가능한 클라이언트들
지원되는 각 클라이언트별 기본 URL 및 API 키 설정 정보가 한 표에 정리되어 있습니다.
Claude Code
Anthropic 스타일 설정을 위한 환경 변수와 모델 플래그 정보입니다.
SDK 및 프레임워크
LangChain, LlamaIndex, Vercel AI SDK, Pydantic AI의 설정 방법에 관한 내용입니다.
API 엔드포인트
모든 인터페이스에 대한 요청 및 응답 스키마가 상세히 기술되어 있습니다.