--- title: "Chat Completions 대화 인터페이스" description: "POST /v1/chat/completions의 최소 요청, 자주 사용하는 필드, 응답 읽기 및 다중 턴 대화 작성 방법." headingIds: {"최소 요청":"section-1","자주 사용하는 필드":"section-2","응답 읽기":"section-3","다중 턴 대화":"section-4","스트리밍 및 다음 단계":"section-5"} --- OpenAI 호환 클라이언트를 사용하거나 이미 `chat.completions.create` 코드가 있는 경우, 이 인터페이스부터 시작하세요. 전체 주소는 `https://1zheai.com/v1/chat/completions`이며, SDK의 Base URL은 `/v1`까지만 입력합니다. ## 최소 요청 먼저 터미널에서 `ONEZHE_API_KEY`을 사이트 키로 설정하세요. 아래 모델은 [사용 가능한 모델 목록](/ko/docs/api-models/)에 존재해야 합니다. ```bash curl --fail-with-body --connect-timeout 10 --max-time 120 \ https://1zheai.com/v1/chat/completions \ -H "Authorization: Bearer $ONEZHE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.6-sol", "messages": [{"role": "user", "content": "请用一句中文解释 DNS 的作用。"}] }' ``` `--fail-with-body`은 HTTP 오류에 대해 0이 아닌 종료 코드를 반환하면서 오류 본문을 유지합니다. curl 7.76 이상이 필요합니다. 이전 버전에서는 먼저 `-i`로 상태 코드를 확인할 수 있습니다. ## 자주 사용하는 필드 | 필드 | 유형 | 사용 방법 | | --- | --- | --- | | `model` | string | 필수, 사이트 모델 ID를 복사하여 다른 플랫폼의 공급자 접두사를 추가하지 않습니다 | | `messages` | array | 필수, 이번 턴의 질문과 보존할 필요가 있는 히스토리 메시지를 순서대로 전송합니다 | | `messages[].role` | string | 일반 대화에는 `user` / `assistant`를 사용합니다. 시스템 지시 역할의 지원 여부는 모델에 따라 다릅니다 | | `messages[].content` | string 또는 내용 블록 배열 | 순수 텍스트는 먼저 문자열을 사용합니다. 이미지 입력은 모델이 해당 내용 블록을 지원해야 합니다 | | `stream` | boolean | `true`로 설정하면 SSE를 읽으며, 응답 전체를 하나의 JSON으로 취급하지 않습니다 | | `temperature` | number | 선택 사항, 일부 추론 모델은 수정을 지원하지 않습니다. 먼저 생략한 뒤 항목별로 검증하세요 | | `tools` / `tool_choice` | array / string 또는 object | 선택 사항, 모델과 업스트림 모두 지원해야 합니다. 도구의 실제 실행은 프로그램에서 수행합니다 | 출력 상한 매개변수는 모델에 따라 다릅니다. Claude의 `max_tokens`, Responses의 `max_output_tokens`, Chat Completions의 매개변수를 기계적으로 서로 교환하지 마세요. 선택한 모델의 요구 사항을 참고하고, 400 오류가 발생하면 먼저 오류 본문을 확인하세요. ## 응답 읽기 일반 텍스트 결과는 `choices[0].message.content`에 있습니다. 종료 원인은 `choices[0].finish_reason`에 있으며, 도구 호출이 반환되면 텍스트가 비어 있을 수 있으므로 `message.tool_calls`을 읽어야 합니다. 응답의 `id`, `model`, `usage`는 이번 호출을 확인하는 데 사용할 수 있습니다. 아래는 주의해야 할 구조만 표시하며, 생략된 필드와 숫자는 실제 요청 결과를 나타내지 않습니다: ```json { "id": "example-completion", "object": "chat.completion", "model": "gpt-5.6-sol", "choices": [{ "index": 0, "message": {"role": "assistant", "content": "DNS 将域名解析为网络地址。"}, "finish_reason": "stop" }] } ``` ## 다중 턴 대화 인터페이스는 동일한 키를 반복 사용한다고 해서 이전 턴을 자동으로 기억하지 않습니다. 보존할 히스토리를 함께 전송하세요: ```json { "model": "gpt-5.6-sol", "messages": [ {"role": "user", "content": "我正在学习 DNS。"}, {"role": "assistant", "content": "我们可以从域名解析开始。"}, {"role": "user", "content": "它和 HTTP 有什么区别？"} ] } ``` 히스토리가 길수록 요청이 커집니다. 애플리케이션은 컨텍스트 제한에 따라 잘라내거나 요약하고, 도구 호출과 결과의 완전한 쌍을 유지해야 합니다. ## 스트리밍 및 다음 단계 `"stream": true`를 추가하면 텍스트 증분은 `choices[].delta.content`에서 옵니다. 일부 이벤트에는 텍스트가 없거나 `choices`이 비어 있을 수 있으므로 읽을 때 판단이 필요합니다. 자세한 내용은 [스트리밍 출력](/ko/docs/streaming/)을 참조하세요. [Python / Node.js 전체 예제](/ko/docs/code-examples/)을 직접 실행하거나, [Responses](/ko/docs/api-responses/)로 전환할 수 있습니다. Claude 네이티브 매개변수는 [Messages](/ko/docs/api-messages/)을 참조하세요.