Chat Completions 대화 인터페이스

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

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

OpenAI 호환 클라이언트를 사용하거나 이미 chat.completions.create 코드가 있는 경우, 이 인터페이스부터 시작하세요. 전체 주소는 https://1zheai.com/v1/chat/completions이며, SDK의 Base URL은 /v1까지만 입력합니다.

최소 요청

먼저 터미널에서 ONEZHE_API_KEY을 사이트 키로 설정하세요. 아래 모델은 사용 가능한 모델 목록에 존재해야 합니다.

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이 비어 있을 수 있으므로 읽을 때 판단이 필요합니다. 자세한 내용은 스트리밍 출력을 참조하세요.

Python / Node.js 전체 예제을 직접 실행하거나, Responses로 전환할 수 있습니다. Claude 네이티브 매개변수는 Messages을 참조하세요.