OpenAI 호환 모드: 응답 처리

호환 모드를 호출하면 OpenAI, Claude, Gemini, Grok, Qwen, GLM 등 모든 모델이 동일한 OpenAI 스키마를 반환합니다. 파싱 로직의 거의 전부를 공유할 수 있습니다: 아래 패턴을 따르면 모델을 바꿔도 코드 변경이 필요하지 않습니다. 이 페이지는 응답 처리를 처음부터 올바르게 설정하는 데 도움이 됩니다. 공통 사항을 먼저 설명한 다음, 반드시 허용해야 하는 몇 가지 차이만 담은 단일 표를 제공합니다. 그중 어느 것도 통합을 막지는 않습니다.

요청 측(base_url, auth, 모델 전환)은 Compatible Mode Calls에서 다룹니다. 이 페이지는 오직 응답 측만 다룹니다: 반환되는 내용을 어떻게 파싱하는지에 관한 설명입니다.

두 가지 모드, 하나의 엔드포인트

동일한 /v1/chat/completions 엔드포인트이며, stream 플래그만 형식을 바꿉니다:

	`stream: false` (기본값)	`stream: true`
형식	단일 JSON 객체	SSE 스트림(여러 `data:` 줄)
최상위 타입	`chat.completion`	`chat.completion.chunk`
텍스트 가져오기	`choices[0].message.content`	각 `choices[0].delta.content`을 누적합니다
사용 사례	백엔드, 배치 작업, 전체 결과	채팅 UI, token 단위 렌더링

비스트리밍 응답

안정적인 구조입니다 — choices[0].message.content만 읽으면 됩니다:

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "gpt-4.1-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "1+1 equals 2." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 31, "completion_tokens": 8, "total_tokens": 39 }
}

resp = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "What is 1+1?"}]
)
print(resp.choices[0].message.content)
print(resp.usage.total_tokens)

const resp = await openai.chat.completions.create({
  model: 'gpt-4.1-mini',
  messages: [{ role: 'user', content: 'What is 1+1?' }]
});
console.log(resp.choices[0].message.content);
console.log(resp.usage.total_tokens);

curl https://api.apiyi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"model":"gpt-4.1-mini","messages":[{"role":"user","content":"What is 1+1?"}]}'

비스트리밍 출력은 모든 주요 모델에서 매우 일관적입니다 — choices[0].message.content는 어디서나 작동합니다. 일부 모델(예: OpenAI 계열)은 message에서 annotations와 refusal도 추가합니다. 필요하면 읽고, 그렇지 않으면 무시하면 됩니다.

스트리밍 응답 (SSE)

스트리밍은 청크를 Server-Sent Events로 한 줄에 하나씩 data: {...} 형태로 전송하며, data: [DONE]로 끝납니다:

data: {"choices":[{"delta":{"content":"1"},"index":0}], ...}
data: {"choices":[{"delta":{"content":"+1"},"index":0}], ...}
data: {"choices":[{"delta":{},"finish_reason":"stop","index":0}], ...}
data: [DONE]

공식 SDK에서는 그냥 순회하기만 하면 됩니다. 핵심은 delta.content를 누적하는 것입니다:

stream = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "Write a short poem"}],
    stream=True
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

const stream = await openai.chat.completions.create({
  model: 'gpt-4.1-mini',
  messages: [{ role: 'user', content: 'Write a short poem' }],
  stream: true
});

for await (const chunk of stream) {
  const delta = chunk.choices?.[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
}

통합 참고 사항: 몇 가지 차이는 있지만, 일관되게 처리할 수 있습니다

모델마다 스트리밍 세부 사항은 조금씩 다르지만, 아래 규칙을 따르면 하나의 코드 경로로 모두 처리할 수 있습니다.

최종 청크의 choices는 빈 배열일 수 있습니다. usage를 담는 마지막 청크는 일부 모델(gpt-4.1-mini, grok, qwen, glm)에서는 "choices":[]입니다. 그곳에서 choices[0]를 인덱싱하면 예외가 발생합니다. 읽기 전에 choices가 비어 있지 않은지 확인하십시오.

차이점	보이는 현상	일관된 처리
최종 청크의 choices	`[]`가 비어 있거나 비어 있지 않을 수 있습니다	delta를 읽기 전에 `choices`가 비어 있지 않은지 확인합니다
`finish_reason` 중간값	일반적으로 `null`입니다. Claude는 `""`(빈 문자열)을 사용합니다	`finish_reason === "stop"`로 종료를 감지합니다
`usage` 위치	빈 choices 청크 / 비어 있지 않은 청크 / `stop`와 같은 청크	세 가지를 모두 시도하고, 있을 때마다 기록합니다
청크 단위	토큰 단위(OpenAI) 또는 문장 단위(Gemini/Claude)	무관합니다 — 그냥 누적하면 됩니다
첫 번째 역할 선언 청크	일부는 `role`를 선언하는 내용이 비어 있는 청크를 보냅니다	내용이 비어 있으면 건너뛰고, 텍스트로 취급하지 마십시오
공급업체 전용 필드	`obfuscation`, `system_fingerprint`, `first_token_return_time` 등	무시하십시오 — 절대 의존하지 마십시오

견고한 참조 파서

원시 SSE를 직접 처리할 때(SDK를 사용하지 않을 때), 이는 위의 모든 차이를 포괄합니다:

import json, requests

def stream_chat(model, messages, api_key):
    resp = requests.post(
        "https://api.apiyi.com/v1/chat/completions",
        headers={"Authorization": f"Bearer {api_key}",
                 "Content-Type": "application/json"},
        json={"model": model, "messages": messages, "stream": True},
        stream=True, timeout=300,
    )
    text, usage = "", None
    for line in resp.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data: "):
            continue
        data = line[6:]
        if data == "[DONE]":
            break
        chunk = json.loads(data)
        if chunk.get("usage"):          # usage may appear in any chunk
            usage = chunk["usage"]
        choices = chunk.get("choices")
        if not choices:                 # final chunk may be empty; guard it
            continue
        delta = choices[0].get("delta", {})
        piece = delta.get("content")
        if piece:                       # skip role-only / empty-content chunks
            text += piece
            print(piece, end="", flush=True)
        # finish_reason == "stop" is just a marker; don't break (usage often follows)
    return text, usage

async function streamChat(model, messages, apiKey) {
  const resp = await fetch("https://api.apiyi.com/v1/chat/completions", {
    method: "POST",
    headers: { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json" },
    body: JSON.stringify({ model, messages, stream: true }),
  });

  const reader = resp.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "", text = "", usage = null;

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split("\n");
    buffer = lines.pop();             // keep the possibly-incomplete last line

    for (const line of lines) {
      if (!line.startsWith("data: ")) continue;
      const data = line.slice(6).trim();
      if (data === "[DONE]") return { text, usage };
      const chunk = JSON.parse(data);
      if (chunk.usage) usage = chunk.usage;        // usage may appear in any chunk
      const choices = chunk.choices;
      if (!choices || choices.length === 0) continue;  // final chunk may be empty
      const piece = choices[0].delta?.content;
      if (piece) { text += piece; process.stdout.write(piece); }
    }
  }
  return { text, usage };
}

추론 모델(grok, qwen, glm 등)은 먼저 delta.reasoning_content(사고의 흐름)를 스트리밍하고, 그다음 delta.content(답변)을 스트리밍합니다. 위의 파서는 content만 읽으므로, 추론 과정은 자동으로 건너뜁니다. 추론 과정을 표시하려면 추론 모델 출력을 참조하십시오.

사용 및 과금

usage는 비스트리밍 응답에서는 인라인으로 반환되며, 스트리밍에서는 후행 청크로 도착합니다(위 표의 위치 — “존재할 때마다 기록”).
필드 구성은 다릅니다: OpenAI 계열은 completion_tokens_details를 추가하고, Gemini/Claude는 input_tokens/output_tokens를 추가하며, 추론 모델은 reasoning_tokens를 추가합니다. 세 가지 표준 필드인 prompt_tokens / completion_tokens / total_tokens를 기준으로 삼으십시오.

스트리밍된 total_tokens를 믿지 마십시오. 테스트에서 일부 모델(예: gpt-5.4-mini)은 total ≠ prompt + completion인 후행 프레임을 내보내지만, 같은 모델은 비스트리밍에서는 올바릅니다. 과금은 스트리밍된 프레임이 아니라 계정 명세서를 기준으로 하십시오.

기초

기본 API

이미지 API (공식)

동영상 API (공식)

멀티모달 이해 API

텍스트 API

OpenAI 호환 모드: 응답 처리

두 가지 모드, 하나의 엔드포인트

비스트리밍 응답

스트리밍 응답 (SSE)

통합 참고 사항: 몇 가지 차이는 있지만, 일관되게 처리할 수 있습니다

견고한 참조 파서

사용 및 과금

관련 링크

​두 가지 모드, 하나의 엔드포인트

​비스트리밍 응답

​스트리밍 응답 (SSE)

​통합 참고 사항: 몇 가지 차이는 있지만, 일관되게 처리할 수 있습니다

​견고한 참조 파서

​사용 및 과금

​관련 링크

두 가지 모드, 하나의 엔드포인트

비스트리밍 응답

스트리밍 응답 (SSE)

통합 참고 사항: 몇 가지 차이는 있지만, 일관되게 처리할 수 있습니다

견고한 참조 파서

사용 및 과금

관련 링크