Interactions API: 브레이킹 체인지 이전 가이드 (2026년 5월)

v1beta Interactions API는 인플라이트 스티어링 및 비동기 도구 호출과 같은 향후 기능을 지원하기 위해 API 모양을 재구성하는 브레이킹 체인지를 도입합니다. 이 페이지에서는 변경사항을 설명하고 마이그레이션에 도움이 되는 이전 및 이후 코드 예시를 제공합니다. 변경사항에는 두 가지 카테고리가 있습니다.

  1. 단계 스키마: 새 steps 배열이 outputs 배열을 대체하여 각 상호작용 턴의 구조화된 타임라인을 제공합니다.
  2. 출력 형식 구성: 새로운 다형성 response_format이 모든 출력 형식 컨트롤을 통합하고 response_mime_type을 삭제합니다.

새 스키마로 마이그레이션하는 방법의 단계에 따라 통합을 업데이트합니다.

핵심 변경사항: outputs에서 steps로

새 스키마는 outputs 배열을 steps 배열로 대체합니다.

  • 기존: 응답은 모델의 생성된 콘텐츠만 포함하는 평면 outputs 배열을 반환합니다.
  • 새 스키마: 응답은 유형 식별자가 있는 구조화된 단계가 포함된 steps 배열을 반환합니다.

POST /interactions는 출력 단계만 반환합니다. GET /interactions/{id} 는 초기 user_input 단계를 포함하여 전체 단계 타임라인을 반환합니다.

기본 입력/출력 (단항)

이전 (기존)

Python

# Request
interaction = client.interactions.create(
    model="gemini-3.6-flash", input="Tell me a joke."
)

# Response access
print(interaction.outputs[-1].text)

JavaScript

// Request
const interaction = await client.interactions.create({
    model: 'gemini-3.6-flash',
    input: 'Tell me a joke.'
});

// Response access
console.log(interaction.outputs[-1].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.6-flash",
    "input": "Tell me a joke."
  }'

// Response
{
  "id": "int_123",
  "role": "model",
  "outputs": [
    {
      "type": "text",
      "text": "Why did the chicken cross the road?"
    }
  ]
}

이후 (새 스키마)

Python

# Request
interaction = client.interactions.create(
    model="gemini-3.6-flash", input="Tell me a joke."
)

# Response access (Recommended sugar)
print(interaction.output_text)

JavaScript

// Request
const interaction = await client.interactions.create({