Multimodal Understanding API Reference
텍스트, 이미지, 영상, 오디오를 모델에 전달하고 텍스트나 구조화된 결과를 받는 VOD API입니다. VOD 애플리케이션의 SubAppId를 지정해 API 키를 먼저 발급하고, 발급된 ApiToken으로 모델을 호출합니다.
호출 규격
호출 준비
1. VOD 애플리케이션 선택
VOD에서 사용할 애플리케이션을 만들고 SubAppId를 확인합니다. 키 발급과 쿼터 관리에는 이 ID를 사용합니다. 모델 호출에는 키에 연결된 애플리케이션 정보가 적용됩니다.
2. API 키 발급
vod.intl.tencentcloudapi.com의 CreateAigcApiToken을 호출합니다. 이 단계는 Tencent Cloud SecretId와 SecretKey로 TC3 서명합니다.
json
{
"SubAppId": 123456789
}TC3 호출 스크립트를 사용하는 경우:
bash
python3 tencent-api.py vod CreateAigcApiToken create-token.json응답의 ApiToken을 이후 모델 요청의 Bearer 키로 사용합니다. 애플리케이션 ID나 SecretKey를 Bearer 키로 전달하지 않습니다.
3. 발급한 키로 모델 호출
bash
export VOD_API_TOKEN='your-vod-aigc-token'
curl https://mmu.vod-qcloud.com/v1/chat/completions \
-H "Authorization: Bearer ${VOD_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.8-flash",
"messages": [
{
"role": "user",
"content": "재시도 간격을 점차 늘리는 이유를 한 문장으로 설명해 주세요."
}
],
"max_tokens": 2048,
"stream": false
}'모델 호출의 주소는 mmu.vod-qcloud.com입니다. 키 발급에 사용하는 Tencent Cloud API 주소와 구분합니다.
API 키 관리
| 작업 | VOD 액션 | 인증 |
|---|---|---|
| 발급 | CreateAigcApiToken | TC3 서명 |
| 목록 조회 | DescribeAigcApiTokens | TC3 서명 |
| 삭제 | DeleteAigcApiToken | TC3 서명 |
| 쿼터 조회 | DescribeAigcQuotas | TC3 서명 |
| 쿼터 생성 / 변경 / 삭제 | CreateAigcQuota / ModifyAigcQuota / DeleteAigcQuota | TC3 서명 |
키는 무기한 유효하며 최대 50개를 발급할 수 있습니다. 생성과 삭제 후 목록에 반영되기까지 약 30초가 걸릴 수 있습니다. 서브 계정에는 해당 VOD 액션의 CAM 권한을 부여합니다.
프로토콜 선택
| 프로토콜 | 요청 경로 | 입력의 중심 필드 | 결과의 중심 필드 |
|---|---|---|---|
| Chat Completions | POST /v1/chat/completions | messages | choices.message |
| Responses | POST /v1/responses | input | output |
| Messages | POST /v1/messages | messages / system | content |
같은 모델을 여러 프로토콜로 호출할 수 있어도 요청 필드와 응답 구조는 다릅니다. 모델별 문서의 지원 프로토콜에서 사용할 경로를 고른 뒤 해당 규격으로 요청을 구성합니다.
인증과 세션 헤더
| 헤더 | 필수 | 값 / 용도 |
|---|---|---|
Authorization | 필수 | Bearer ${VOD_API_TOKEN} |
Content-Type | 필수 | application/json |
x-api-key | 선택 | Messages 연동에서 사용할 수 있는 API 키 헤더 |
X-Request-Id | 선택 | 요청 추적 ID |
Tx-User-Session-Id | 선택 | 동일 대화의 요청을 연결하는 세션 ID |
호출 가능한 모델 조회
bash
curl https://mmu.vod-qcloud.com/v1/models \
-H "Authorization: Bearer ${VOD_API_TOKEN}"응답의 data.id가 요청에 넣는 model 값입니다. 모델의 표시 이름과 API 식별자를 구분합니다.
API 목록과 요청 파라미터
Chat Completions
요청 파라미터
| 파라미터 | 필수 | 타입 | 설명 |
|---|---|---|---|
model | 필수 | String | 모델 ID |
messages | 필수 | Array | 역할과 내용을 포함한 대화 이력 |
stream | 선택 | Boolean | SSE 스트리밍 여부 |
max_tokens | 선택 | Integer | 최대 생성 토큰 수. 추론 토큰을 포함 |
max_completion_tokens | 선택 | Integer | SDK 호환용 생성 토큰 한도. max_tokens와 중복 지정하지 않음 |
temperature | 선택 | Number | 샘플링 온도. 허용 범위는 모델별 문서 참조 |
top_p | 선택 | Number | 누적 확률 기반 샘플링 |
top_k | 선택 | Integer | 지원 모델의 후보 토큰 수 제한 |
reasoning_effort | 선택 | String | 모델별 추론 강도 |
thinking_enabled | 선택 | Boolean | 지원 모델의 추론 활성화 여부 |
tools | 선택 | Array | 호출 가능한 도구와 입력 스키마 |
tool_choice | 선택 | String / Object | 자동 선택, 도구 사용 강제, 특정 도구 선택 |
response_format | 선택 | Object | 일반 텍스트, JSON 또는 JSON Schema 출력 |
stream_options | 선택 | Object | include_usage=true로 스트림 사용량 수신 |
max_tokens는 입력과 출력을 합친 컨텍스트 한도가 아닙니다. 모델의 컨텍스트 한도, 생성 한도, 계정의 TPM 쿼터는 각각 별도로 적용됩니다.
메시지 구조
| 필드 | 타입 | 설명 |
|---|---|---|
role | String | system / developer / user / assistant / tool |
content | String / Array | 텍스트 또는 미디어 Part 배열 |
tool_calls | Array | 모델이 요청한 함수 이름과 인수 |
tool_call_id | String | 도구 결과와 원래 호출을 연결하는 ID |
응답 예시
json
{
"id": "chatcmpl-example",
"object": "chat.completion",
"model": "gemini-3.8-flash",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "재시도 간격을 늘리면 장애가 난 서버에 요청이 몰리는 것을 줄일 수 있습니다."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 24,
"completion_tokens": 32,
"total_tokens": 56
}
}finish_reason=length는 생성 한도에 도달했다는 뜻입니다. 추론을 사용하는 요청에서는 최종 답변을 위한 토큰도 남도록 한도를 설정합니다.
Responses
요청 파라미터
| 파라미터 | 필수 | 타입 | 설명 |
|---|---|---|---|
model | 필수 | String | 모델 ID |
input | 필수 | String / Array | 입력 텍스트, 메시지, 도구 결과 |
instructions | 선택 | String | 모델이 따를 응답 지침 |
max_output_tokens | 선택 | Integer | 추론을 포함한 최대 출력 토큰 |
reasoning | 선택 | Object | effort 등 지원 모델의 추론 설정 |
text | 선택 | Object | 출력 형식과 지원 모델의 텍스트 설정 |
tools | 선택 | Array | 함수 이름, 설명, 파라미터 스키마 |
tool_choice | 선택 | String / Object | 도구 선택 방식 |
stream | 선택 | Boolean | SSE 스트리밍 여부 |
요청 예시
json
{
"model": "gpt-5.6-sol",
"instructions": "한국어로 간결하게 답하세요.",
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "캐시 무효화가 필요한 경우를 설명해 주세요."
}
]
}
],
"reasoning": {
"effort": "low"
},
"max_output_tokens": 2048,
"stream": false
}응답 예시
json
{
"id": "resp_example",
"object": "response",
"status": "completed",
"model": "gpt-5.6-sol",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "원본 데이터가 바뀌면 캐시를 갱신하거나 무효화해야 합니다.",
"annotations":
}
]
}
],
"usage": {
"input_tokens": 24,
"output_tokens": 32,
"total_tokens": 56
}
}output에는 메시지 외에 추론과 함수 호출 항목도 들어갈 수 있습니다. 텍스트는 type=message의 content에서 type=output_text를 읽습니다.
Messages
요청 파라미터
| 파라미터 | 필수 | 타입 | 설명 |
|---|---|---|---|
model | 필수 | String | 모델 ID |
messages | 필수 | Array | user / assistant 대화 이력 |
max_tokens | 필수 | Integer | 최대 생성 토큰 |
system | 선택 | String / Array | 대화 이력과 분리된 응답 지침 |
stream | 선택 | Boolean | SSE 스트리밍 여부 |
temperature | 선택 | Number | 지원 모델의 샘플링 온도 |
top_p / top_k | 선택 | Number / Integer | 지원 모델의 샘플링 설정 |
thinking | 선택 | Object | 지원 모델의 추론 방식과 예산 |
output_config | 선택 | Object | 지원 모델의 추론 강도 등 출력 설정 |
tools | 선택 | Array | name, description, input_schema |
tool_choice | 선택 | Object | auto, any, tool 등 도구 선택 방식 |
stop_sequences | 선택 | Array | 생성을 멈출 문자열 목록 |
요청 예시
json
{
"model": "cd-sonnet-5",
"system": "한국어로 답하세요.",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "요청 시간 초과와 재시도 정책을 설명해 주세요."
}
]
}
],
"max_tokens": 2048,
"stream": false
}응답 예시
json
{
"id": "msg_example",
"type": "message",
"role": "assistant",
"model": "cd-sonnet-5",
"content": [
{
"type": "text",
"text": "시간 초과는 요청의 완료 여부가 불명확할 수 있으므로 중복 실행을 고려해 재시도해야 합니다."
}
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 24,
"output_tokens": 32
}
}추론 설정
| 프로토콜 | 설정 위치 | 예시 |
|---|---|---|
| Chat Completions | 최상위 reasoning_effort | "reasoning_effort": "high" |
| Chat Completions | 지원 모델의 thinking_enabled | "thinking_enabled": true |
| Responses | reasoning.effort | "reasoning": {"effort": "high"} |
| Messages | 모델별 thinking / output_config | Claude 문서의 버전별 설정 참조 |
추론 설정 이름과 허용값은 프로토콜과 모델 버전에 따라 다릅니다. thinking_enabled를 모든 모델에 공통으로 넣지 않습니다. 반환되는 추론 토큰은 생성 토큰 사용량에 포함됩니다.
Media Input
Chat Completions의 Part
| type | 입력 필드 | 내용 |
|---|---|---|
text | text | 질문과 지시문 |
image_url | image_url.url | 이미지 URL 또는 data URL |
video_url | video_url.url | 영상 URL |
input_audio | input_audio | 오디오 URL 또는 data / format |
file | file.file_url / file.file_data / file.file_name | 파일 URL 또는 Base64 데이터와 이름 |
미디어 지원 범위는 모델별 문서에서 확인합니다. 영상과 오디오의 지원 여부를 이미지 입력 지원 여부와 동일하게 취급하지 않습니다. 100MB를 초과하는 영상은 URL 입력을 사용합니다.
대화와 역할
system은 답변 규칙, user는 질문과 미디어, assistant는 이전 모델 응답에 사용합니다. 도구 결과는 Chat Completions의 tool, Responses의 function_call_output, Messages의 tool_result로 전달합니다.
Chat Completions 상세 필드
프로토콜의 필드 구조입니다. 모델별 지원 기능과 허용값은 해당 모델의 버전별 규격을 따릅니다.
핵심 파라미터
| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
model | 문자열 | 필수 | - | 모델 식별자입니다. 플랫폼의 기본 서비스 ID는 모델 이름과 같습니다(예: hy3, deepseek-v4-flash). 사용자 지정 서비스 형식은 ep-xxxxxxxx입니다. |
messages | 배열 | 필수 | - | 채팅 컨텍스트 메시지 배열입니다. 자세한 내용은 Messages 파라미터를 참조하세요. |
stream | 불리언 | 선택 | false | 스트리밍 출력(SSE) 활성화 여부입니다. |
stream_options | 객체 | 선택 | - | 스트리밍 옵션입니다. stream=true일 때만 적용됩니다. |
stream_options.include_usage | 불리언 | 선택 | false | 스트리밍 모드의 마지막 청크에 usage 통계를 포함할지 여부입니다. 플랫폼은 항상 사용량을 요청하며, 이 필드는 클라이언트에 전달할지 여부만 제어합니다. |
Messages 파라미터
| 필드 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
role | 문자열 | 필수 | "system"으로 고정 |
content | 문자열 | 필수 | 모델 동작과 컨텍스트를 설정하는 시스템 지침입니다. |
| 필드 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
role | 문자열 | 필수 | "user"로 고정 |
content | 문자열 또는 배열 | 필수 | 일반 텍스트는 문자열에 해당하고, 멀티모달 콘텐츠는 배열에 해당합니다(아래 Content Part 참조). |
| 필드 | 유형 | 설명 |
|---|---|---|
type | 문자열 | 콘텐츠 유형: "text" / "image_url" / "video_url" / "file_url" |
text | 문자열 | type="text"일 때의 텍스트 콘텐츠입니다. |
image_url | 객체 | type="image_url"일 때의 이미지 정보입니다. |
image_url.url | 문자열 | 이미지 HTTP(S) URL 또는 data:image/...;base64,... 형식의 Data URL |
image_url.detail | 문자열 | 이미지 해상도 정책: "auto" / "low" / "high". 기본값은 "auto"입니다. |
video_url | 객체 | type="video_url"일 때의 동영상 정보입니다. |
video_url.url | 문자열 | 동영상 HTTP(S) URL입니다. |
file_url | 객체 | type="file_url"일 때의 파일 정보입니다. |
file_url.url | 문자열 | 파일 HTTP URL입니다(직접 HTTP 링크만 지원하며 Base64는 지원하지 않음). |
| 필드 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
role | 문자열 | 필수 | "assistant"로 고정 |
content | 문자열 | 선택 | 모델 응답 텍스트입니다(tool_calls가 없으면 필수). |
reasoning_content | 문자열 | 선택 | 추론 체인 콘텐츠입니다. 사고 시 모델 응답에 반환되며, 멀티턴 대화에서 컨텍스트 연속성을 유지하려면 그대로 다시 입력해야 합니다. |
reasoning_details | 배열 | 선택 | 서명을 포함하는 추론 체인 블록 배열입니다. 멀티턴 대화에서 컨텍스트 연속성을 유지하려면 그대로 다시 전달해야 합니다. |
tool_calls | 배열 | 선택 | 도구 호출 목록입니다. 도구 호출 파라미터를 참조하세요. |
prefix | 불리언 | 선택 | 일부 DeepSeek 모델에서 지원합니다. true로 설정하면 모델은 이 메시지의 콘텐츠를 이어 쓰기용 접두사로 사용하며, 해당 Beta 엔드포인트가 필요합니다. 표준 엔드포인트에서는 이 필드가 무시되며 요청 결과에 영향을 주지 않습니다. |
| 필드 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
role | 문자열 | 필수 | "tool"로 고정 |
content | 문자열 | 필수 | 도구 함수가 반환한 결과 콘텐츠입니다(JSON 문자열 형식 권장). |
tool_call_id | 문자열 | 필수 | assistant.tool_calls.id에 대응하는 값입니다. |
name | 문자열 | 선택 | 도구 함수 이름입니다. |
생성 제어 파라미터
| 파라미터 | 타입 | 필수 | 기본값 | 값 범위 | 설명 |
|---|---|---|---|---|---|
temperature | 실수 | 선택 | 1.0 | [0.0, 2.0] | 샘플링 온도입니다. 값이 높을수록 출력이 더 무작위적이고, 낮을수록 더 결정적입니다. 일반적으로 이 파라미터와 top_p 중 하나만 조정하세요. |
top_p | 실수 | 선택 | 1.0 | (0.0, 1.0] | 핵 샘플링 확률 임계값입니다. top_p=0은 플랫폼에서 null로 정규화됩니다(기본값과 동일). |
max_tokens | 정수 | 선택 | 모델 최댓값 | ≥ 1 | 단일 응답에서 생성할 수 있는 최대 토큰 수입니다. 이 제한을 초과하면 finish_reason은 "length"입니다. |
max_completion_tokens | 정수 | 선택 | 모델 최댓값 | ≥ 1 | 생성할 수 있는 최대 토큰 수입니다(OpenAI의 새 필드이며 의미상 max_tokens와 동일). 둘 중 하나만 제공하세요. 플랫폼은 max_completion_tokens를 우선 사용합니다. |
n | 정수 | 선택 | 1 | ≥ 1 | 후보 응답 수입니다. n > 1이면 총 토큰 수를 기준으로 과금됩니다. 일부 모델은 이를 지원하지 않습니다. 추론 모드가 활성화된 경우 n은 1이어야 하며, 그렇지 않으면 400 오류가 반환됩니다. |
stop | 문자열 또는 배열 | 선택 | - | 최대 4개 | 중지 시퀀스입니다. 일치하는 시퀀스가 나타나면 생성을 즉시 중지합니다. 4개를 초과하면 검증 중 거부됩니다. |
seed | 정수 | 선택 | - | 임의의 정수 | 난수 시드입니다. 동일한 시드를 사용하면 시스템은 일관된 출력을 보장하기 위해 최선을 다합니다. |
frequency_penalty | 실수 | 선택 | 0 | [-2.0, 2.0] | 빈도 페널티입니다. 양수 값은 이미 등장한 토큰의 반복 확률을 낮춥니다. 0은 null로 정규화됩니다. |
presence_penalty | 실수 | 선택 | 0 | [-2.0, 2.0] | 존재 페널티입니다. 양수 값은 새로운 주제 생성을 장려합니다. 0은 null로 정규화됩니다. |
logprobs | 불리언 | 선택 | false | - | 출력 토큰의 로그 확률 반환 여부입니다. |
top_logprobs | 정수 | 선택 | 0 | [0, 20] | 각 위치에서 확률이 가장 높은 N개 토큰을 반환합니다. logprobs=true가 필요하며, 그렇지 않으면 검증에 실패합니다. |
reasoning_effort | 문자열 | 선택 | - | "low" / "medium" / "high" | 추론 깊이입니다. 추론 모델에 적용됩니다. Hunyuan 모델에는 내부 매핑 변환이 적용됩니다. |
응답 형식 파라미터
| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
response_format | 객체 | 선택 | {"type":"text"} | 응답 형식을 제어합니다. |
response_format.type | 문자열 | 필수 | "text" | 형식 유형: "text" / "json_object" / "json_schema". |
response_format.json_schema | 객체 | 조건부 | - | type="json_schema"일 때 필수입니다. 출력 JSON 구조를 정의합니다. |
response_format.json_schema.name | 문자열 | 필수 | - | 스키마 이름입니다. |
response_format.json_schema.schema | 객체 | 필수 | - | JSON Schema 정의입니다(JSON Schema 사양 준수). |
response_format.json_schema.strict | 불리언 | 선택 | false | 엄격한 Schema 일치 적용 여부입니다. |
도구 호출 파라미터
| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
tools | 배열 | 선택 | - | 도구 정의 목록입니다. |
tools.type | 문자열 | 필수 | - | "function"으로 고정됩니다. |
tools.function | 객체 | 필수 | - | 함수 정의입니다. |
tools.function.name | 문자열 | 필수 | - | 도구 함수 이름입니다(문자, 숫자, 밑줄, 하이픈만 포함). |
tools.function.description | 문자열 | 선택 | - | 도구 함수를 설명하여 모델이 호출 시점을 판단하도록 지원합니다. |
tools.function.parameters | 객체 | 선택 | {} | 입력 파라미터 정의입니다(JSON Schema 객체 형식). |
tool_choice | 문자열 또는 객체 | 선택 | "auto" | 도구 호출 정책입니다. 자세한 내용은 아래 열거형을 참조하세요. |
parallel_tool_calls | 불리언 | 선택 | true | 여러 도구의 병렬 호출 허용 여부입니다. |
| 값 | 설명 |
|---|---|
"none" | 도구를 호출하지 않습니다(Hunyuan 환경에서는 tools 필드도 비워짐). |
"auto" | 모델이 도구 호출 여부를 자체적으로 결정합니다(기본값). |
"required" | 모델이 하나 이상의 도구를 호출하도록 강제합니다. 참고: 사고 모드가 활성화된 경우(deepseek-v4-* 등의 모델에서는 기본 활성화), 이 값을 사용하거나 함수 객체를 지정하면 400 오류가 반환됩니다. 사용 전에 thinking: {"type": "disabled"}를 명시적으로 전달해야 합니다. |
{"type":"function","function":{"name":"xxx"}} | 호출할 도구를 지정합니다. |
사고 모드 파라미터
| 파라미터 | 타입 | 필수 | 기본값 | 설명 | 적용 모델 |
|---|---|---|---|---|---|
thinking | 객체 | 선택 | - | 사고 모드 제어(표준 방식) | 사고 모델(예: Hy 및 DeepSeek) |
thinking.type | 문자열 | 필수 | - | 활성화는 "enabled" / 비활성화는 "disabled" / 적응형 모드는 "adaptive"입니다. thinking 객체를 전달할 때 이 필드는 필수입니다. type 없이 budget_tokens만 제공하면 400 오류가 반환됩니다. | 사고 모델(thinking과 동일하며, 사용할 수 있는 구체적인 값은 모델마다 다름). |
thinking.budget_tokens | 정수 | 선택 | 8192 (자동 입력) | 추론 프로세스의 최대 토큰 수입니다. type=enabled이고 이 값을 지정하지 않으면 8192가 자동으로 입력됩니다. 이 값은 예상 상한이며 하드 제한이 아닙니다. 일부 모델의 실제 추론 토큰 수는 설정값을 초과할 수 있습니다. 정확한 추론 토큰 수는 응답의 usage.completion_tokens_details.reasoning_tokens를 참조하세요. | 사고 모델(일부 모델에서는 참고용일 뿐 엄격히 적용되지 않음). |
enable_thinking | 불리언 | 선택 | - | 사고 모드 활성화 여부입니다(간소화된 스위치). thinking.type의 대안이며 일부 모델(예: DeepSeek 시리즈)에서 사용할 수 있습니다. thinking.type을 일관되게 사용하는 것이 좋습니다. | Hy 및 DeepSeek 등의 일부 모델 |
thinking_budget | 정수 | 선택 | - | 추론 프로세스의 최대 토큰 수입니다(간소화된 필드). enable_thinking과 함께 사용해야 합니다. thinking.budget_tokens를 일관되게 사용하는 것이 좋습니다. | Hy 및 DeepSeek 등의 일부 모델 |
interleaved_thinking | 불리언 | 선택 | - | 인터리브 추론 체인 모드입니다. 추론과 출력을 동시에 수행하므로 스트리밍 표시에 적합합니다. 이 필드는 확장 기능입니다. 실제 지원 수준은 모델마다 다릅니다. 지원하지 않는 모델은 오류를 발생시키지 않고 이 필드를 무시합니다. | 일부 모델(구체적인 모델 기능 설명 기준) |
reasoning_split | 불리언 | 선택 | - | 추론 콘텐츠와 최종 답변을 별도 세그먼트로 출력합니다. 이 필드는 확장 기능입니다. 지원하지 않는 모델은 오류를 발생시키지 않고 이 필드를 무시합니다. | 일부 모델 |
캐시 파라미터
| 파라미터 | 타입 | 필수 | 기본값 | 설명 | 적용 모델 |
|---|---|---|---|---|---|
prompt_cache_key | 문자열 | 선택 | - | Prompt 캐시 키를 수동으로 지정합니다. 키가 같은 요청은 캐시를 재사용할 수 있습니다. 캐시 적중 후에는 캐시 가격을 기준으로 과금됩니다. 응답의 usage.prompt_tokens_details.cached_tokens에서 적중한 캐시 토큰 수를 확인할 수 있습니다. | Prompt Cache를 지원하는 모델 |
기타 파라미터
| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
user | 문자열 | 선택 | - | 최종 사용자 식별자입니다. 악용 감지 및 사용량 추적을 위해 모델 서비스에 그대로 전달됩니다. |
user_id | 문자열 또는 숫자 | 선택 | - | 플랫폼 비즈니스 계층의 사용자 ID입니다(숫자 유형과 호환되며 플랫폼에서 자동으로 문자열로 변환). 플랫폼 내부 사용자 식별에만 사용되며 모델 서비스에는 전달되지 않습니다. 모델 서비스에 사용자 식별자를 전달하려면 user 필드를 사용하세요. |
safety_identifier | 문자열 | 선택 | - | 보안 식별자입니다. 위험 제어 시스템에서 사용자 수준의 콘텐츠 조정 추적에 사용됩니다. |
extra_body | 객체 | 선택 | - | 플랫폼에서 구문 분석하지 않고 모델 서비스에 그대로 전달하는 추가 파라미터입니다. 일부 모델은 이 필드를 요청 본문의 최상위에 병합하지만, 다른 모델 서비스는 무시합니다. |
최상위 구조
| 필드 | 유형 | 설명 |
|---|---|---|
id | 문자열 | chatcmpl-{uuid} 형식의 고유 요청 식별자입니다(플랫폼에서 생성하며 모델 서비스가 반환한 ID와 무관). |
object | 문자열 | 객체 유형이며 "chat.completion"으로 고정됩니다. |
created | 정수 | 생성 시간입니다(Unix 타임스탬프, 초 단위). |
model | 문자열 | 사용자 요청에 전달된 원래 모델 이름입니다(모델 서비스가 실제로 사용한 모델 이름이 아님). |
choices | 배열 | 후보 결과 목록이며, 요소 수는 요청에 지정된 n과 같습니다. |
usage | 객체 | 토큰 사용량 통계입니다. 자세한 내용은 "usage" 객체를 참조하세요. |
search_info | 객체 또는 null | 웹 검색 정보입니다(Hunyuan/AISearch 경로를 사용할 때 포함되며, 그렇지 않으면 null). |
Choices 배열 요소
| 필드 | 유형 | 설명 |
|---|---|---|
index | 정수 | choices 배열 내 옵션 인덱스이며 0부터 시작합니다. |
message | 객체 | 응답 메시지 객체입니다. 자세한 내용은 message 객체를 참조하세요. |
finish_reason | 문자열 | 생성 완료 사유입니다. 아래 열거형을 참조하세요. |
logprobs | 객체 또는 null | 토큰 확률 정보입니다(요청에 logprobs=true를 설정해야 함). |
| 값 | 설명 | 처리 권장 사항 |
|---|---|---|
"stop" | 정상 종료(모델이 자체적으로 중지하거나 stop 시퀀스와 일치). | 정상적으로 처리하세요. |
"length" | max_tokens / max_completion_tokens 제한에 도달하여 출력이 잘렸습니다. | max_tokens 값을 늘리거나 콘텐츠를 여러 세그먼트로 나누어 생성하는 방안을 고려하세요. |
"tool_calls" | 모델이 도구를 호출해야 합니다. | 도구를 실행하고 결과를 tool 메시지로 포함하여 요청을 계속하세요. |
"content_filter" | 보안 정책에 의해 콘텐츠가 필터링되었습니다. | 입력 콘텐츠가 보안 규칙을 트리거하는지 확인하세요. |
| 필드 | 유형 | 설명 | 적용 시나리오 |
|---|---|---|---|
role | 문자열 | "assistant"로 고정 | 전체 |
content | 문자열 또는 null | 응답 텍스트 콘텐츠입니다. tool_calls가 있으면 null일 수 있습니다. | 전체 |
reasoning_content | 문자열 | 추론 체인/추론 프로세스 콘텐츠 | 사고 모델 |
reasoning_details | 배열 | 추론 체인 블록 배열(signature 포함) | 사고 모델 |
tool_calls | 배열 | 도구 호출 목록 | 함수 호출 |
refusal | 문자열 또는 null | 거부 사유 | 콘텐츠 보안 필터링 |
| 필드 | 유형 | 설명 |
|---|---|---|
id | 문자열 | call_{uuid} 형식의 고유 도구 호출 ID입니다. |
type | 문자열 | "function"으로 고정됩니다. |
function.name | 문자열 | 호출되는 함수의 이름입니다. |
function.arguments | 문자열 | 함수 파라미터입니다(JSON 문자열 형식이며 사용 전에 JSON.parse로 구문 분석해야 함). |
Usage 객체
| 필드 | 유형 | 설명 |
|---|---|---|
prompt_tokens | 정수 | 입력 토큰 수입니다(system, messages 및 도구 정의의 토큰 포함). |
completion_tokens | 정수 | 출력 토큰 수입니다(추론 토큰 포함). |
total_tokens | 정수 | 총 토큰 수 |
cache_read_tokens | 정수 | Prompt Cache 적중으로 읽은 토큰 수입니다(일부 모델에서 사용 가능하며 과금을 줄일 수 있음). |
cache_write_tokens | 정수 | Prompt Cache에 기록된 토큰 수입니다(일부 모델에서 사용 가능). |
prompt_tokens_details | 객체 | 입력 토큰 세부 내역입니다(일부 모델에서 사용 가능). |
prompt_tokens_details.cached_tokens | 정수 | 캐시된 토큰 수 |
completion_tokens_details | 객체 | 출력 토큰 세부 내역입니다(일부 모델에서 사용 가능). |
completion_tokens_details.reasoning_tokens | 정수 | 추론에 사용된 토큰 수입니다(OpenAI 호환 경로). |
completion_tokens_details.audio_tokens | 정수 | 오디오 출력에 사용된 토큰 수 |
| 필드 | 유형 | 설명 |
|---|---|---|
object | 문자열 | "chat.completion.chunk"로 고정됩니다. |
choices.delta | 객체 | 증분 콘텐츠입니다. |
choices.delta.role | 문자열 | 첫 번째 청크에만 나타나며 값은 "assistant"입니다. |
choices.delta.content | 문자열 | 증분 텍스트 조각이며, 누적 연결하면 완전한 응답이 됩니다. |
choices.delta.reasoning_content | 문자열 | 증분 추론 체인 조각입니다(추론 체인 모드에서 content보다 먼저 출력됨). |
choices.delta.reasoning_details | 배열 | 증분 추론 체인 블록입니다(signature 포함. 스트림 종료 후 완전히 수집하여 여러 턴에 걸쳐 반환해야 함). |
choices.delta.tool_calls | 배열 | 증분 도구 호출입니다(배열 위치를 식별하는 index 필드 포함). |
choices.delta.search_results | 배열 | 증분 웹 검색 결과입니다(일부 모델이 스트림에서 푸시). |
choices.finish_reason | 문자열 또는 null | 생성 중에는 null이며 완료 시 종료 사유로 변경됩니다. |
usage | 객체 또는 null | include_usage=true일 때 마지막 정식 청크에만 포함됩니다. |
| 시나리오 | 조치 |
|---|---|
첫 패킷 전 실패(HTTP 200 헤더가 기록되기 전) | 표준 JSON 오류 본문을 반환하며, 여기에서 오류 코드를 정상적으로 구문 분석할 수 있습니다. Fallback Provider가 구성된 경우 자동 폴백 재시도가 수행됩니다. |
200 응답 헤더 전송 후 오류 | 플랫폼이 SSE 스트림에 data: {"error":{"type":"...","message":"..."}}\\n\\n 오류 프레임을 삽입한 후 data: [DONE]\\n\\n 프레임을 전송하여 스트림을 종료합니다. 클라이언트는 delta에 error 필드가 포함되어 있는지 확인해야 합니다. |
예시: 멀티턴 사고 과정 대화(signature 포함)
Responses 상세 필드
프로토콜의 필드 구조입니다. 모델별 지원 기능과 허용값은 해당 모델의 버전별 규격을 따릅니다.
기본 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
model | 문자열 | 선택 | 응답 생성에 사용하는 모델 ID입니다(예: hy3). |
input | 문자열 또는 배열 | 선택 | 모델에 전송하는 텍스트, 이미지 또는 파일 입력입니다. 문자열은 일반 텍스트(user 역할의 텍스트와 동일)를 나타냅니다. 배열은 입력 항목 목록을 나타냅니다. 자세한 내용은 입력 유형 세부 정보를 참조하세요. |
instructions | 문자열 | 선택 | 모델 컨텍스트에 삽입되는 시스템(또는 개발자) 메시지입니다. 시스템 메시지를 previous_response_id와 함께 사용하면 이전 응답의 지침이 다음 응답으로 이어지지 않으므로 시스템 메시지를 교체할 수 있습니다. |
stream | 불리언 | 선택 | true로 설정하면 모델 응답 데이터가 SSE를 통해 스트리밍되며, 이벤트에는 response.created, response.output_text.delta, response.completed 등이 포함됩니다. |
생성 제어 파라미터
| 파라미터 | 타입 | 값 범위 | 설명 |
|---|---|---|---|
max_output_tokens | 숫자 | ≥ 1 | 응답에서 생성할 수 있는 최대 토큰 수로, 표시되는 출력 토큰과 추론 토큰을 포함합니다. 추론 모델의 추론 토큰도 이 제한에 포함됩니다. |
temperature | 숫자 | [0, 2] | 출력의 무작위성을 제어하는 샘플링 온도입니다. 값이 높을수록 출력이 더 무작위적이고 창의적이며, 낮을수록 더 집중되고 결정적입니다. |
top_p | 숫자 | (0, 1] | 핵 샘플링 파라미터입니다. 모델은 누적 확률 질량이 상위 top_p인 토큰만 고려합니다. temperature와 top_p 중 하나만 조정하는 것이 좋습니다. |
truncation | 문자열 | "auto" / "disabled" | 컨텍스트가 모델의 최대 길이를 초과할 때 적용할 잘림 정책입니다. auto는 대화 시작 부분의 항목부터 삭제하고, disabled(기본값)는 제한 초과 시 요청을 400 오류로 실패시킵니다. 세 모델 모두 이 파라미터를 허용하지만 응답 본문에는 그대로 반환하지 않습니다. |
도구 호출
| 파라미터 | 타입 | 설명 |
|---|---|---|
tools | 배열 | 모델이 응답을 생성할 때 호출할 수 있는 도구 배열입니다. 함수 호출, 파일 검색, 웹 검색 등을 지원합니다. 자세한 내용은 도구 유형 설명을 참조하세요. |
tool_choice | 문자열 또는 객체 | 모델이 도구를 선택하는 방식입니다. 구체적인 값은 아래 표를 참조하세요. |
parallel_tool_calls | 불리언 | 모델의 도구 호출 병렬 실행 허용 여부입니다. |
| 값/유형 | 설명 |
|---|---|
"none" | 모델이 도구를 호출하지 않고 메시지를 직접 생성합니다. |
"auto" | 모델이 메시지를 생성하거나 하나 이상의 도구를 호출할 수 있습니다. |
{ "type": "function", "name": "..." } | 모델이 특정 함수를 호출하도록 강제합니다. |
{ "type": "mcp", "server_label": "...", "name": "..." } | 모델이 특정 MCP 서버의 도구를 호출하도록 강제합니다. |
출력 형식 제어
| 형식 유형 | 설명 |
|---|---|
{ "type": "text" } | 텍스트 응답을 생성하는 기본 형식입니다. |
{ "type": "json_schema", "name": "...", "schema": {...} } | 모델 출력이 지정된 JSON Schema를 준수하도록 보장하는 구조화된 출력입니다. |
{ "type": "json_object" } | 출력이 유효한 JSON이 되도록 보장하는 레거시 JSON 모드입니다(새 모델에는 권장하지 않음). |
| 값 | 설명 |
|---|---|
file_search_call.results | 파일 검색 도구 호출의 검색 결과를 포함합니다. |
web_search_call.results | 웹 검색 도구 호출의 결과를 포함합니다. |
message.input_image.image_url | 입력 메시지의 이미지 URL을 포함합니다. |
code_interpreter_call.outputs | 코드 인터프리터 실행 출력을 포함합니다. |
reasoning.encrypted_content | 상태 비저장 멀티턴 대화에 사용되는 추론 토큰의 암호화된 버전을 포함합니다. |
message.output_text.logprobs | 어시스턴트 메시지의 로그 확률을 포함합니다. |
추론 제어
| 필드 | 유형 | 설명 |
|---|---|---|
effort | "none" / "low" / "medium" / "high" | 추론 노력 수준을 제한합니다. 추론 노력 수준을 낮추면 응답 시간과 추론 토큰 소비를 줄일 수 있습니다. |
summary | "auto" / "concise" / "detailed" | 디버깅 및 추론 과정 이해에 사용되는 모델 추론 과정의 요약입니다. |
기타 파라미터
| 파라미터 | 타입 | 설명 |
|---|---|---|
background | 불리언 | 백그라운드에서 비동기적으로 실행할지 여부입니다. 모든 모델이 이 파라미터를 허용하지만 실제로는 모두 동기적으로 반환합니다. |
store | 불리언 | 후속 검색을 위해 응답을 저장할지 여부입니다. 세 모델 모두 이 파라미터를 오류 없이 허용하지만 실제로 응답에는 그대로 반환하지 않습니다. |
metadata | 객체 | 응답에 첨부되는 키-값 쌍 메타데이터입니다(최대 16쌍, 키 길이 ≤ 64자, 값 길이 ≤ 512자). 세 모델 모두 이 파라미터를 허용하지만 응답 본문에는 그대로 반환하지 않습니다. |
service_tier | 문자열 | 서비스 계층: auto / default / flex / scale / priority. |
| 필드 | 유형 | 설명 |
|---|---|---|
content | 문자열 또는 배열 | 텍스트, 이미지 또는 오디오 입력이며 이전 어시스턴트 응답도 포함할 수 있습니다. |
role | "user" / "assistant" / "system" / "developer" | 메시지 역할입니다. developer 또는 system의 지침이 user의 지침보다 우선합니다. |
phase | "commentary" / "final_answer" | 선택 사항입니다. 어시스턴트 메시지를 중간 해설 또는 최종 답변으로 표시합니다. |
type | "message" | 선택 사항입니다. 메시지 입력 유형이며 항상 message입니다. |
| 필드 | 유형 | 설명 |
|---|---|---|
detail | "low" / "high" / "auto" / "original" | 이미지 세부 수준이며 기본값은 auto입니다. |
type | "input_image" | 유형이며 항상 input_image입니다. |
file_id | 문자열 | 선택 사항입니다. 파일 ID입니다. |
image_url | 문자열 | 선택 사항입니다. 이미지 URL 또는 base64로 인코딩된 데이터 URL입니다. |
| 필드 | 유형 | 설명 |
|---|---|---|
type | "input_file" | 유형이며 항상 input_file입니다. |
file_data | 문자열 | 선택 사항입니다. 파일 콘텐츠(base64 인코딩)입니다. |
file_id | 문자열 | 선택 사항입니다. 파일 ID입니다. |
file_url | 문자열 | 선택 사항입니다. 파일 URL입니다. |
filename | 문자열 | 선택 사항입니다. 파일 이름입니다. |
| 필드 | 유형 | 설명 |
|---|---|---|
type | "function" | 유형이며 항상 function입니다. |
name | 문자열 | 함수 이름 |
parameters | 객체 | 함수 파라미터를 설명하는 JSON Schema 객체입니다. |
strict | 불리언 | 엄격한 파라미터 검증 적용 여부입니다. 기본값은 true입니다. |
description | 문자열 | 선택 사항입니다. 모델이 호출 여부를 판단하는 데 사용하는 함수 설명입니다. |
| 필드 | 유형 | 설명 |
|---|---|---|
type | "file_search" | 유형이며 항상 file_search입니다. |
vector_store_ids | 문자열 배열 | 검색할 벡터 저장소 ID 목록입니다. |
max_num_results | 숫자 | 선택 사항입니다. 반환할 최대 결과 수이며 범위는 1-50입니다. |
filters | ComparisonFilter 또는 CompoundFilter | 선택 사항입니다. 필터 조건입니다. 자세한 내용은 필터 유형을 참조하세요. |
| 필드 | 유형 | 설명 |
|---|---|---|
id | 문자열 | 응답의 고유 식별자입니다. |
object | "response" | 객체 유형이며 항상 response입니다. |
created_at | 숫자 | 응답이 생성된 Unix 타임스탬프(초)입니다. |
status | 문자열 | 응답 상태: completed / incomplete / failed / in_progress / cancelled. |
completed_at | 숫자 | 응답이 완료된 Unix 타임스탬프(초)입니다. |
error | 객체 | 요청 실패 시 반환되는 오류 객체입니다. 성공적으로 완료되면 반환되지 않습니다. |
incomplete_details | 객체 | 응답이 잘린 경우의 세부 정보입니다. reason 필드는 "max_output_tokens" 또는 "content_filter"일 수 있습니다. |
instructions | 문자열 | 요청에 전달된 시스템 메시지를 변경 없이 그대로 반환합니다. |
max_output_tokens | 숫자 | 요청에 지정된 최대 출력 토큰 수입니다. 지정하지 않으면 반환되지 않습니다. |
model | 문자열 | 응답 생성에 사용된 모델 ID입니다. |
output | 배열 | 모델이 생성한 출력 항목 목록입니다. 자세한 내용은 출력 항목 유형을 참조하세요. |
parallel_tool_calls | 불리언 또는 null | 병렬 도구 호출 허용 여부입니다. |
previous_response_id | 문자열 | 멀티턴 대화에서 이전 응답의 ID입니다. 단일 턴 대화에는 반환되지 않습니다. |
usage | 객체 | 토큰 소비 통계입니다. 자세한 내용은 ResponseUsage 객체를 참조하세요. |
service_tier | 문자열 | 실제로 사용된 서비스 계층입니다. |
| 필드 | 유형 | 설명 |
|---|---|---|
input_tokens | 숫자 | 입력 토큰 수입니다. |
input_tokens_details | 객체 | cached_tokens를 포함한 입력 토큰 세부 정보 |
output_tokens | 숫자 | 출력 토큰 수입니다. |
output_tokens_details | 객체 | reasoning_tokens를 포함한 출력 토큰 세부 정보 |
total_tokens | 숫자 | 총 토큰 수(입력 + 출력)입니다. |
| 필드 | 유형 | 설명 |
|---|---|---|
id | 문자열 | 출력 메시지의 고유 ID입니다. |
type | "message" | 유형이며 항상 message입니다. |
role | "assistant" | 역할이며 항상 assistant입니다. |
status | "in_progress" / "completed" / "incomplete" | 메시지 상태입니다. |
content | 배열 | 메시지 콘텐츠 배열입니다. 각 항목에는 type: "output_text" 및 text 필드가 포함됩니다. |
| 필드 | 유형 | 설명 |
|---|---|---|
id | 문자열 | 고유 ID입니다. |
type | "function_call" | 유형이며 항상 function_call입니다. |
call_id | 문자열 | 함수 호출 ID이며 function_call_output 제출 시 반드시 전달해야 합니다. |
name | 문자열 | 호출되는 함수의 이름입니다. |
arguments | 문자열 | 함수 파라미터의 JSON 문자열입니다. |
status | 문자열 | in_progress / completed / incomplete. |
| 필드 | 유형 | 설명 |
|---|---|---|
id | 문자열 | 고유 ID입니다. |
type | "reasoning" | 유형이며 항상 reasoning입니다. |
summary | 배열 | 추론 요약 텍스트 목록입니다. 각 항목에는 type: "summary_text" 및 text 필드가 포함됩니다. |
status | 문자열 | 상태입니다. |
예시: 추론 모델
| 필드 | 유형 | 설명 |
|---|---|---|
key | 문자열 | 비교할 속성의 키 |
type | "eq" / "ne" / "gt" / "gte" / "lt" / "lte" / "in" / "nin" | 비교 연산자 |
value | 문자열 / 숫자 / 불리언 / 배열 | 비교할 값 |
| 필드 | 유형 | 설명 |
|---|---|---|
type | "and" / "or" | 연산 유형 |
filters | 배열 | 결합할 필터 배열(ComparisonFilter 또는 CompoundFilter) |
Messages 상세 필드
프로토콜의 필드 구조입니다. 모델별 지원 기능과 허용값은 해당 모델의 버전별 규격을 따릅니다.
기본 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
model | string | 필수 | 사용할 모델의 이름입니다. 예: deepseek-v4-flash. |
messages | array | 필수 | 시간순으로 정렬되고 전체 컨텍스트를 포함하는 대화 메시지 목록입니다. 플랫폼은 세션을 관리하지 않습니다. 멀티턴 대화에서는 클라이언트가 전체 기록을 전달해야 합니다. 자세한 내용은 메시지 객체 상세 정보를 참조하세요. |
system | string 또는 array | 선택 | 시스템 프롬프트입니다. messages에 포함되지 않으며 최상위 system 필드를 통해 별도로 전달됩니다. 이는 OpenAI Chat 프로토콜과의 주요 차이점입니다. |
max_tokens | integer | 필수 | 단일 모델 출력에서 생성할 수 있는 최대 토큰 수입니다. 모델마다 자체 제한이 있습니다. 추론 체인에서 소비한 토큰도 이 제한에 포함됩니다. 따라서 thinking이 활성화된 경우 이 값은 budget_tokens보다 커야 합니다. 제한에 도달하면 stop_reason은 "max_tokens"입니다. |
stream | boolean | 선택 | 스트리밍 응답 활성화 여부입니다(기본값: false). true이면 응답이 SSE 형식으로 이벤트별 반환됩니다. |
생성 제어 파라미터
| 파라미터 | 타입 | 범위 | 설명 |
|---|---|---|---|
temperature | float | [0, 1] | 샘플링 온도입니다. Anthropic의 범위는 [0, 1]이며 OpenAI의 [0, 2]와 다릅니다. |
top_p | float | (0, 1] | 누클리어스 샘플링입니다. 일반적으로 temperature와 top_p 중 하나만 조정하세요. |
top_k | integer | - | 확률이 가장 높은 상위 K개 토큰에서만 샘플링합니다. Anthropic 전용 파라미터이며 OpenAI Chat 프로토콜에는 없습니다. |
stop_sequences | string[] | - | 사용자 지정 중지 시퀀스입니다. 어떤 시퀀스든 일치하면 즉시 중지하고 stop_reason을 "stop_sequence"로 설정합니다. 일치한 시퀀스는 응답의 stop_sequence 필드에 다시 기록됩니다. |
도구 호출
| 필드 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
name | string | 필수 | 도구 이름입니다. |
description | string | 선택 | 도구의 용도를 설명하여 모델이 호출 시점을 판단하도록 지원합니다. |
input_schema | object | 필수 | JSON Schema 형식을 따르는 파라미터 정의입니다. |
type | string | 선택 | 일반 도구는 비워 두세요. 기본 제공 도구는 유형 이름을 입력하세요(예: web_search_20250305). |
max_uses | integer | 선택 | 기본 제공 도구의 세션당 최대 호출 횟수입니다. |
cache_control | object | 선택 | 도구 정의 수준의 캐시 플래그입니다. |
| Anthropic tool_choice | 동등한 OpenAI 값 | 설명 |
|---|---|---|
{"type":"auto"} | "auto" | 기본값이며 모델이 자체적으로 결정합니다. |
{"type":"any"} | "required" | 사용 가능한 도구 중 하나를 모델이 반드시 호출하도록 합니다. |
{"type":"none"} | "none" | 도구 호출을 비활성화합니다. |
{"type":"tool","name":"x"} | {"type":"function","function":{"name":"x"}} | 지정한 도구를 모델이 반드시 호출하도록 합니다. |
사고 체인(확장 thinking)
| 필드 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
type | string | 필수 | 활성화는 "enabled" / 비활성화는 "disabled" / 적응형 모드는 "adaptive"입니다. |
budget_tokens | integer | 조건부 | enabled일 때 권장됩니다. 사고 체인 토큰 예산입니다(권장 범위: 1024~32000). 값은 max_tokens보다 작아야 합니다. |
display | string | 선택 | 추론 과정 표시 방식입니다(일부 모델에서 지원). |
출력 구성
| 필드 | 유형 | 설명 |
|---|---|---|
effort | string | 출력 작업 수준: low / medium / high / xhigh / max. |
format.type | string | 구조화된 출력 유형(예: json_schema). |
format.schema | object | JSON Schema 정의입니다. |
캐싱(프롬프트 캐싱)
| 수준 | 태그 위치 | 설명 |
|---|---|---|
| 도구 수준 | tools[n].cache_control | 도구 정의 캐시 |
| 시스템 수준 | system[n].cache_control | 시스템 콘텐츠 블록 캐시 |
| 메시지/콘텐츠 블록 수준 | messages[n].content[m].cache_control | 과거 메시지 또는 콘텐츠 블록 캐시 |
메타데이터 및 서비스 수준
| 값 | 설명 |
|---|---|
auto | 자동 선택 |
standard | 표준 계층 |
priority | 우선 계층(더 높은 보장) |
batch | 배치 계층 |
요청 헤더
| 요청 헤더 | 필수 여부 | 설명 |
|---|---|---|
x-api-key | 필수 | API 키(Anthropic 공식 규칙)이며, 플랫폼은 Authorization: Bearer <key>도 지원합니다. |
anthropic-version | 필수 | API 버전이며 2023-06-01로 고정됩니다. |
content-type | 필수 | application/json |
anthropic-beta | 선택 | beta 기능 스위치(예: prompt-caching 및 interleaved-thinking)이며, 플랫폼은 이를 변경 없이 모델 서비스에 투명하게 전달합니다. |
| role | 설명 | 사용 위치 |
|---|---|---|
user | 사람 사용자의 입력(tool_result 포함) | 홀수 번째 대화 턴입니다. |
assistant | 모델의 과거 응답(text / thinking / tool_use 포함 가능) | 짝수 번째 대화 턴에 사용합니다. 멀티턴 대화에서는 과거 컨텍스트를 전달해야 합니다. |
| 블록 유형 | 주요 필드 | 적용 가능한 role | 설명 |
|---|---|---|---|
text | text,cache_control | user / assistant | 텍스트 콘텐츠 |
image | source | user | 이미지 |
video | source | user | 영상 |
document | source,title,context,citations,cache_control | user | 문서 입력 및 인용 |
search_result | source,title,content,citations | user | 검색 결과 콘텐츠 블록 |
tool_use | id,name,input | assistant | 도구 호출을 요청하는 모델 요청 |
tool_result | tool_use_id,content | user | 도구 실행 결과 |
thinking | thinking,signature | assistant | 추론 체인 콘텐츠 |
redacted_thinking | data | assistant | 편집된 추론 체인 |
source 필드 | 유형 | 설명 |
|---|---|---|
type | string | "base64" 또는 "url". |
media_type | string | base64 선택 시 필수입니다. 예: image/jpeg, image/png, image/gif 또는 image/webp. |
data | string | base64 선택 시 이미지 데이터입니다. |
url | string | url 선택 시 이미지 주소입니다. |
detail | string | 이미지 분석 상세 수준을 지정하는 low / high / auto. |
| 필드 | 유형 | 설명 |
|---|---|---|
id | string | 도구 호출의 고유 ID이며 해당 tool_result에 반환해야 합니다. |
name | string | 호출할 도구의 이름입니다. |
input | object | 도구 파라미터입니다(JSON 문자열이 아닌 객체이며 OpenAI의 arguments 문자열과 다름). |
| 필드 | 유형 | 설명 |
|---|---|---|
tool_use_id | string | tool_use.id에 해당합니다. |
content | string 또는 array | 도구 결과이며 일반 텍스트 또는 콘텐츠 블록 배열(text+image 지원)일 수 있습니다. |
is_error | boolean | 도구 실행 실패 시 true로 설정합니다. |
cache_control | object | 캐시 플래그입니다. |
| 필드 | 유형 | 설명 |
|---|---|---|
thinking | string | 모델 추론 과정의 텍스트 |
signature | string | 추론 블록의 무결성 서명 |
비스트리밍 응답
| 필드 | 유형 | 설명 |
|---|---|---|
id | string | 응답의 고유 식별자입니다(접두사 msg_). |
type | string | "message"로 고정됩니다. |
role | string | "assistant"로 고정됩니다. |
model | string | 실제로 사용된 모델의 이름입니다. |
content | array | 콘텐츠 블록 배열이며 일반적인 순서는 thinking → text → tool_use입니다. |
stop_reason | string | 중지 이유입니다. 아래 열거형을 참조하세요. |
stop_sequence | string 또는 null | 일치한 중지 시퀀스입니다(stop_sequences가 일치한 경우). |
usage | object | 토큰 사용량입니다. 토큰 사용량을 참조하세요. |
container | object | 코드 실행 컨테이너 정보(id, expires_at)입니다. 기본 제공 code_execution 도구를 사용한 경우에만 반환됩니다. |
service_tier | string | 실제로 일치한 서비스 계층입니다. |
스트리밍 응답(SSE)
| 이벤트 | 설명 | 주요 필드 |
|---|---|---|
message_start | 메시지 시작을 나타내며 초기 메시지 골격을 반환합니다. | message(초기 usage 및 input/cache 포함) |
content_block_start | 콘텐츠 블록 시작 | index 및 content_block(유형은 text/thinking/tool_use) |
content_block_delta | 콘텐츠 증분 | index 및 delta(아래 표 참조) |
content_block_stop | 콘텐츠 블록 종료 | index |
message_delta | 메시지 수준 델타 | delta.stop_reason 및 usage(최종 output_tokens) |
message_stop | 메시지 종료 | - |
| delta.type | 필드 | 의미 |
|---|---|---|
text_delta | text | 텍스트 델타입니다. |
thinking_delta | thinking | 추론 과정 델타입니다. |
signature_delta | signature | 추론 블록의 무결성 서명입니다(thinking 블록 종료 전에 전달됨). |
input_json_delta | partial_json | 도구 파라미터 JSON 조각이며 누적한 후 전체로 파싱해야 합니다. |
stop_reason 열거형
| 값 | 설명 | 권장 처리 방법 |
|---|---|---|
end_turn | 모델이 정상적으로 종료합니다. | 정상적으로 처리하세요. |
max_tokens | max_tokens 제한에 도달하여 출력이 잘렸습니다. | max_tokens 값을 늘리거나 콘텐츠를 분할하여 생성하세요. |
stop_sequence | stop_sequences가 일치했습니다. | 일치한 stop_sequence 필드를 확인하세요. |
tool_use | 모델이 도구 호출을 요청합니다. | 도구를 실행하고 tool_result를 통해 결과를 반환하여 대화를 계속하세요. |
pause_turn | 서버 도구의 장기 턴 일시 중지 | 현재 콘텐츠를 변경 없이 그대로 반환하고 요청을 계속하여 재개하세요. |
refusal | 보안상의 이유로 모델이 응답을 거부합니다. | 입력이 보안 정책을 트리거하는지 확인하세요. |
토큰 사용량
| 필드 | 유형 | 설명 |
|---|---|---|
input_tokens | integer | 순 입력 토큰(캐시 읽기/쓰기 작업 제외) |
output_tokens | integer | 출력 토큰(thinking 콘텐츠 포함) |
cache_creation_input_tokens | integer | 캐시에 기록된 토큰 수 |
cache_read_input_tokens | integer | 캐시 적중으로 읽은 토큰 수(과금이 크게 줄어듦) |
cache_creation.ephemeral_5m_input_tokens | integer | 5분 TTL 캐시 생성 토큰(TTL별 세부 내역) |
cache_creation.ephemeral_1h_input_tokens | integer | 1시간 TTL 캐시 생성 토큰(TTL별 세부 내역) |
server_tool_use.web_search_requests | integer | 기본 제공 web_search 호출 횟수 |
server_tool_use.web_fetch_requests | integer | 기본 제공 web_fetch 호출 횟수 |
service_tier | string | 실제로 일치한 서비스 계층 |
예시: 프롬프트 캐싱
응답과 실행 흐름
스트리밍
Chat Completions
stream=true를 지정하고 choices.delta.content를 순서대로 합칩니다. stream_options.include_usage=true를 사용하면 마지막 사용량 이벤트도 처리합니다.
text
data: {"choices":[{"index":0,"delta":{"content":"안녕하세요"}}]}
data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":3,"total_tokens":15}}
data: [DONE]Responses
response.output_text.delta에서 텍스트를 읽고 response.completed에서 최종 상태와 사용량을 확인합니다. 오류나 중단 이벤트도 처리합니다.
Messages
message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop 순서로 메시지를 구성합니다. 도구 입력은 텍스트 응답과 별도 블록으로 처리합니다.
SSE 이벤트 경계와 네트워크 패킷 경계는 일치하지 않습니다. 받은 데이터를 줄 단위로 누적하고 빈 줄을 이벤트 구분자로 처리합니다.
도구 호출
| 프로토콜 | 도구 선언 | 모델의 호출 | 결과 전달 |
|---|---|---|---|
| Chat Completions | tools.function.parameters | message.tool_calls | role=tool / tool_call_id |
| Responses | tools.parameters | type=function_call | type=function_call_output / call_id |
| Messages | tools.input_schema | type=tool_use | type=tool_result / tool_use_id |
도구를 선언해도 API가 사용자 함수를 실행하지는 않습니다. 애플리케이션이 함수 이름과 인수를 확인해 실행하고, 결과를 다음 요청으로 전달합니다. 모델이 반환한 서명이나 추론 블록이 필요한 후속 호출에서는 해당 필드를 보존합니다.
오류와 호출 제한
호출 제한과 오류 처리
기본 호출 범위는 30 RPM / 300K TPM입니다. 계정에 적용된 쿼터를 기준으로 동시 요청 수와 재시도 간격을 조절합니다.
| 상황 | 처리 |
|---|---|
| 인증 실패 | 키의 유효 상태와 연결된 애플리케이션 확인 |
| 잘못된 모델 / 파라미터 | 모델 ID, 프로토콜, 버전별 허용값 확인 |
| 호출 빈도 / 토큰 한도 초과 | 요청을 줄이고 간격을 두어 재시도 |
| 서버 오류 / 시간 초과 | 요청 ID를 기록하고 완료 여부와 중복 실행 가능성을 확인 |
쿼터 관리 API는 TC3 서명으로 호출합니다. Text 쿼터는 ApiToken 기준입니다. 누적 쿼터를 새로 시작하려면 기존 쿼터를 삭제하고 재생성합니다.
요청 예제
호출할 모델 또는 프로토콜의 요청 예제를 사용하십시오. 서로 다른 경로의 인증 방식과 요청 필드를 한 요청에 혼합하지 마십시오. 아래 엔진 문서와 프로토콜별 파라미터를 함께 확인하십시오.
결과·리소스 관리
사용량과 캐시
| 프로토콜 | 입력 / 출력 토큰 | 캐시 읽기 |
|---|---|---|
| Chat Completions | prompt_tokens / completion_tokens | prompt_tokens_details.cached_tokens |
| Responses | input_tokens / output_tokens | input_tokens_details.cached_tokens |
| Messages | input_tokens / output_tokens | cache_read_input_tokens |
Messages의 캐시 생성량은 cache_creation_input_tokens에서 확인합니다. 프로토콜별 사용량 필드의 의미가 다르므로 동일한 계산식에 섞지 않습니다.
통계와 로그
| API | 용도 | 제한 |
|---|---|---|
DescribeAigcUsageData | 모델별 입력 / 출력 / 캐시 입력 사용량 | 최근 365일 중 한 번에 최대 90일 |
GET /v1/statistics | 요청 수, 상태 코드, 토큰, 캐시, TTFT | 초당 2회 |
GET /v1/request-logs | 요청별 모델, 토큰, 지연, 결과 코드 | 초당 2회 / scroll_token 페이징 |
statistics는 granularity=1m, 5m, 1h를 사용합니다. 1분 / 5분 데이터는 31일, 1시간 데이터는 90일 보관됩니다. 조회의 app_id는 API 키의 소유 애플리케이션과 일치해야 합니다.