메인 콘텐츠로 건너뛰기
구조화된 출력 및 도구 호출은 경로별 계약입니다. TokenLab은 여러 공용 API 형식을 전달하므로, 가장 안전한 프로덕션 패턴은 각 제공자 고유의 도구 형상을 해당 경로에 유지하고, 귀하의 애플리케이션에서 모델 출력을 검증하는 것입니다.

​
경로 선택

필요경로이 형상 사용
휴대 가능한 JSON 객체 응답/v1/chat/completionsresponse_format: {"type": "json_object"}
OpenAI 호환 함수 호출/v1/chat/completionstools: [{ "type": "function", "function": ... }]
OpenAI 응답 도구/v1/responses응답 tools, tool_choice, 및 text 필드
Claude 고유 도구 사용 또는 사고/v1/messagesAnthropic Messages 도구 스키마
Gemini 함수 선언 또는 내장 도구/v1beta/models/:model:generateContentGemini 고유 tools 및 콘텐츠 부분
제공자 고유의 내장 도구를 다른 경로를 통해 전송하고 TokenLab이 이를 조용히 변환할 것이라고 기대하지 마십시오.

​
JSON 모드

휴대 가능한 구조화된 응답을 위해 Chat Completions JSON 모드로 시작하세요: 
{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "도시와 날씨를 포함한 JSON 객체를 반환하세요."
    }
  ],
  "response_format": { "type": "json_object" }
}
Chat Completions에 대한 안정적인 공유 검증은 text 및 json_object를 수용합니다. json_schema, strict, 및 제공자 특정 스키마 강제 적용은 일부 업스트림 경로 또는 변환 경로에 존재할 수 있지만, 이는 모든 TokenLab 경로 및 모델에 걸쳐 보편적인 약속이 아닙니다. 의존하기 전에 선택한 모델에 대해 이를 검증하십시오. 항상 서버에서 반환된 JSON을 파싱하고 검증하십시오. JSON 모드는 형상을 개선하지만, 애플리케이션 수준의 스키마 검증을 대체하지는 않습니다.

​
도구 호출 루프

TokenLab은 귀하의 함수를 실행하지 않습니다. 귀하의 애플리케이션이 루프를 소유합니다:
  1. 메시지와 도구 정의를 전송합니다.
  2. tool_calls, function_call, Anthropic tool_use, 또는 Gemini 함수 호출 부분에 대한 모델 응답을 읽습니다.
  3. 귀하의 백엔드에서 도구를 실행합니다.
  4. 동일한 경로에서 요구되는 형식으로 도구 결과를 추가합니다.
  5. 모델이 최종 답변을 반환할 때까지 대화를 계속합니다.
도구 루프 전반에 걸쳐 동일한 경로를 유지하십시오. Chat Completions, Responses, Messages, 및 Gemini 형식을 하나의 대화에서 혼합하면 일반적으로 미세한 상태 및 스키마 버그가 발생합니다.

​
Chat Completions 예제

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {
        "role": "user",
        "content": "이름과 이메일을 JSON으로 추출하세요. 필요하다면 고객을 조회하세요."
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "이메일로 고객 조회",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'

​
스키마 설계

  • 스키마를 작고 명시적으로 유지하십시오. 큰 중첩 스키마는 토큰을 추가하고 신뢰성을 감소시킵니다.
  • 제품이 계속 진행할 수 없는 값에 대해 필수 필드를 선호하십시오.
  • UI 또는 백엔드가 의존하는 닫힌 집합에 대해 enums를 사용하십시오.
  • 모델이 형상에 어려움을 겪을 때 프롬프트에 예제를 포함하십시오.
  • 지원되지 않는 필드 오류를 계약 피드백으로 취급하십시오. 필드를 제거하거나 이를 문서화한 기본 경로를 사용하십시오.

​
프로덕션 체크리스트

  • 경로, 모델, 도구 이름 및 정제된 스키마 형상을 로그에 기록하십시오.
  • 부작용을 실행하기 전에 도구 인수를 검증하십시오.
  • 도구 실행 전에 귀하의 권한 검사를 적용하십시오.
  • 클라이언트 재시도가 동일한 도구 호출을 반복할 수 있을 때 도구 실행을 멱등성 있게 만드십시오.
  • 도구가 반환한 비밀을 모델이 볼 수 있는 메시지에 기록하지 마십시오.

​
API 참조

주제참조
다중 형식 API다중 형식 API
채팅 완료 생성채팅 완료 생성
응답 생성응답 생성
메시지 생성메시지 생성
Gemini 콘텐츠 생성Gemini 콘텐츠 생성