{ "openapi": "3.1.0", "info": { "title": "GLM-5.2 전체 파라미터 문서 (OpenAI 호환)", "description": "GLM-5.2 대화 인터페이스의 전체 API 레퍼런스입니다.\n\n**모델 능력**:\n- 최신 플래그십 모델로, 복잡한 추론, 초장문 컨텍스트와 극대화된 추론 속도를 제공\n- 최대 출력: **131,072 tokens**(128K), 권장 **1,024 tokens** 이상\n- 심층 사고: `thinking` 필드로 사고 체인을 켜고 끄며, `reasoning_effort`로 추론 강도를 조절(GLM-5.2 전용)\n- 도구 호출: Function Calling, 지식베이스 검색, 웹 검색, MCP 지원(최대 128개 도구)\n- 스트리밍 출력: SSE 스트리밍 응답 지원\n- 구조화 출력: `text` / `json_object` 두 가지 응답 형식 지원", "license": { "name": "MIT" }, "version": "1.0.0" }, "servers": [ { "url": "https://direct.evolink.ai", "description": "프로덕션 (권장)" }, { "url": "https://api.evolink.ai", "description": "대체 URL" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/chat/completions": { "post": { "summary": "GLM-5.2 대화 인터페이스(OpenAI 호환)", "description": "- OpenAI Chat Completions 프로토콜을 사용하여 GLM-5.2 모델을 호출합니다\n- 동기 처리 모드로 대화 내용을 실시간으로 반환합니다\n- **순수 텍스트 대화**: 단일 턴 또는 멀티턴 컨텍스트 대화\n- **시스템 프롬프트**: `role=system` 메시지로 AI의 역할과 동작을 사용자 정의\n- **심층 사고**: `thinking.type`으로 사고 체인을 켜고 끄며, `reasoning_effort`로 추론 강도를 조절; 추론 과정은 `reasoning_content`를 통해 반환\n- **스트리밍 출력**: SSE 스트리밍 응답 지원(`stream=true`)\n- **도구 호출**: Function Calling, 지식베이스 검색(retrieval), 웹 검색(web_search), MCP 지원(최대 128개 도구)\n- **구조화 출력**: `response_format`으로 JSON 모드 활성화\n\n**스트리밍 응답 설명**: `stream=true`일 때 Server-Sent Events를 통해 반환하며, 각 메시지의 형식은 `data: {JSON}`이고 종료 시 `data: [DONE]`을 반환합니다. 각 데이터 청크(`ChatCompletionChunk`)는 `id`, `created`, `model`, `choices`와 선택적인 `usage`, `content_filter`를 포함하며, 그중 `choices[].delta`는 `role` / `content` / `reasoning_content` / `tool_calls`를 증분으로 반환하고 `choices[].finish_reason`은 마지막 청크에서 종료 사유를 제공합니다.", "operationId": "createChatCompletionGLM52", "tags": [ "대화 생성" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" }, "examples": { "simple_text": { "summary": "단일 턴 텍스트 대화", "value": { "model": "glm-5.2", "messages": [ { "role": "user", "content": "자기소개를 해 주세요" } ] } }, "multi_turn": { "summary": "멀티턴 대화(컨텍스트 이해)", "value": { "model": "glm-5.2", "messages": [ { "role": "user", "content": "Python이란 무엇인가요?" }, { "role": "assistant", "content": "Python은 고급 프로그래밍 언어입니다……" }, { "role": "user", "content": "그 장점은 무엇인가요?" } ] } }, "system_prompt": { "summary": "시스템 프롬프트 사용", "value": { "model": "glm-5.2", "messages": [ { "role": "system", "content": "당신은 전문적인 Python 프로그래밍 어시스턴트입니다. 간결한 언어로 질문에 답하세요." }, { "role": "user", "content": "파일을 어떻게 읽나요?" } ] } }, "deep_thinking": { "summary": "심층 사고 활성화 및 추론 강도 조절", "value": { "model": "glm-5.2", "messages": [ { "role": "user", "content": "한 농부가 늑대, 양, 양배추를 데리고 강을 건너야 하는데 한 번에 하나만 옮길 수 있습니다. 어떻게 안전하게 건널 수 있을까요?" } ], "thinking": { "type": "enabled" }, "reasoning_effort": "max" } }, "disable_thinking": { "summary": "심층 사고 비활성화(직접 답변)", "value": { "model": "glm-5.2", "messages": [ { "role": "user", "content": "상대성 이론을 한 문장으로 요약해 주세요." } ], "thinking": { "type": "disabled" } } }, "function_calling": { "summary": "도구 호출(Function Calling)", "value": { "model": "glm-5.2", "messages": [ { "role": "user", "content": "베이징의 오늘 날씨는 어떤가요?" } ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "지정한 도시의 실시간 날씨를 조회합니다", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "도시 이름, 예: 베이징" } }, "required": [ "city" ] } } } ], "tool_choice": "auto" } }, "web_search": { "summary": "웹 검색 도구 활성화", "value": { "model": "glm-5.2", "messages": [ { "role": "user", "content": "최근 일주일간의 인공지능 뉴스를 조회해 주세요" } ], "tools": [ { "type": "web_search", "web_search": { "enable": true, "search_engine": "search_pro", "count": 10, "search_recency_filter": "oneWeek" } } ] } }, "json_mode": { "summary": "JSON 구조화 출력", "value": { "model": "glm-5.2", "messages": [ { "role": "system", "content": "name과 age 두 필드를 포함하여 JSON 형식으로 출력해 주세요." }, { "role": "user", "content": "홍길동, 올해 28세" } ], "response_format": { "type": "json_object" } } }, "streaming": { "summary": "스트리밍 출력(SSE)", "value": { "model": "glm-5.2", "messages": [ { "role": "user", "content": "봄에 관한 짧은 시를 써 주세요" } ], "stream": true } } } } } }, "responses": { "200": { "description": "대화 생성 성공", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } } } }, "400": { "description": "잘못된 요청 파라미터", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 400, "message": "Invalid request parameters", "type": "invalid_request_error" } } } } }, "401": { "description": "인증되지 않음, 토큰이 유효하지 않거나 만료됨", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 401, "message": "Invalid or expired token", "type": "authentication_error" } } } } }, "402": { "description": "할당량 부족, 충전 필요", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 402, "message": "Insufficient quota", "type": "insufficient_quota_error", "fallback_suggestion": "https://evolink.ai/dashboard/billing" } } } } }, "403": { "description": "접근 권한 없음", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 403, "message": "Access denied for this model", "type": "permission_error", "param": "model" } } } } }, "404": { "description": "리소스를 찾을 수 없음", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 404, "message": "Specified model not found", "type": "not_found_error", "param": "model", "fallback_suggestion": "glm-5.2" } } } } }, "429": { "description": "요청 빈도 초과", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 429, "message": "Rate limit exceeded", "type": "rate_limit_error", "fallback_suggestion": "retry after 60 seconds" } } } } }, "500": { "description": "서버 내부 오류", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 500, "message": "Internal server error", "type": "internal_server_error", "fallback_suggestion": "try again later" } } } } }, "502": { "description": "업스트림 서비스 오류", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 502, "message": "Upstream AI service unavailable", "type": "upstream_error", "fallback_suggestion": "try different model" } } } } }, "503": { "description": "서비스를 일시적으로 사용할 수 없음", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": 503, "message": "Service temporarily unavailable", "type": "service_unavailable_error", "fallback_suggestion": "retry after 30 seconds" } } } } } } } } }, "components": { "schemas": { "ChatCompletionRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "description": "호출할 모델 코드\n\n- `glm-5.2`: 최신 플래그십 모델로, 복잡한 추론, 초장문 컨텍스트와 극대화된 추론 속도를 제공", "enum": [ "glm-5.2" ], "default": "glm-5.2", "example": "glm-5.2" }, "messages": { "type": "array", "description": "대화 메시지 목록으로, 현재 대화의 완전한 컨텍스트 정보를 포함합니다\n\n`system`, `user`, `assistant`, `tool` 네 가지 역할을 지원합니다. 역할마다 메시지의 필드 구조가 다르므로 해당 역할을 선택하여 확인하세요. 최소 1개의 메시지를 포함해야 하며, 시스템 메시지나 어시스턴트 메시지만 포함할 수는 없습니다.", "items": { "oneOf": [ { "$ref": "#/components/schemas/SystemMessage" }, { "$ref": "#/components/schemas/UserMessage" }, { "$ref": "#/components/schemas/AssistantRequestMessage" }, { "$ref": "#/components/schemas/ToolMessage" } ], "discriminator": { "propertyName": "role", "mapping": { "system": "#/components/schemas/SystemMessage", "user": "#/components/schemas/UserMessage", "assistant": "#/components/schemas/AssistantRequestMessage", "tool": "#/components/schemas/ToolMessage" } } }, "minItems": 1 }, "stream": { "type": "boolean", "description": "스트리밍 출력 모드를 활성화할지 여부\n\n- `false`: 모델이 완전한 응답을 생성한 후 한 번에 반환(기본값), 짧은 텍스트와 일괄 처리에 적합\n- `true`: Server-Sent Events(SSE)를 통해 청크 단위로 실시간 반환, 채팅과 장문에 적합; 스트리밍 종료 시 `data: [DONE]`을 반환", "default": false, "example": false }, "thinking": { "type": "object", "description": "사고 체인(Chain of Thought)을 켤지 여부를 제어합니다", "properties": { "type": { "type": "string", "description": "사고 체인 스위치\n\n- `enabled`: 심층 사고 활성화(기본값)\n- `disabled`: 심층 사고를 비활성화하고 모델이 직접 답변", "enum": [ "enabled", "disabled" ], "default": "enabled" }, "clear_thinking": { "type": "boolean", "description": "과거 대화 턴의 `reasoning_content`를 제거할지 여부\n\n- `true`(기본값): 과거 턴의 `reasoning_content`를 무시/제거하고, 추론이 아닌 내용(사용자/어시스턴트가 볼 수 있는 텍스트, 도구 호출과 결과 등)만 컨텍스트로 사용하여 컨텍스트 길이와 비용을 줄일 수 있습니다\n- `false`: 과거 턴의 `reasoning_content`를 유지하고 컨텍스트와 함께 모델에 제공합니다(Preserved Thinking); 이 경우 `messages`에 과거 `reasoning_content`를 **완전하고, 수정 없이, 원래 순서대로** 그대로 전달해야 하며, 누락, 잘림, 변형 또는 재배열은 효과 저하나 동작 불능을 초래합니다\n- 참고: 이 파라미터는 턴 간의 과거 사고에만 영향을 주며, 현재 턴에서 사고를 생성하는지 여부는 바꾸지 않습니다", "default": true, "example": true } } }, "reasoning_effort": { "type": "string", "description": "모델의 추론 정도를 제어합니다(GLM-5.2 전용 능력)\n\n**설명**:\n- `thinking`이 켜진 경우에만 유효하며, 기본값은 `max`\n- 값은 강한 것부터 약한 것 순서로: `max` > `xhigh` > `high` > `medium` > `low` > `minimal` > `none`\n\n**GLM-5.2 매핑 규칙**(다른 프로토콜과의 호환을 위해):\n- `xhigh` → `max`와 동등\n- `low` / `medium` → `high`와 동등\n- `none` / `minimal` → 사고 포기(심층 추론을 수행하지 않음)", "enum": [ "max", "xhigh", "high", "medium", "low", "minimal", "none" ], "default": "max", "example": "max" }, "do_sample": { "type": "boolean", "description": "샘플링 전략을 활성화할지 여부\n\n- `true`(기본값): `temperature` / `top_p`로 무작위 샘플링을 수행하여 출력이 더 다양해짐\n- `false`: 항상 확률이 가장 높은 단어를 선택(그리디 디코딩)하여 출력이 더 확정적이며, 이때 `temperature`와 `top_p`는 무시됩니다\n\n일관성과 재현성이 필요한 작업(예: 코드 생성, 번역)에는 `false`로 설정하는 것을 권장합니다", "default": true, "example": true }, "temperature": { "type": "number", "format": "float", "description": "샘플링 온도로, 출력의 무작위성과 창의성을 제어합니다\n\n**설명**:\n- 범위: `[0.0, 1.0]`, 소수점 둘째 자리까지\n- 높은 값(예: 0.8): 더 무작위하고 창의적이며 창작 글쓰기에 적합\n- 낮은 값(예: 0.2): 더 안정적이고 확정적이며 사실 기반 질의응답과 코드 생성에 적합\n- GLM-5.2 기본값: `1.0`\n\n**권장 사항**: `temperature`와 `top_p`를 동시에 조정하지 마세요", "minimum": 0, "maximum": 1, "default": 1, "example": 1 }, "top_p": { "type": "number", "format": "float", "description": "핵 샘플링(Nucleus Sampling) 파라미터로, `temperature` 샘플링의 대체 방법입니다\n\n**설명**:\n- 범위: `[0.01, 1.0]`, 소수점 둘째 자리까지\n- 모델은 누적 확률이 `top_p`에 도달하는 후보 단어만 고려하며, 예를 들어 0.1은 상위 10% 확률의 단어만 고려함을 의미합니다\n- 작은 값은 더 집중되고 일관된 출력을 만들며, 큰 값은 다양성을 높입니다\n- GLM-5.2 기본값: `0.95`\n\n**권장 사항**: `temperature`와 `top_p`를 동시에 조정하지 마세요", "minimum": 0.01, "maximum": 1, "default": 0.95, "example": 0.95 }, "max_tokens": { "type": "integer", "description": "모델 출력의 최대 token 수 제한\n\n**설명**:\n- GLM-5.2는 최대 **131,072 tokens**(128K) 출력 길이를 지원하며, `1024` 이상으로 설정하는 것을 권장합니다\n- `thinking`이 켜진 경우 사고 체인 token도 이 상한에 포함됩니다\n- 생성이 `length` 사유로 잘린 경우 이 값을 높여 보세요", "minimum": 1, "maximum": 131072, "example": 1024 }, "tools": { "type": "array", "description": "모델이 호출할 수 있는 도구 목록\n\n**설명**:\n- 함수 호출(`function`), 지식베이스 검색(`retrieval`), 웹 검색(`web_search`), MCP(`mcp`) 지원\n- 최대 128개 함수 지원", "items": { "oneOf": [ { "$ref": "#/components/schemas/FunctionTool" }, { "$ref": "#/components/schemas/RetrievalTool" }, { "$ref": "#/components/schemas/WebSearchTool" }, { "$ref": "#/components/schemas/McpTool" } ], "discriminator": { "propertyName": "type", "mapping": { "function": "#/components/schemas/FunctionTool", "retrieval": "#/components/schemas/RetrievalTool", "web_search": "#/components/schemas/WebSearchTool", "mcp": "#/components/schemas/McpTool" } } }, "maxItems": 128 }, "tool_choice": { "type": "string", "description": "모델이 어떤 함수를 호출할지 선택하는 방식을 제어합니다\n\n**설명**: 도구 유형이 `function`일 때만 유효하며, 기본값이자 `auto`만 지원합니다(모델이 도구 호출 여부를 자동으로 결정)", "enum": [ "auto" ], "default": "auto", "example": "auto" }, "stop": { "type": "array", "description": "중지 단어 목록\n\n**설명**:\n- 모델이 생성하는 텍스트가 지정한 문자열을 만나면 즉시 생성을 중지합니다(중지 단어 자체는 반환 텍스트에 포함되지 않음)\n- 현재는 단일 중지 단어만 지원하며, 형식은 `[\"stop_word1\"]`, 예: `[\"Human:\"]`", "items": { "type": "string" }, "maxItems": 4, "example": [ "Human:" ] }, "response_format": { "type": "object", "description": "모델 응답 출력 형식을 지정하며, 기본값은 `text`입니다\n\n**설명**:\n- `{ \"type\": \"json_object\" }`는 JSON 모드를 활성화하며, 모델이 유효한 JSON 형식 데이터를 반환하여 구조화 데이터 추출 등의 시나리오에 적합합니다\n- JSON 모드를 사용할 때는 `system` 또는 `user` 메시지에서 JSON 출력을 명확히 요구하는 것을 권장합니다", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "출력 형식 유형\n\n- `text`: 일반 텍스트 출력(기본값)\n- `json_object`: JSON 형식 출력", "enum": [ "text", "json_object" ], "default": "text" } } }, "request_id": { "type": "string", "description": "요청 고유 식별자\n\n**설명**:\n- 사용자 측에서 전달하며, 길이는 6-64자이고 고유성을 보장하기 위해 UUID 형식을 권장합니다\n- 제공하지 않으면 플랫폼이 자동으로 생성합니다", "minLength": 6, "maxLength": 64, "example": "req-7f3a2c1e8b9d4f0a" }, "user_id": { "type": "string", "description": "최종 사용자의 고유 식별자\n\n**설명**: 길이는 6-128자이며, 민감한 정보를 포함하지 않는 고유 식별자 사용을 권장합니다. 플랫폼이 남용 행위를 모니터링하고 탐지하는 데 도움이 됩니다", "minLength": 6, "maxLength": 128, "example": "user-abc123456" } } }, "SystemMessage": { "title": "System Message", "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "system" ], "description": "역할 식별자, `system`으로 고정" }, "content": { "type": "string", "description": "시스템 프롬프트 내용, AI의 역할과 동작을 설정하는 데 사용" } } }, "UserMessage": { "title": "User Message", "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user" ], "description": "역할 식별자, `user`로 고정" }, "content": { "type": "string", "description": "사용자 메시지 내용(순수 텍스트 문자열)" } } }, "AssistantRequestMessage": { "title": "Assistant Message", "type": "object", "description": "어시스턴트 메시지, 도구 호출을 포함할 수 있음", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "assistant" ], "description": "역할 식별자, `assistant`로 고정" }, "content": { "type": [ "string", "null" ], "description": "어시스턴트 메시지 내용\n\n**설명**: 멀티턴 대화에서 과거 어시스턴트 응답을 전달하는 데 사용; `tool_calls`가 존재할 때는 보통 `null`입니다" }, "reasoning_content": { "type": [ "string", "null" ], "description": "과거 사고 체인 내용\n\n**설명**: `thinking.clear_thinking=false`(Preserved Thinking)일 때만 필요하며, 이전 턴 응답의 `reasoning_content`를 그대로 다시 전달; 기본값(`clear_thinking=true`)에서는 다시 전달할 필요가 없습니다" }, "tool_calls": { "type": "array", "description": "도구 호출 목록\n\n멀티턴 대화에서 과거 도구 호출 정보를 전달하는 데 사용; 이 필드를 제공할 때 `content`는 보통 비어 있습니다", "items": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "도구 호출 ID" }, "type": { "type": "string", "enum": [ "function", "web_search", "retrieval" ], "description": "도구 유형" }, "function": { "type": "object", "description": "함수 호출 정보, `type`이 `function`일 때 비어 있지 않음", "required": [ "name", "arguments" ], "properties": { "name": { "type": "string", "description": "함수 이름" }, "arguments": { "type": "string", "description": "함수 인자(JSON 형식 문자열)" } } } } } } } }, "ToolMessage": { "title": "Tool Message", "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "tool" ], "description": "역할 식별자, `tool`로 고정" }, "content": { "type": "string", "description": "도구 호출 반환 결과 내용" }, "tool_call_id": { "type": "string", "description": "이 메시지에 대응하는 도구 호출 `ID`를 가리킵니다(assistant 메시지의 `tool_calls`에서 반환된 `id`에 대응)" } } }, "FunctionTool": { "title": "Function 도구", "type": "object", "required": [ "type", "function" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "function" ], "default": "function", "description": "도구 유형, `function`으로 고정" }, "function": { "type": "object", "required": [ "name", "description", "parameters" ], "properties": { "name": { "type": "string", "description": "호출할 함수 이름\n\n**설명**: `a-z`, `A-Z`, `0-9` 문자로 구성하거나 밑줄과 하이픈을 포함해야 합니다; 최대 길이는 64자입니다", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$" }, "description": { "type": "string", "description": "함수 기능 설명, 모델이 언제 어떻게 함수를 호출할지 선택하는 데 사용" }, "parameters": { "type": "object", "description": "함수의 입력 파라미터, JSON Schema 객체로 기술" } } } } }, "RetrievalTool": { "title": "Retrieval 도구(지식베이스 검색)", "type": "object", "required": [ "type", "retrieval" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "retrieval" ], "default": "retrieval", "description": "도구 유형, `retrieval`로 고정" }, "retrieval": { "type": "object", "required": [ "knowledge_id" ], "properties": { "knowledge_id": { "type": "string", "description": "지식베이스 `ID`, 플랫폼에서 생성하거나 가져옴" }, "prompt_template": { "type": "string", "description": "모델 요청용 프롬프트 템플릿으로, 플레이스홀더 `{{ knowledge }}`와 `{{ question }}`을 포함하는 사용자 정의 템플릿; 전달하지 않으면 기본 템플릿을 사용합니다" } } } } }, "WebSearchTool": { "title": "Web Search 도구(웹 검색)", "type": "object", "required": [ "type", "web_search" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "web_search" ], "default": "web_search", "description": "도구 유형, `web_search`로 고정" }, "web_search": { "type": "object", "required": [ "search_engine" ], "properties": { "enable": { "type": "boolean", "description": "검색 기능을 활성화할지 여부, 활성화 시 `true`로 설정", "default": false }, "search_engine": { "type": "string", "description": "검색 엔진 유형, 기본값 `search_std`", "enum": [ "search_std", "search_pro", "search_pro_sogou", "search_pro_quark" ] }, "search_query": { "type": "string", "description": "검색을 강제로 트리거하는 사용자 정의 키워드" }, "search_intent": { "type": "string", "description": "검색 의도 인식을 수행할지 여부, 기본적으로 수행\n\n- `true`: 검색 의도 인식을 수행하고, 검색 의도가 있으면 검색을 실행\n- `false`: 의도 인식을 건너뛰고 검색을 바로 실행" }, "count": { "type": "integer", "description": "반환 결과의 개수, 범위 `1-50`, 기본값 `10`(`search_std` / `search_pro` / `search_pro_sogou` 지원)", "minimum": 1, "maximum": 50, "default": 10 }, "search_domain_filter": { "type": "string", "description": "검색 결과를 제한하는 도메인 화이트리스트(예: `www.example.com`)" }, "search_recency_filter": { "type": "string", "description": "검색 결과의 시간 범위를 제한, 기본값 `noLimit`", "enum": [ "oneDay", "oneWeek", "oneMonth", "oneYear", "noLimit" ], "default": "noLimit" }, "content_size": { "type": "string", "description": "웹페이지 요약의 글자 수를 제어, 기본값 `medium`\n\n- `medium`: 요약 정보를 반환하여 기본 추론 요구를 충족\n- `high`: 컨텍스트를 최대화하여 정보가 더 상세함", "enum": [ "medium", "high" ], "default": "medium" }, "result_sequence": { "type": "string", "description": "검색 결과를 반환하는 위치(모델 응답의 앞 또는 뒤), 기본값 `after`", "enum": [ "before", "after" ], "default": "after" }, "search_result": { "type": "boolean", "description": "검색 출처의 상세 정보를 반환할지 여부, 기본값 `false`", "default": false }, "require_search": { "type": "boolean", "description": "검색 결과를 기반으로만 답변을 반환하도록 강제할지 여부, 기본값 `false`", "default": false }, "search_prompt": { "type": "string", "description": "검색 결과 처리를 사용자 정의하는 데 사용하는 `Prompt`, 전달하지 않으면 기본 템플릿을 사용합니다" } } } } }, "McpTool": { "title": "MCP 도구", "type": "object", "required": [ "type", "mcp" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "mcp" ], "default": "mcp", "description": "도구 유형, `mcp`로 고정" }, "mcp": { "type": "object", "required": [ "server_label" ], "properties": { "server_label": { "type": "string", "description": "MCP server 식별자; 플랫폼 내장 MCP server에 연결할 때는 해당 mcp code를 입력하며, `server_url`은 입력할 필요가 없습니다" }, "server_url": { "type": "string", "description": "MCP server 주소" }, "transport_type": { "type": "string", "description": "전송 유형", "enum": [ "sse", "streamable-http" ], "default": "streamable-http" }, "allowed_tools": { "type": "array", "description": "호출을 허용할 도구 집합", "items": { "type": "string" } }, "headers": { "type": "object", "description": "MCP server에 필요한 인증 정보" } } } } }, "ChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "작업 `ID`", "example": "chatcmpl-a6613b56-c61c-94ba-9a9f-43d4cdc7d77a" }, "object": { "type": "string", "description": "응답 유형", "enum": [ "chat.completion" ], "example": "chat.completion" }, "request_id": { "type": "string", "description": "요청 `ID`(요청에서 `request_id`를 제공한 경우 다시 반환)", "example": "req-7f3a2c1e8b9d4f0a" }, "created": { "type": "integer", "description": "요청 생성 시각, `Unix` 타임스탬프(초)", "example": 1777021417 }, "model": { "type": "string", "description": "모델 이름", "example": "glm-5.2" }, "choices": { "type": "array", "description": "모델 응답 목록", "items": { "$ref": "#/components/schemas/Choice" } }, "usage": { "$ref": "#/components/schemas/Usage" }, "web_search": { "type": "array", "description": "웹 검색 관련 정보, `web_search` 도구를 사용하고 검색에 적중했을 때 반환", "items": { "$ref": "#/components/schemas/WebSearchResult" } }, "content_filter": { "type": "array", "description": "콘텐츠 안전 관련 정보", "items": { "$ref": "#/components/schemas/ContentFilter" } } } }, "Choice": { "type": "object", "properties": { "index": { "type": "integer", "description": "결과 인덱스", "example": 0 }, "message": { "$ref": "#/components/schemas/AssistantMessage" }, "finish_reason": { "type": "string", "description": "추론 종료 사유\n\n- `stop`: 자연스러운 종료 또는 중지 단어 트리거\n- `tool_calls`: 모델이 함수(도구 호출)에 적중\n- `length`: token 길이 제한 도달\n- `sensitive`: 콘텐츠가 안전 심사에 의해 차단됨(판단하여 공개 콘텐츠 철회 여부를 결정하세요)\n- `network_error`: 모델 추론 이상\n- `model_context_window_exceeded`: 모델 컨텍스트 윈도우 초과", "enum": [ "stop", "tool_calls", "length", "sensitive", "network_error", "model_context_window_exceeded" ], "example": "stop" } } }, "AssistantMessage": { "type": "object", "properties": { "role": { "type": "string", "description": "현재 대화 역할, 기본값 `assistant`", "enum": [ "assistant" ], "example": "assistant" }, "content": { "type": [ "string", "null" ], "description": "대화 텍스트 내용\n\n**설명**: 도구를 호출(`tool_calls`)할 때는 `null`일 수 있으며, 그렇지 않으면 모델 응답 내용을 반환합니다", "example": "안녕하세요! 저는 GLM-5.2로, 대화, 추론, 작문, 코딩 등 다양한 작업을 도와드릴 수 있습니다." }, "reasoning_content": { "type": "string", "description": "사고 체인 내용\n\n**설명**: `thinking`이 켜진 경우 반환되며, 모델의 추론 과정을 기록합니다", "example": "먼저 이 문제를 분석해 보겠습니다……" }, "tool_calls": { "type": "array", "description": "생성된 도구 호출 정보(모델이 도구를 호출하기로 결정했을 때 반환)", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "도구 호출의 고유 식별자" }, "type": { "type": "string", "description": "도구 호출 유형", "enum": [ "function", "mcp" ] }, "function": { "type": "object", "description": "함수 호출 정보(생성된 함수 이름과 JSON 형식 인자를 포함)", "properties": { "name": { "type": "string", "description": "생성된 함수 이름" }, "arguments": { "type": "string", "description": "함수 호출 인자의 JSON 형식 문자열, 함수를 호출하기 전에 인자를 검증하세요" } } }, "mcp": { "type": "object", "description": "MCP 도구 호출 파라미터(`type=mcp`일 때 반환)", "properties": { "id": { "type": "string", "description": "MCP 도구 호출 고유 식별자" }, "type": { "type": "string", "description": "MCP 호출 유형", "enum": [ "mcp_list_tools", "mcp_call" ] }, "server_label": { "type": "string", "description": "MCP server 라벨" }, "error": { "type": "string", "description": "오류 정보" } } } } } } } }, "Usage": { "type": "object", "description": "호출 종료 시 반환되는 Token 사용 통계", "properties": { "prompt_tokens": { "type": "integer", "description": "사용자 입력의 token 수", "example": 24 }, "completion_tokens": { "type": "integer", "description": "출력의 token 수(사고 체인 `reasoning_tokens` 부분 포함)", "example": 346 }, "total_tokens": { "type": "integer", "description": "token 총수 = prompt_tokens + completion_tokens", "example": 370 }, "prompt_tokens_details": { "type": "object", "description": "입력 token 상세 내역", "properties": { "cached_tokens": { "type": "integer", "description": "캐시에 적중한 token 수", "example": 0 } } }, "completion_tokens_details": { "type": "object", "description": "출력 token 상세 내역", "properties": { "reasoning_tokens": { "type": "integer", "description": "사고 체인(심층 사고)에서 생성된 token 수, `completion_tokens`에 포함됨", "example": 321 } } } } }, "WebSearchResult": { "type": "object", "description": "단일 웹 검색 결과", "properties": { "icon": { "type": "string", "description": "출처 사이트의 아이콘" }, "title": { "type": "string", "description": "검색 결과의 제목" }, "link": { "type": "string", "description": "검색 결과의 웹페이지 링크" }, "media": { "type": "string", "description": "검색 결과 웹페이지의 미디어 출처 이름" }, "publish_date": { "type": "string", "description": "사이트 게시 시각" }, "content": { "type": "string", "description": "검색 결과 웹페이지에서 인용한 텍스트 내용" }, "refer": { "type": "string", "description": "각주 번호" } } }, "ContentFilter": { "type": "object", "description": "콘텐츠 안전 정보", "properties": { "role": { "type": "string", "description": "안전이 적용되는 단계\n\n- `assistant`: 모델 추론\n- `user`: 사용자 입력\n- `history`: 과거 컨텍스트", "enum": [ "assistant", "user", "history" ] }, "level": { "type": "integer", "description": "심각도 `0-3`, `0`은 가장 심각함을, `3`은 경미함을 의미", "minimum": 0, "maximum": 3 } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "HTTP 상태 오류 코드" }, "message": { "type": "string", "description": "오류 설명 정보" }, "type": { "type": "string", "description": "오류 유형" }, "param": { "type": "string", "description": "관련 파라미터 이름" }, "fallback_suggestion": { "type": "string", "description": "오류 시의 권장 사항" } } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "##모든 인터페이스는 Bearer Token 인증이 필요합니다##\n\n**API Key 발급**:\n\n[API Key 관리 페이지](https://evolink.ai/dashboard/keys)에 방문하여 API Key를 발급받으세요\n\n**요청 헤더에 추가**:\n```\nAuthorization: Bearer YOUR_API_KEY\n```" } } }, "tags": [ { "name": "대화 생성", "description": "AI 대화 생성 관련 인터페이스" } ] }