WAND wiki
최근 문서

검색 결과가 없습니다. 모델명이나 다른 키워드로 검색해 보세요.

↑ ↓ 이동 ↵ 열기전체 결과 보기 →
Multimodal UnderstandingLast Updated 2026-09-30

Multimodal Understanding API Reference

On this page

텍스트, 이미지, 영상, 오디오를 모델에 전달하고 텍스트나 구조화된 결과를 받는 VOD API입니다. VOD 애플리케이션의 SubAppId를 지정해 API 키를 먼저 발급하고, 발급된 ApiToken으로 모델을 호출합니다.

호출 규격

호출 준비

1. VOD 애플리케이션 선택

VOD에서 사용할 애플리케이션을 만들고 SubAppId를 확인합니다. 키 발급과 쿼터 관리에는 이 ID를 사용합니다. 모델 호출에는 키에 연결된 애플리케이션 정보가 적용됩니다.

2. API 키 발급

vod.intl.tencentcloudapi.com의 CreateAigcApiToken을 호출합니다. 이 단계는 Tencent Cloud SecretId와 SecretKey로 TC3 서명합니다.

LANGUAGE
{
  "SubAppId": 123456789
}

TC3 호출 스크립트를 사용하는 경우:

LANGUAGE
python3 tencent-api.py vod CreateAigcApiToken create-token.json

응답의 ApiToken을 이후 모델 요청의 Bearer 키로 사용합니다. 애플리케이션 ID나 SecretKey를 Bearer 키로 전달하지 않습니다.

3. 발급한 키로 모델 호출

LANGUAGE
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

호출 가능한 모델 조회

LANGUAGE
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

응답 예시

LANGUAGE
{
  "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 스트리밍 여부

요청 예시

LANGUAGE
{
  "model": "gpt-5.6-sol",
  "instructions": "한국어로 간결하게 답하세요.",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "캐시 무효화가 필요한 경우를 설명해 주세요."
        }
      ]
    }
  ],
  "reasoning": {
    "effort": "low"
  },
  "max_output_tokens": 2048,
  "stream": false
}

응답 예시

LANGUAGE
{
  "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 생성을 멈출 문자열 목록

요청 예시

LANGUAGE
{
  "model": "cd-sonnet-5",
  "system": "한국어로 답하세요.",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "요청 시간 초과와 재시도 정책을 설명해 주세요."
        }
      ]
    }
  ],
  "max_tokens": 2048,
  "stream": false
}

응답 예시

LANGUAGE
{
  "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를 사용하면 마지막 사용량 이벤트도 처리합니다.

LANGUAGE
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 키의 소유 애플리케이션과 일치해야 합니다.

Contact us about WAND