스트리밍 출력

1ZheAI가 관리하는 문서입니다. 출처 및 수정 사항.

오류를 발견하셨나요? 페이지 주소와 설명을 첨부하여 고객 지원으로 문의해 주세요. API 키나 계정 정보는 보내지 마세요.

긴 답변은 스트리밍 출력("stream": true)을 사용하면 첫 글자가 더 빨리 나오고, 단일 요청 시간이 너무 길어 중간 네트워크에서 끊기는 일도 줄어듭니다. 두 프로토콜 모두 지원되며 형식은 각각 공식과 일치합니다.

Anthropic 네이티브

요청에 "stream": true을 추가하면 Server-Sent Events가 반환됩니다. 정상적인 스트림은 다음 순서로 진행됩니다(Anthropic Streaming 문서 참조):

이벤트	의미
message_start	메시지 시작, 모델과 초기 usage 포함
content_block_start	콘텐츠 블록 시작(텍스트, thinking, tool_use)
content_block_delta	콘텐츠 증분, 텍스트는 delta.text에 있음
content_block_stop	해당 콘텐츠 블록 종료
message_delta	메시지 수준 업데이트, stop_reason과 최종 출력 토큰 수 포함
message_stop	전체 메시지 종료

중간에 ping 이벤트가 끼어들 수 있으며 무시하면 됩니다. 오류 발생 시 error 이벤트를 받게 됩니다.

bash

curl -N https://1zheai.com/v1/messages \
  -H "x-api-key: $ONEZHE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":128,"stream":true,
       "messages":[{"role":"user","content":"从一数到五"}]}'

SDK를 사용하면 이벤트를 직접 파싱할 필요가 없습니다. Anthropic SDK의 스트리밍 예제를 참조하세요.

OpenAI 호환

/v1/chat/completions에 "stream": true을 추가하면 data: {...} 형식의 chunk가 반환되며, 텍스트는 choices[0].delta.content에 있고 마지막은 data: [DONE]으로 끝납니다. SDK 예제는 OpenAI SDK을 참조하세요.

usage이 붙은 마지막 chunk는 [DONE] 이전에 오며, choices는 빈 배열입니다. stream_options.include_usage을 전달하지 않아도 반환됩니다. 2026-10-15에 실측한 전체 스트림:

text

data: {"id":"msg_011Cg3ERqM8nN58LxLt7TVuG","object":"chat.completion.chunk","created":1792031230,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"msg_011Cg3ERqM8nN58LxLt7TVuG","object":"chat.completion.chunk","created":1792031230,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"content":"ok"},"finish_reason":null}]}

data: {"id":"msg_011Cg3ERqM8nN58LxLt7TVuG","object":"chat.completion.chunk","created":1792031230,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"content":""},"finish_reason":"stop"}]}

data: {"id":"msg_011Cg3ERqM8nN58LxLt7TVuG","object":"chat.completion.chunk","created":1792031230,"model":"claude-sonnet-4-6","choices":[],"usage":{"prompt_tokens":370,"completion_tokens":4,"total_tokens":374}}

data: [DONE]

chunk를 처리할 때는 먼저 choices이 비어 있는지 확인하세요. 위의 OpenAI SDK 페이지 예제는 이미 이렇게 작성되어 있습니다.

스트림이 끊겼을 때

• 먼저 프록시 여부를 확인하세요: 프록시를 끄고 직접 연결해 다시 시도합니다.
• 클라이언트의 읽기 타임아웃은 모델 생성 시간보다 길어야 합니다. 긴 출력일 때는 타임아웃 설정을 늘리세요.
• error 이벤트의 overloaded_error을 받으면 몇 초 후 재시도하세요. 오류 코드와 문제 해결을 참조하세요.

중간에 끊겼을 때의 과금

중간에 끊긴 요청이 전액 무료인 것은 아닙니다. 끊기기 전에 이미 생성된 출력 토큰 기준으로 과금되며 호출 로그에 기록됩니다. 과금되는 출력은 클라이언트가 실제로 받은 것보다 약간 더 많을 수 있습니다. 2026-10-15에 실측한 결과, 모델이 1부터 600까지 세도록 하고 클라이언트가 4초에 끊었을 때 188줄(약 380개 출력 토큰)을 받았고, 호출 로그에 기록된 출력은 750 토큰이었습니다. 필요 없는 긴 출력은 중간에 끊는 것보다 처음부터 max_tokens을 작게 설정하는 편이 낫습니다.