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-flash-preview", input="Tell me a joke."
)

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

JavaScript

// Request
const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    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-flash-preview",
    "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-flash-preview", input="Tell me a joke."
)

# Response access
print(interaction.steps[-1].content[0].text)  # CHANGED: steps instead of outputs

JavaScript

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

// Response access
console.log(interaction.steps.at(-1).content[0].text);

REST

# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Tell me a joke."
  }'
// POST Response
{
  "id": "int_123",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Why did the chicken cross the road?"
        }
      ]
    }
  ]
}

// GET /v1beta/interactions/int_123 (returns full timeline including input)
{
  "id": "int_123",
  "steps": [
    {
      "type": "user_input",
      "content": [
        { "type": "text", "text": "Tell me a joke." }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Why did the chicken cross the road?"
        }
      ]
    }
  ]
}

함수 호출

요청 구조는 변경되지 않지만 응답은 평면 outputs 콘텐츠를 구조화된 단계로 대체합니다.

이전 (기존)

Python

# Accessing function call in legacy schema
for output in interaction.outputs:
    if output.type == "function_call":
        print(f"Calling {output.name} with {output.arguments}")

JavaScript

// Accessing function call in legacy schema
for (const output of interaction.outputs) {
    if (output.type === 'function_call') {
        console.log(`Calling {output.name} with {JSON.stringify(output.arguments)}`);
    }
}

REST

// Response
{
  "id": "int_001",
  "role": "model",
  "status": "requires_action",
  "outputs": [
    {
      "type": "thought",
      "signature": "abc123..."
    },
    {
      "type": "function_call",
      "id": "fc_1",
      "name": "get_weather",
      "arguments": { "location": "Boston, MA" }
    }
  ]
}

이후 (새 스키마)

Python

# Accessing function call in new steps schema
for step in interaction.steps:
    if step.type == "function_call":
        print(f"Calling {step.name} with {step.arguments}")

JavaScript

// Accessing function call in new steps schema
for (const step of interaction.steps) {
    if (step.type === 'function_call') {
        console.log(`Calling {step.name} with {JSON.stringify(step.arguments)}`);
    }
}

REST

// POST Response
{
  "id": "int_001",
  "status": "requires_action",
  "steps": [
    {
      "type": "thought",
      "summary": [{
        "type": "text",
        "text": "I need to check the weather in Boston..."
      }],
      "signature": "abc123..."
    },
    {
      "type": "function_call",
      "id": "fc_1",
      "name": "get_weather",
      "arguments": { "location": "Boston, MA" }
    }
  ]
}

서버 측 도구

이제 서버 측 도구 (예: Google 검색 또는 코드 실행)가 steps 배열에서 특정 단계 유형을 생성합니다. 기존 스키마는 이러한 작업을 outputs 배열 내의 특정 콘텐츠 유형으로 반환했지만 새 스키마는 이를 steps 배열로 이동합니다. 다음 예시에서는 Google 검색을 사용합니다.

이전 (기존)

Python

# Accessing search results in legacy schema
for output in interaction.outputs:
    if output.type == "google_search_call":
        print(f"Searched for: {output.arguments.queries}")
    elif output.type == "google_search_result":
        print(f"Found results: {output.result.rendered_content}")

JavaScript

// Accessing search results in legacy schema
for (const output of interaction.outputs) {
    if (output.type === 'google_search_call') {
        console.log(`Searched for: {output.arguments.queries}`);
    } else if (output.type === 'google_search_result') {
        console.log(`Found results: {output.result.renderedContent}`);
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Who won the last Super Bowl?",
    "tools": [
      { "type": "google_search" }
    ]
  }'
// Response
{
  "id": "int_456",
  "outputs": [
    {
      "type": "google_search_call",
      "id": "gs_1",
      "arguments": { "queries": ["last Super Bowl winner"] }
    },
    {
      "type": "google_search_result",
      "call_id": "gs_1",
      "result": {
        "rendered_content": "<div>...</div>",
        "url": "https://www.nfl.com/super-bowl"
      }
    },
    {
      "type": "text",
      "text": "The Kansas City Chiefs won the last Super Bowl.",
      "annotations": [
        {
          "start_index": 4,
          "end_index": 22,
          "source": "https://www.nfl.com/super-bowl"
        }
      ]
    }
  ],
  "status": "completed"
}

이후 (새 스키마)

Python

# Accessing search results in new steps schema
for step in interaction.steps:
    if step.type == "google_search_call":
        print(f"Searched for: {step.arguments.queries}")
    elif step.type == "google_search_result":
        print(f"Found results: {step.result.search_suggestions}")

JavaScript

// Accessing search results in new steps schema
for (const step of interaction.steps) {
    if (step.type === 'google_search_call') {
        console.log(`Searched for: {step.arguments.queries}`);
    } else if (step.type === 'google_search_result') {
        console.log(`Found results: {step.result.searchSuggestions}`);
    }
}

REST

# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Who won the last Super Bowl?",
    "tools": [
      { "type": "google_search" }
    ]
  }'
// POST Response
{
  "id": "int_456",
  "steps": [
    {
      "type": "google_search_call",
      "id": "gs_1",
      "arguments": { "queries": ["last Super Bowl winner"] },
      "signature": "abc123..."
    },
    {
      "type": "google_search_result",
      "call_id": "gs_1",
      "result": {
        "search_suggestions": "<div>...</div>"
      },
      "signature": "abc123..."
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The Kansas City Chiefs won the last Super Bowl.",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://www.nfl.com/super-bowl",
              "title": "NFL.com",
              "start_index": 4,
              "end_index": 22
            }
          ]
        }
      ]
    }
  ],
  "status": "completed"
}

스트리밍

스트리밍은 새로운 이벤트 유형을 노출합니다.

새 이벤트 유형

  • interaction.created
  • interaction.completed
  • interaction.in_progress
  • interaction.requires_action
  • step.start
  • step.delta
  • step.stop

지원 중단된 이벤트 유형

다음 기존 이벤트 유형은 위에 나열된 새 이벤트로 대체됩니다.

  • interaction.startinteraction.created
  • content.startstep.start
  • content.deltastep.delta
  • content.stopstep.stop
  • interaction.completeinteraction.completed
  • interaction.status_updateinteraction.in_progress, interaction.requires_action 등으로 대체됨

스트리밍 함수 호출: 함수 호출과 함께 스트리밍을 사용하면 step.start 이벤트가 함수 이름을 전달하고 step.delta 이벤트가 인수를 부분 JSON 문자열로 스트리밍합니다 (arguments_delta 사용). 전체 인수를 가져오려면 이러한 델타를 누적해야 합니다. 이는 완전한 함수 호출 객체를 한 번에 수신하는 단항 호출과는 다릅니다.

이전 (기존)

Python

# Legacy streaming used content.delta
stream = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Explain quantum entanglement in simple terms.",
    stream=True,
)

for chunk in stream:
    if chunk.event_type == "content.delta":
        if chunk.delta.type == "text":
            print(chunk.delta.text, end="", flush=True)

JavaScript

// Legacy streaming used content.delta
const stream = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Explain quantum entanglement in simple terms.',
    stream: true,
});

for await (const chunk of stream) {
    if (chunk.event_type === 'content.delta') {
        if (chunk.delta.type === 'text') {
            process.stdout.write(chunk.delta.text);
        }
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Explain quantum entanglement in simple terms.",
    "stream": true
  }'
// Response (SSE Lines)
// event: interaction.start
// data: {"id": "int_123", "status": "in_progress"}
//
// event: content.start
// data: {"index": 0, "type": "text"}
//
// event: content.delta
// data: {"delta": {"type": "text", "text": "Quantum entanglement is..."}}
//
// event: content.stop
// data: {"index": 0}
//
// event: interaction.complete
// data: {"id": "int_123", "status": "done", "usage": {"total_tokens": 42}}
이후 (새 스키마)

Python

# Consuming stream and handling new event types
for event in client.interactions.create(
    model="gemini-3-flash-preview",
    input="Tell me a story.",
    stream=True,
):
    if event.type == "step.delta":  # CHANGED: step.delta instead of content.delta
        if event.delta.type == "text":
            print(event.delta.text, end="")

JavaScript

// Consuming stream and handling new event types
const stream = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Tell me a story.',
    stream: true,
});

for await (const event of stream) {
    if (event.type === 'step.delta') {  // CHANGED: step.delta instead of content.delta
        if (event.delta.type === 'text') {
            process.stdout.write(event.delta.text);
        }
    }
}

REST

 # Opt-in needed before May 26th
 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
   -H "Content-Type: application/json" \
   -H "Accept: text/event-stream" \
   -H "Api-Revision: 2026-05-20" \
   -d '{
     "model": "gemini-3-flash-preview",
     "input": "Tell me a story.",
     "stream": true
   }'
 // Response (SSE Lines)
 // event: interaction.created
 // data: {"interaction": {"id": "int_xyz", "status": "in_progress", "object": "interaction", "model": "gemini-3-flash-preview"}, "event_type": "interaction.created"}
 //
 // event: interaction.in_progress
 // data: {"interaction_id": "int_xyz", "event_type": "interaction.in_progress"}
 //
 // event: step.start
 // data: {"index": 0, "step": {"type": "thought", "signature": "abc123..."}, "event_type": "step.start"}
 //
 // event: step.stop
 // data: {"index": 0, "event_type": "step.stop"}
 //
 // event: step.start
 // data: {"index": 1, "step": {"content": [{"text": "Once upon", "type": "text"}], "type": "model_output"}, "event_type": "step.start"}
 //
 // event: step.delta
 // data: {"index": 1, "delta": {"text": " a time...", "type": "text"}, "event_type": "step.delta"}
 //
 // event: step.stop
 // data: {"type": "step.stop", "index": 1, "status": "done"}
 //
 // event: interaction.completed
 // data: {"type": "interaction.completed", "interaction": {"id": "int_xyz", "status": "completed", "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}}} // NEW: Dedicated completion event

상태 비저장 대화 기록

클라이언트 측에서 대화 기록을 수동으로 관리하는 경우 (스테이트리스 사용 사례) 이전 턴을 연결하는 방법을 업데이트해야 합니다.

  • 기존: 개발자는 응답에서 outputs 배열을 수집하고 다음 턴의 input 필드에 다시 전송하는 경우가 많았습니다.
  • 새 스키마: 이제 응답에서 steps 배열을 수집하고 새 사용자 턴을 user_input 단계로 추가하여 다음 요청의 input 필드에 전달해야 합니다.

출력 형식 구성: response_format 변경사항

업데이트된 API는 모든 출력 형식 컨트롤을 통합된 다형성 response_format 필드로 통합합니다. 이렇게 하면 최상위 수준에서 출력 구성이 중앙 집중화되고 generation_config가 온도, top_p, 생각과 같은 모델 동작에 집중됩니다.

주요 변경사항

  • API가 response_mime_type을 삭제합니다. 이제 response_format 내의 형식 항목별로 MIME 유형을 지정합니다.
  • 이제 response_format이 다형성 객체 (또는 배열)입니다. 각 항목에는 type 구분자 (text, audio, image)와 유형별 필드가 있습니다. 여러 출력 모달리티를 요청하려면 형식 항목 배열을 전달합니다.
  • image_configgeneration_config에서 response_format으로 이동합니다. 이제 response_format 항목에서 "type": "image"와 함께 aspect_ratioimage_size 와 같은 이미지 출력 설정을 지정합니다.

구조화된 출력 (JSON)

새 스키마는 response_mime_type 필드를 삭제합니다. 대신 MIME 유형과 JSON 스키마를 response_format 객체 내에서 "type": "text" 지정합니다.

이전 (기존)

Python

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Summarize this article.",
    response_mime_type="application/json",
    response_format={
        "type": "object",
        "properties": {
            "summary": {"type": "string"}
        }
    },
)

print(interaction.outputs[-1].text)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Summarize this article.',
    response_mime_type: 'application/json',
    response_format: {
        type: 'object',
        properties: {
            summary: { type: 'string' }
        }
    },
});

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-flash-preview",
    "input": "Summarize this article.",
    "response_mime_type": "application/json",
    "response_format": {
      "type": "object",
      "properties": {
        "summary": { "type": "string" }
      }
    }
  }'

이후 (새 스키마)

Python

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Summarize this article.",
    # response_mime_type is removed — specify mime_type inside response_format
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": {
            "type": "object",
            "properties": {
                "summary": {"type": "string"}
            }
        }
    },
)

print(interaction.steps[-1].content[0].text)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Summarize this article.',
    // response_mime_type is removed — specify mime_type inside response_format
    response_format: {
        type: 'text',
        mime_type: 'application/json',
        schema: {
            type: 'object',
            properties: {
                summary: { type: 'string' }
            }
        }
    },
});

console.log(interaction.steps.at(-1).content[0].text);

REST

# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Summarize this article.",
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {
          "summary": { "type": "string" }
        }
      }
    }
  }'

이미지 구성

새 스키마는 generation_config에서 image_config를 삭제합니다. 이제 response_format 항목에서 "type": "image"를 사용하여 이미지 출력 설정을 지정합니다.

이전 (기존)

Python

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Generate an image of a sunset over the ocean.",
    generation_config={
        "image_config": {
            "aspect_ratio": "1:1",
            "image_size": "1K"
        }
    },
)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Generate an image of a sunset over the ocean.',
    generation_config: {
        image_config: {
            aspect_ratio: '1:1',
            image_size: '1K'
        }
    },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Generate an image of a sunset over the ocean.",
    "generation_config": {
      "image_config": {
        "aspect_ratio": "1:1",
        "image_size": "1K"
      }
    }
  }'

이후 (새 스키마)

Python

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Generate an image of a sunset over the ocean.",
    # image_config is removed from generation_config — use response_format
    response_format={
        "type": "image",
        "mime_type": "image/jpeg",
        "aspect_ratio": "1:1",
        "image_size": "1K"
    },
)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Generate an image of a sunset over the ocean.',
    // image_config is removed from generation_config — use response_format
    response_format: {
        type: 'image',
        mime_type: 'image/jpeg',
        aspect_ratio: '1:1',
        image_size: '1K'
    },
});

REST

# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Generate an image of a sunset over the ocean.",
    "response_format": {
      "type": "image",
      "mime_type": "image/jpeg",
      "aspect_ratio": "1:1",
      "image_size": "1K"
    }
  }'

여러 출력 모달리티 (예: 텍스트와 오디오 함께)를 요청하려면 단일 객체 대신 형식 항목 배열을 response_format에 전달합니다.

새 스키마로 마이그레이션하는 방법

SDK 사용자

최신 SDK 버전 (Python ≥2.0.0, JavaScript ≥2.0.0)으로 업그레이드합니다. SDK는 자동으로 새 스키마를 선택합니다. 응답을 읽는 방법을 업데이트하는 것 외에는 코드를 변경할 필요가 없습니다 (위의 예 참고). 이러한 SDK 버전에서는 새 스키마만 지원됩니다. 이전 SDK 버전(Python 1.x.x, JavaScript 1.x.x)은 2026년 6월 8일 에 기존 스키마가 삭제될 때까지 계속 작동합니다.

REST API 사용자

지금 새 스키마를 선택하려면 요청에 Api-Revision: 2026-05-20 헤더를 추가합니다. 5월 26일 이후에는 새 스키마가 모든 요청의 기본값이 됩니다. API가 기존 스키마를 영구적으로 삭제하는 6월 8일까지 Api-Revision: 2026-05-07 로 일시적으로 선택 해제할 수 있습니다.

타임라인

날짜 단계 SDK 사용자 REST API 사용자
5월 7일 선택 새 SDK 버전 사용 가능 (Python ≥2.0.0, JS ≥2.0.0). 새 스키마를 자동으로 가져오려면 업그레이드하세요. Api-Revision: 2026-05-20 헤더를 추가하여 선택합니다. 기본값은 기존으로 유지됩니다.
5월 26일 기본값 뒤집기 이미 업그레이드한 경우 별도의 조치가 필요하지 않습니다. 이전 SDK (Python 1.x.x, JS 1.x.x)는 계속 작동하지만 기존 응답을 반환합니다. 이제 새 스키마가 기본값입니다. Api-Revision: 2026-05-07 헤더를 전송하여 선택 해제합니다.
6월 8일 일몰 Python 1.x.x 및 JS 1.x.x SDK 버전은 Interactions API 호출에서 중단됩니다. Interactions API의 기존 스키마가 삭제되었습니다. Api-Revision 헤더가 무시됩니다.

마이그레이션 체크리스트

단계 스키마 (steps)

  • outputs 대신 steps 배열에서 응답 콘텐츠를 읽도록 코드를 업데이트합니다. 예 보기.
  • 코드가 user_inputmodel_output 단계 유형을 모두 처리하는지 확인합니다. 예 보기.
  • (함수 호출) steps 배열에서 function_call 단계를 찾도록 코드를 업데이트합니다. 예 보기.
  • (서버 측 도구) 도구별 단계 (예: google_search_call, google_search_result)를 처리하도록 코드를 업데이트합니다. 예 보기.
  • (상태 비저장 기록) 다음 요청의 input 필드에 steps 배열을 전달하도록 기록 관리를 업데이트합니다. 세부정보 보기.
  • (스트리밍만 해당) 새 SSE 이벤트 유형 (interaction.created, step.delta 등)을 수신 대기하도록 클라이언트를 업데이트합니다. 예 보기.

출력 형식 구성 (response_format)

  • response_mime_typeresponse_format 내의 mime_type 필드로 바꿉니다. 예 보기.
  • 기존 response_format JSON 스키마를 {"type": "text", "schema": ...} 객체 내에 래핑합니다. 예 보기.
  • (이미지 생성) image_configgeneration_config에서 response_format{"type": "image", ...} 항목으로 이동합니다. 예 보기.
  • (멀티모달) 여러 출력 모달리티를 요청할 때 response_format을 단일 객체에서 배열로 변환합니다.