Interactions API: Breaking changes 마이그레이션 가이드

Interactions API: Breaking changes 마이그레이션 가이드 (2026년 5월)

Breaking changes: 이 가이드에 설명된 변경 사항은 Interactions API의 breaking change예요. 레거시 스키마는 2026년 6월 8일에 제거돼요. Api-Revision 요청 헤더를 사용해 마이그레이션을 관리하세요.

v1beta Interactions API는 미드플라이트 스티어링(mid-flight steering)과 비동기 도구 호출 같은 향후 기능을 지원하기 위해 API 형태를 재구성하는 breaking changes를 도입해요. 이 페이지는 무엇이 바뀌는지 설명하고 마이그레이션을 돕기 위한 전/후 코드 예시를 제공해요. 변경 사항은 두 범주가 있어요:

1. Steps 스키마: 새 steps 배열이 outputs 배열을 대체하며 각 상호작용 턴의 구조화된 타임라인을 제공해요.
2. 출력 형식 구성: 새 다형성(polymorphic) response_format이 모든 출력 형식 제어를 통합하고 response_mime_type을 제거해요.

통합을 업데이트하려면 새 스키마로 마이그레이션하는 방법의 단계를 따르세요.

출처: 원문

본문

핵심 변경: outputs → steps

새 스키마는 outputs 배열을 steps 배열로 대체해요.

• 레거시(Legacy): 응답은 모델이 생성한 콘텐츠만 포함하는 평면(flat) outputs 배열을 반환했어요.
• 새 스키마: 응답은 유형 식별자가 있는 구조화된 단계를 포함하는 steps 배열을 반환해요.

POST /interactions는 출력 단계만 반환해요. GET /interactions/{id}는 초기 user_input 단계를 포함한 전체 단계 타임라인을 반환해요.

기본 입출력(Unary)

이전(Legacy)

Python

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

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

JavaScript

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

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

이후(New schema)

Python

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

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

JavaScript

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

// Response access (Recommended sugar)
console.log(interaction.output_text);

참고: SDK 편의 속성(.output_text, .output_image, .output_audio 등)에 대한 자세한 내용은 개요의 SDK 편의 속성으로 출력 접근을 참고하세요.

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.8-flash",
    "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?"
        }
      ]
    }
  ]
}

함수 호출(Function calling)

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

이전(Legacy)

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" }
    }
  ]
}

이후(New schema)

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" }
    }
  ]
}

서버 측 도구(Server-side tools)

서버 측 도구(Google Search 또는 코드 실행 등)는 이제 steps 배열에서 특정 단계 유형을 산출해요. 레거시 스키마는 이러한 작업을 outputs 배열 안의 특정 콘텐츠 유형으로 반환했지만, 새 스키마는 이를 steps 배열로 옮겨요. 다음 예시는 Google Search를 사용해요.

이전(Legacy)

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.8-flash",
    "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"
}

이후(New schema)

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[0].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[0].search_suggestions}`);
    }
}

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.8-flash",
    "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"
}

스트리밍(Streaming)

스트리밍은 새 이벤트 유형을 노출해요:

새 이벤트 유형

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

단종된 이벤트 유형

다음 레거시 이벤트 유형은 위에 나열된 새 이벤트로 대체돼요:

• interaction.start → interaction.created
• content.start → step.start
• content.delta → step.delta
• content.stop → step.stop
• interaction.complete → interaction.completed
• interaction.status_update → interaction.in_progress, interaction.requires_action 등으로 대체됨

스트리밍 함수 호출: 함수 호출과 함께 스트리밍을 사용하면 step.start 이벤트가 함수 이름을 전달하고, step.delta 이벤트가 인수를 부분 JSON 문자열(arguments_delta 사용)로 스트리밍해요. 전체 인수를 얻으려면 이러한 델타를 축적해야 해요. 이는 완전한 함수 호출 객체를 한 번에 받는 unary 호출과 다르요.

예시

이전(Legacy)

Python

# Legacy streaming used content.delta
stream = client.interactions.create(
    model="gemini-3.8-flash",
    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.8-flash',
    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.8-flash",
    "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}}

이후(New Schema)

Python

# Consuming stream and handling new event types
for event in client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me a story.",
    stream=True,
):
    if event.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.8-flash',
    input: 'Tell me a story.',
    stream: true,
});

for await (const event of stream) {
    if (event.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.8-flash",
     "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.8-flash"}, "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

무상태(Stateless) 대화 기록

대화 기록을 클라이언트 측에서 수동으로 관리한다면(무상태 사용 사례), 이전 턴을 연결하는 방식을 업데이트해야 해요.

• 레거시: 개발자는 응답의 outputs 배열을 수집해 다음 턴의 input 필드로 다시 보내는 경우가 많았어요.
• 새 스키마: 응답의 steps 배열을 수집해 다음 요청의 input 필드에 전달하고, 새 사용자 턴을 user_input 단계로 추가해야 해요.

출력 형식 구성: response_format 변경

업데이트된 API는 모든 출력 형식 제어를 통합된 다형성 response_format 필드로 통합해요. 이는 출력 구성을 최상위 수준에 중앙화하고 generation_config는 모델 동작(예: temperature, top_p, thinking)에 집중하도록 유지해요.

주요 변경 사항

• API가 response_mime_type을 제거해요. 이제 response_format 안의 형식 항목별로 MIME 유형을 지정해요.
• response_format은 이제 다형성 객체(또는 배열)예요. 각 항목은 type 식별자(text, audio, image)와 유형별 필드를 가져요. 여러 출력 모달리티를 요청하려면 형식 항목 배열을 전달해요.
• image_config가 generation_config에서 response_format으로 이동해요. 이제 "type": "image"의 response_format 항목에서 aspect_ratio, image_size 같은 이미지 출력 설정을 지정해요.

구조화 출력(JSON)

새 스키마는 response_mime_type 필드를 제거해요. 대신 "type": "text"의 response_format 객체 안에 MIME 유형과 JSON 스키마를 지정해요.

이전(Legacy)

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    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.8-flash',
    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.8-flash",
    "input": "Summarize this article.",
    "response_mime_type": "application/json",
    "response_format": {
      "type": "object",
      "properties": {
        "summary": { "type": "string" }
      }
    }
  }'

이후(New schema)

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    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 response
print(interaction.output_text)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    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 response
console.log(interaction.output_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.8-flash",
    "input": "Summarize this article.",
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {
          "summary": { "type": "string" }
        }
      }
    }
  }'

이미지 구성(Image configuration)

새 스키마는 generation_config에서 image_config를 제거해요. 이제 "type": "image"의 response_format 항목에서 이미지 출력 설정을 지정해요.

이전(Legacy)

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    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.8-flash',
    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.8-flash",
    "input": "Generate an image of a sunset over the ocean.",
    "generation_config": {
      "image_config": {
        "aspect_ratio": "1:1",
        "image_size": "1K"
      }
    }
  }'

이후(New schema)

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    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.8-flash',
    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.8-flash",
    "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"
    }
  }'

오디오 구성(Audio configuration)

새 스키마는 response_modalities: ["audio"]를 "type": "audio"의 response_format 항목으로 대체해요.

이전(Legacy)

Python

interaction = client.interactions.create(
    model="gemini-3.1-flash-tts-preview",
    input="Say cheerfully: Have a wonderful day!",
    response_modalities=["audio"],
    generation_config={
        "speech_config": [
            {"voice": "Kore"}
        ]
    }
)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3.1-flash-tts-preview',
    input: 'Say cheerfully: Have a wonderful day!',
    response_modalities: ['audio'],
    generation_config: {
        speech_config: [
            { voice: 'Kore' }
        ]
    },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-tts-preview",
    "input": "Say cheerfully: Have a wonderful day!",
    "response_modalities": ["audio"],
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    }
  }'

이후(New schema)

Python

interaction = client.interactions.create(
    model="gemini-3.1-flash-tts-preview",
    input="Say cheerfully: Have a wonderful day!",
    # response_modalities is removed — use response_format
    response_format={
        "type": "audio"
    },
    generation_config={
        "speech_config": [
            {"voice": "Kore"}
        ]
    }
)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3.1-flash-tts-preview',
    input: 'Say cheerfully: Have a wonderful day!',
    // response_modalities is removed — use response_format
    response_format: {
        type: 'audio'
    },
    generation_config: {
        speech_config: [
            { voice: 'Kore' }
        ]
    },
});

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.1-flash-tts-preview",
    "input": "Say cheerfully: Have a wonderful day!",
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    }
  }'

여러 출력 모달리티(예: 텍스트와 오디오를 함께)를 요청하려면 단일 객체 대신 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일	옵트인(Opt-in)	새 SDK 버전 사용 가능(Python ≥2.0.0, JS ≥2.0.0). 업그레이드하면 새 스키마를 자동으로 얻을 수 있어요.	Api-Revision: 2026-05-20 헤더를 추가해 옵트인하세요. 기본값은 레거시로 유지돼요.
5월 26일	기본 전환(Default flip)	이미 업그레이드했다면 조치 필요 없음. 이전 SDK(Python 1.x.x, JS 1.x.x)는 여전히 동작하지만 레거시 응답을 반환해요.	새 스키마가 기본값이 돼요. 옵트아웃하려면 Api-Revision: 2026-05-07 헤더를 보내세요.
6월 8일	제거(Sunset)	Python 1.x.x, JS 1.x.x SDK 버전은 Interactions API 호출에 대해 실패하게 돼요.	Interactions API용 레거시 스키마가 제거돼요. Api-Revision 헤더는 무시돼요.

참고: 5월 7일 이후 출시되는 새 기능은 steps 응답에만 나타나요. 레거시 outputs 스키마 사용자는 마이그레이션할 때까지 새 기능을 받지 못해요.

마이그레이션 체크리스트

Steps 스키마(steps)

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

출력 형식 구성(response_format)

• response_mime_type을 response_format 안의 mime_type 필드로 교체해요. 예시 참고.
• 기존 response_format JSON 스키마를 {"type": "text", "schema": ...} 객체 안에 감싸요. 예시 참고.
• (이미지 생성) generation_config의 image_config를 response_format의 {"type": "image", ...} 항목으로 이동해요. 예시 참고.
• (음성 생성) response_modalities=["audio"]를 response_format의 {"type": "audio"} 항목으로 교체해요. 예시 참고.
• (멀티모달) 여러 출력 모달리티를 요청할 때 response_format을 단일 객체에서 배열로 변환해요.

더 알아보기 (Learn more)

• Interactions API 개요
• Gemini API