개발자를 위한 Realtime API 업데이트 노트

최근 발표에서 최신 음성-음성 변환 모델인 gpt-realtime을 소개하고 Realtime API의 정식 출시와 여러 API 신기능을 알렸습니다. Realtime API와 음성-음성 변환(s2s) 모델이 정식 출시(GA)되면서 모델 품질과 안정성이 크게 개선되었고, 개발자도 API를 더 편리하게 사용할 수 있게 되었습니다.

새로운 API 기능은 문서와 API 레퍼런스에서 확인할 수 있습니다. 이 글에서는 놓치기 쉬운 기능 몇 가지를 살펴보고 언제 사용하면 좋을지 설명합니다. Realtime API를 연동하는 분들께 도움이 되길 바랍니다.

모델 개선 사항

새 모델에서는 프로덕션 환경의 음성 앱을 더 잘 지원하기 위해 여러 부분을 개선했습니다. 이 글에서는 API 변경 사항을 중심으로 다룹니다. 모델을 더 잘 이해하고 활용하려면 출시 발표 글과 실시간 모델 프롬프팅 가이드를 참고하세요. 여기서는 모델 사용 시 알아둘 몇 가지 사항을 짚어보겠습니다.

새 모델을 사용할 때는 다음 사항을 참고하세요.

• 실시간 Playground에서 다양한 프롬프트를 시험해 보세요.
• 어시스턴트의 음성 품질을 최대한 높이려면 marin 또는 cedar 음성을 사용하세요.
• 새 모델에 맞게 프롬프트를 다시 작성하세요. 모델이 지시를 더 잘 따르게 되면서 구체적인 지시가 응답에 미치는 영향도 훨씬 커졌습니다.
  • 예를 들어 이전 모델은 “Y일 때는 항상 X라고 말하세요”라는 지시를 대략적인 지침으로 받아들였을 수 있지만, 새 모델은 예상치 못한 상황에서도 그대로 따를 수 있습니다.
  • 모델이 지시를 그대로 따른다고 가정하고, 어떤 지시를 내리는지 세심하게 살펴보세요.

API 인터페이스 변경 사항

정식 출시에 맞춰 Realtime API의 인터페이스를 변경했습니다. 현재는 베타 인터페이스와 GA 인터페이스가 모두 제공됩니다. 새 기능을 활용하려면 클라이언트를 GA 인터페이스로 마이그레이션하는 것이 좋습니다. 베타 인터페이스는 향후 사용 중단 예정(deprecated) 상태로 전환됩니다.

마이그레이션에 필요한 전체 변경 사항은 베타에서 GA로 마이그레이션하는 방법에서 확인할 수 있습니다.

베타 인터페이스에서도 새 gpt-realtime 모델을 사용할 수 있지만, 일부 기능은 지원되지 않을 수 있습니다. 자세한 내용은 아래를 참고하세요.

기능별 지원 여부

Realtime API 정식 버전에는 여러 기능이 추가되었습니다. 이전 모델에서는 그중 일부만 사용할 수 있습니다.

*베타 모델은 비동기 함수 호출을 지원하지 않아 아직 결과가 반환되지 않은 MCP 도구 호출을 제대로 처리하지 못할 수 있습니다. MCP를 사용할 때는 GA 모델을 권장합니다.

temperature 변경 사항

GA 인터페이스에서는 모델 매개변수 temperature를 제거했습니다. 베타 인터페이스에서 temperature의 설정 범위는 0.6 - 1.2이고 기본값은 0.8입니다.

“동일한 입력에 더 일관된 응답을 얻고 싶을 때 temperature를 원하는 값으로 설정하면 안 될까요?”라는 의문이 들 수 있습니다. 이 모델 아키텍처에서는 temperature가 다르게 작동하기 때문에 거의 모든 경우에 권장값인 0.8을 사용하는 편이 가장 좋습니다.

지금까지 관찰한 바로는 temperature를 낮춰도 동일한 입력에 항상 동일한 오디오 응답이 나오게 할 수는 없었고, 값을 높이면 오디오에 이상이 생겼습니다. 이런 모델 동작을 조정하려면 프롬프트를 바꿔 가며 시험해 보세요.

새로운 기능

베타에서 GA로 전환하면서 인터페이스를 변경한 것 외에도 Realtime API에 몇 가지 기능을 추가했습니다.

전체 기능은 문서와 API 레퍼런스에서 확인할 수 있습니다. 여기서는 API를 연동하거나 마이그레이션할 때 새 기능을 어떻게 활용할 수 있는지 살펴보겠습니다.

대화 중 유휴 시간 초과

앱에 따라서는 사용자 입력이 한동안 없으면 상황을 확인해야 합니다. 전화 통화 중 상대방의 목소리가 한참 들리지 않으면 무슨 일이 있는지 물어보는 것과 같습니다. 모델이 사용자의 말을 놓쳤을 수도 있고, 사용자가 모델의 말이 끝났는지 몰라 기다리고 있을 수도 있습니다. 이런 경우 모델이 “아직 듣고 계신가요?”와 같은 질문을 자동으로 하도록 하는 기능을 추가했습니다.

이 기능을 켜려면 idle_timeout_ms 값을 턴 감지용 server_vad 설정에 지정하세요. 유휴 시간은 모델의 마지막 응답 오디오 재생이 끝난 뒤부터 계산합니다. 즉, 시간 초과 시점은 response.done 이벤트가 발생한 시각에 오디오 재생 시간과 설정한 유휴 시간을 더한 시각입니다. 이 기간에 음성 활동 감지(VAD)가 음성을 감지하지 않으면 시간 초과가 발생합니다.

시간이 초과되면 서버가 input_audio_buffer.timeout_triggered 이벤트를 보냅니다. 그러면 빈 오디오 구간이 대화 기록에 추가되고 모델이 응답을 생성합니다. 빈 오디오 구간을 기록하면 해당 시간에 사용자가 말했지만 VAD가 이를 감지하지 못한 것은 아닌지 모델이 확인할 수 있습니다.

클라이언트에서는 다음과 같이 이 기능을 켤 수 있습니다.

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "You are a helpful assistant.",
    "audio": {
      "input": {
        "turn_detection": {
          "type": "server_vad",
          "idle_timeout_ms": 6000
        }
      }
    }
  }
}

긴 대화와 컨텍스트 처리

Realtime API가 긴 세션을 처리하는 방식을 조정했습니다. 다음 사항을 참고하세요.

• 실시간 세션의 최대 길이가 30분에서 60분으로 늘어났습니다.
• gpt-realtime 모델의 컨텍스트 윈도우는 32,768토큰입니다. 응답 하나에 최대 4,096토큰을 사용할 수 있으므로 모델의 최대 입력 길이는 28,672토큰입니다.
• 세션 지시와 도구를 합친 길이는 최대 16,384토큰입니다.
• 세션이 28,672토큰에 도달하면 서비스가 자동으로 메시지를 잘라냅니다. 이 동작은 설정에서 조정할 수 있습니다.
• GA 버전에서는 전사 텍스트가 있으면 토큰을 절약하기 위해 일부 오디오 토큰을 자동으로 제거합니다.

메시지 잘라내기 설정

대화의 컨텍스트 윈도우가 토큰 한도에 도달하면 Realtime API는 세션 시작 부분에 있는 가장 오래된 메시지부터 자동으로 잘라냅니다. "truncation": "disabled"를 설정하면 이 동작을 끌 수 있습니다. 이 경우 응답을 생성하는 데 필요한 입력 토큰이 너무 많으면 오류가 발생합니다. 메시지 잘라내기를 사용하면 입력이 모델의 한도를 초과해도 세션을 이어갈 수 있습니다. Realtime API는 잘라낸 메시지에 대해 요약이나 컨텍스트 압축을 수행하지 않지만, 필요한 경우 직접 구현할 수 있습니다.

메시지를 잘라내면 대화의 시작 부분이 바뀌어 토큰 단위 프롬프트 캐싱의 효과가 떨어집니다. 프롬프트 캐싱은 프롬프트의 시작 부분에서 내용이 정확히 일치하는 구간을 찾는 방식으로 작동합니다. 이후 각 턴에서는 변경되지 않은 토큰만 캐싱됩니다. 메시지를 잘라내 대화의 시작 부분이 달라지면 캐싱할 수 있는 토큰 수도 줄어듭니다.

이를 완화하기 위해 메시지를 잘라낼 때 필요한 최소량보다 더 많이 제거하는 기능을 추가했습니다. 유지 비율을 0.8로 설정하면 입력 토큰 수가 한도 아래로 내려갈 만큼만 잘라내는 대신 컨텍스트 윈도우의 20%를 잘라냅니다. 매번 조금씩 잘라내는 대신 컨텍스트를 더 많이 한 번에 잘라내면 캐시가 무효화되는 빈도를 줄일 수 있습니다. 이렇게 캐시를 더 오래 활용하면 입력 한도에 도달하는 긴 세션에서도 비용을 낮게 유지할 수 있습니다.

{
  "type": "session.update",
  "session": {
    "truncation": {
      "type": "retention_ratio",
      "retention_ratio": 0.8
    }
  }
}

비동기 함수 호출

Responses API에서는 함수를 호출한 직후에 함수 응답을 제공해야 하지만, Realtime API에서는 클라이언트가 함수 응답을 기다리는 동안에도 세션을 이어갈 수 있습니다. 실시간 대화가 자연스럽게 이어져 사용자 경험이 좋아지는 반면, 모델이 간혹 아직 받지 않은 함수 응답의 내용을 지어내기도 합니다.

이 문제를 완화하기 위해 GA 버전의 Responses API에는 함수 응답을 기다리는 동안 사용할 임시 응답이 추가되었습니다. 모델이 대기 중에도 자연스럽게 대응하도록 실험을 통해 임시 응답의 내용을 평가하고 조정했습니다. 함수 호출 결과를 물으면 모델은 “아직 결과를 기다리고 있습니다”와 같이 답합니다. 새 모델에는 이 기능이 자동으로 적용되므로 별도로 변경할 사항은 없습니다.

EU 데이터 레지던시

이제 gpt-realtime-2025-08-28과 gpt-4o-realtime-preview-2025-06-03에서 EU 데이터 레지던시를 지원합니다. 데이터 레지던시를 사용하려면 조직 단위로 명시적으로 활성화하고 https://eu.api.openai.com으로 접속해야 합니다.

트레이싱

Realtime API는 실시간 세션 중 발생한 주요 이벤트를 개발자 콘솔에 트레이스로 기록합니다. 이 기록은 문제 조사와 디버깅에 활용할 수 있습니다. 정식 출시와 함께 다음 이벤트 유형을 추가했습니다.

• 세션 업데이트(session.updated 이벤트가 클라이언트에 전송될 때)
• 출력 텍스트 생성(모델이 텍스트를 생성할 때)

호스팅된 프롬프트

이제 Realtime API에서 프롬프트를 사용하면 애플리케이션 코드에서 프롬프트를 참조하고 프롬프트 자체는 별도로 편집할 수 있습니다. 프롬프트에는 지시뿐 아니라 턴 감지 설정과 같은 세션 구성도 포함됩니다.

실시간 Playground에서 프롬프트를 만들고 필요에 따라 수정하면서 버전을 관리할 수 있습니다. 그런 다음 클라이언트에서 아래와 같이 ID로 해당 프롬프트를 참조하세요.

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {
      "id": "pmpt_123", // your stored prompt ID
      "version": "89", // optional: pin a specific version
      "variables": {
        "city": "Paris" // example variable used by your prompt
      }
    },
    // You can still set direct session fields; these override prompt fields if they overlap:
    "instructions": "Speak clearly and briefly. Confirm understanding before taking actions."
  }
}

위 예시처럼 프롬프트 설정과 세션에 직접 전달한 설정이 겹치면 세션 설정이 우선합니다. 따라서 클라이언트는 프롬프트에 저장된 설정을 그대로 사용하거나 세션 중에 조정할 수 있습니다.

사이드밴드 연결

Realtime API에서는 클라이언트가 WebRTC나 SIP로 API 서버에 직접 연결할 수 있습니다. 다만 도구 사용과 기타 비즈니스 로직은 애플리케이션 서버에서 처리하는 편이 적합한 경우가 많습니다. 이렇게 하면 로직을 외부에 노출하지 않고 클라이언트에 종속되지 않도록 할 수 있습니다.

사이드밴드 제어 채널로 연결하면 도구 사용, 비즈니스 로직, 기타 세부 사항을 서버 측에서 안전하게 관리할 수 있습니다. 이제 SIP와 WebRTC 연결 모두에서 사이드밴드를 지원합니다.

사이드밴드 연결을 사용하면 동일한 실시간 세션에 두 연결이 동시에 유지됩니다. 하나는 사용자의 클라이언트에서, 다른 하나는 애플리케이션 서버에서 연결합니다. 서버 연결을 통해 세션을 모니터링하고, 지시를 업데이트하고, 도구 호출에 응답할 수 있습니다.

자세한 내용은 사이드밴드 연결 문서를 참고하세요.

개발 시작하기

이 글이 Realtime API 정식 버전과 새로운 실시간 모델에서 달라진 점을 이해하는 데 도움이 되었기를 바랍니다.

이제 Realtime API 문서를 참고해 음성 에이전트를 만들거나, 연결을 설정하거나, 실시간 모델에 프롬프트를 입력해 보세요.