Gemini Interactions API – Create, Retrieve, and Cancel

Interact with Gemini models or agents through /v1beta/interactions. Supports multi-turn conversation, multimodal input, function calling, background tasks, and streaming output.

For new projects, use the stable Interactions API (v1). This page is retained for /v1beta/interactions compatibility.

Create an interaction with a model or an agent. You can pass plain text, or images, audio, video, and documents. Multi-turn history, tool calls, and background tasks are supported.

This is currently a Beta endpoint, and the path is under /v1beta/. Provide one of model or agent: when using a model, put generation parameters in generation_config; when using an agent, put parameters in agent_config.

The create endpoint returns an Interaction resource directly. To retrieve it later by ID, set store to true when creating it. For long-running tasks, set background to true, then check the status with the query endpoint; a background interaction that is still running can be cancelled.

Base URL

https://api.autorouter.top — Production

Authentication

BearerAuth: http (bearer) Authenticate using a Bearer Token. Format: Authorization: Bearer sk-xxxxxx

Endpoints

POST `/v1beta/interactions`

Create an interaction

Create a new interaction. Specify a model with model, or an agent with agent.

Request Body

Content-Type: application/json

Example:

{
  "model": "gemini-3.6-flash",
  "input": "Hello, please introduce yourself"
}

Properties:

Name	Type	Required	Description
`model`	string	Conditional	Model name used to generate the interaction. Required when `agent` is not provided. See below for allowed values
`agent`	string	Conditional	Agent name used to generate the interaction. Required when `model` is not provided. See below for allowed values
`input`	string \| object \| array	No	Interaction input. It can be a string, a single content block, an array of content blocks, or conversation history made up of Steps. It is passed in every example
`system_instruction`	string	No	System instruction for this interaction
`tools`	object[]	No	List of tool declarations the model can call. See "Tools" at the end for types and fields
`response_format`	object \| object[]	No	Force the response to be a JSON object that matches the given JSON Schema
`stream`	boolean	No	Whether to return the interaction as a stream. Input only
`store`	boolean	No	Whether to store the request and response so they can be queried later by ID. Input only
`background`	boolean	No	Whether to run in the background. Input only. Background tasks can be stopped with the cancel endpoint
`generation_config`	object	No	Model configuration. Applies only when `model` is set, and is mutually exclusive with `agent_config`
`generation_config.max_output_tokens`	integer	No	Maximum number of tokens included in the response
`generation_config.seed`	integer	No	Random seed used for decoding, for reproducing results
`generation_config.speech_config`	object \| object[]	No	Speech and multi-speaker configuration
`generation_config.speech_config.speakers`	object[]	No	Configuration for each speaker
`generation_config.speech_config.speakers[].language`	string	No	Speech language
`generation_config.speech_config.speakers[].speaker`	string	No	Speaker name. It must match the name in the prompt
`generation_config.speech_config.speakers[].voice`	string	No	Speaker voice
`generation_config.stop_sequences`	string[]	No	Stop output when these character sequences are encountered
`generation_config.thinking_level`	string	No	Thinking token level: `minimal` / `low` / `medium` / `high`
`generation_config.thinking_summaries`	string	No	Whether to include a thinking summary in the response: `auto` / `none`
`generation_config.tool_choice`	string \| object	No	Tool choice: `auto` / `any` / `none` / `validated`
`generation_config.transcription_config`	object	No	Speech recognition configuration. Passing it enables transcription
`generation_config.transcription_config.custom_vocabulary`	string[]	No	Custom vocabulary that biases recognition toward specific terms
`generation_config.transcription_config.language_codes`	string[]	No	BCP-47 language codes. The language is detected automatically when this is omitted or empty
`generation_config.transcription_config.mode`	string \| object	No	Transcription mode: `verbatim` (word-for-word) / `smart` (intelligent)
`generation_config.transcription_config.mode.type`	string	Yes	Required when the mode is an object. Value is `smart` or `verbatim`
`generation_config.transcription_config.mode.diarization_mode`	string	No	`verbatim` only. Speaker diarization. Supported value: `speaker`
`generation_config.transcription_config.mode.timestamp_granularities`	string[]	No	`verbatim` only. Timestamp granularity. Supported value: `word`. If empty, no timestamps are generated
`generation_config.video_config`	object	No	Video generation configuration
`generation_config.video_config.task`	string	No	Video generation task mode. When not specified, the model decides from the prompt and input media
`agent_config`	object	No	Agent configuration. Applies only when `agent` is set, and is mutually exclusive with `generation_config`
`environment`	string \| object	No	Runtime environment. It can be an existing environment ID, or an object that describes the source of a remote environment
`labels`	object	No	Custom labels. Keys and values are each at most 63 characters, and may contain only lowercase letters, digits, underscores, and hyphens. Keys must start with a letter
`previous_interaction_id`	string	No	ID of the previous interaction, used to continue the context
`safety_settings`	object[]	No	Safety settings for this interaction
`safety_settings[].method`	string	No	How content is blocked. When not specified, content is blocked by probability score
`safety_settings[].threshold`	string	Yes	Block threshold. Required when safety settings are present
`safety_settings[].type`	string	Yes	Harmful content category to block. Required when safety settings are present
`service_tier`	string	No	Service tier: `flex` / `standard` / `priority` / `deferred`
`webhook_config`	object	No	Webhook notification configuration for when the interaction completes
`webhook_config.uris`	string[]	No	When set, events are sent to these URIs and the registered Webhook is no longer used
`webhook_config.user_metadata`	object	No	User metadata, returned with every event push

modelstring(conditional)

Model name used to generate the interaction. Required when agent is not provided.

Specific model IDs are those shown in Model Plaza on the AutoRouter platform and visible to the API Key.

agentstring(conditional)

Agent name used to generate the interaction. Required when model is not provided. You can also pass the ID of a custom agent that has already been created.

For long-running tasks such as Deep Research, also set "background": true, then get progress through the query endpoint.

inputstring | object | array(optional)

Input for this interaction. It applies to both models and agents.

String: used directly as the user text
A single content block, or an array of content blocks: text, image, audio, video, and document. See "Content blocks" at the end
An array of Steps: multi-turn history. Elements are steps such as user_input / model_output

Example value: Hello, please introduce yourself

toolsobject[](optional)

Tools the model can call in this interaction. Use type to distinguish the types. See "Tools" at the end for the full types and fields.

generation_configobject(optional)

Generation parameters for the model. They take effect only when the request sets model.

backgroundboolean(optional)

Whether to run this interaction in the background. Suited to long-running tasks such as Deep Research.

After a background task is created, an in-progress Interaction is returned first. Then poll status with the query endpoint until it becomes completed, failed, cancelled, or incomplete. While it is still running, you can call the cancel endpoint.

storeboolean(optional)

Whether to store this request and response so they can later be retrieved by id with the query endpoint.

streamboolean(optional)

Whether to return this interaction as a stream. The query endpoint can also resume the stream with the query parameter stream=true, using Server-Sent Events. See "InteractionSseEvent" at the end for event fields.

environmentstring | object(optional)

The runtime environment of the agent.

"remote": create a new remote environment. Pass the environment_id from the response back unchanged on later requests to reuse the same environment
An existing environment ID string: keep using that environment. Usually pass previous_interaction_id as well
Object: describes the remote environment, and can mount a code repository or inline files

{
  "environment": {
    "type": "remote",
    "sources": [
      {
        "type": "repository",
        "source": "https://github.com/octocat/Spoon-Knife",
        "target": "/workspace/repo"
      },
      {
        "type": "inline",
        "content": "Focus only on Python files.",
        "target": "/workspace/notes.txt"
      }
    ]
  }
}

previous_interaction_idstring(optional)

ID of the previous interaction. When used together with an existing environment, the agent can continue from the previous files and context.

safety_settingsobject[](optional)

Safety filtering for this interaction. Each item specifies the category to block and the threshold.

service_tierstring(optional)

Service tier of the interaction: flex, standard, priority, deferred.

Responses

200: Created successfully. Returns an Interaction resource

Content-Type: application/json

400: Invalid request parameters

Content-Type: application/json

401: Authentication failed

429: Request rate limit

Request Example

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "input": "Hello, please introduce yourself"
}'

Put the history in input. Each turn is a Step: user_input is the user, and model_output is the model's previous reply.

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "input": [
    { "type": "user_input", "content": [{ "type": "text", "text": "Hello" }] },
    { "type": "model_output", "content": [{ "type": "text", "text": "Hello, what can I help you with?" }] },
    { "type": "user_input", "content": [{ "type": "text", "text": "What is the capital of France?" }] }
  ]
}'

Put text and an image together in the content block array. For the image, use Base64 data, or uri.

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "input": [
    { "type": "text", "text": "What is in this image?" },
    { "type": "image", "data": "BASE64_ENCODED_IMAGE", "mime_type": "image/png" }
  ]
}'

Declare the function first. When the model decides to call it, the response status is requires_action, and a function_call appears in steps.

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Get the current weather for a specified location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City, for example Shanghai"
          }
        },
        "required": ["location"]
      }
    }
  ],
  "input": "What is the weather in Boston right now?"
}'

Deep Research should run in the background. After creation, read id and status, then poll the query endpoint.

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "agent": "deep-research-pro-preview-12-2025",
  "input": "Summarize the main advances in cancer research in 2025",
  "background": true,
  "store": true
}'

When environment is set to "remote", the response includes environment_id. On the next turn, pass that ID together with previous_interaction_id to continue in the same environment.

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "agent": "antigravity-preview-05-2026",
  "input": "Write a Hello World script in /workspace/hello.py.",
  "environment": "remote"
}'

Response Example

{
  "created": "2025-11-26T12:25:15Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3.6-flash",
  "object": "interaction",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Hello, I can help you write code, look up information, and analyze images. What would you like to do first today?"
        }
      ]
    }
  ],
  "updated": "2025-11-26T12:25:15Z",
  "usage": {
    "input_tokens_by_modality": [
      { "modality": "text", "tokens": 7 }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 7,
    "total_output_tokens": 20,
    "total_thought_tokens": 22,
    "total_tokens": 49,
    "total_tool_use_tokens": 0
  }
}

Response fields:

Name	Type	Description
`id`	string	Unique identifier of the interaction. Output only
`object`	string	Always `interaction`
`status`	string	Interaction status. See below
`created`	string	Creation time, ISO 8601, for example `2025-11-26T12:25:15Z`
`updated`	string	Last updated time, ISO 8601
`model`	string	Model used this time. May not be returned when an agent is used
`agent`	string	Agent used this time. May not be returned when a model is used
`steps`	object[]	Steps that make up this interaction
`environment_id`	string	Environment ID. Returned when the request sets an environment. It can be reused in `environment` on later requests
`usage`	object	Token usage
`usage.total_input_tokens`	integer	Number of input tokens
`usage.total_output_tokens`	integer	Number of output tokens
`usage.total_cached_tokens`	integer	Number of input tokens that hit the cache
`usage.total_thought_tokens`	integer	Number of thinking tokens
`usage.total_tool_use_tokens`	integer	Number of tokens related to tool use
`usage.total_tokens`	integer	Total number of tokens counted for this interaction
`usage.input_tokens_by_modality`	object[]	Input tokens counted by modality. The same applies to `output_tokens_by_modality`, `cached_tokens_by_modality`, and `tool_use_tokens_by_modality`
`usage.*_by_modality[].modality`	string	Modality: `text` / `image` / `audio` / `video` / `document`
`usage.*_by_modality[].tokens`	integer	Number of tokens for this modality
`usage.grounding_tool_count`	object[]	Number of grounding tool calls
`usage.grounding_tool_count[].type`	string	`google_search` (web and image search) / `google_maps` (maps) / `retrieval` (customer data retrieval)
`usage.grounding_tool_count[].count`	integer	Number of calls of this type
`errors`	object[]	Diagnostic failures or platform errors. Usually not returned on success
`errors[].code`	string	URI that identifies the error type
`errors[].message`	string	Human-readable error message
`input`	string \| object \| array	Interaction input. Returned on query only when `include_input=true`
`system_instruction`	string	System instruction
`tools`	object[]	Tools declared for this interaction
`previous_interaction_id`	string	ID of the associated previous interaction
`labels`	object	Custom labels written at creation
`service_tier`	string	Service tier: `flex` / `standard` / `priority` / `deferred`

statusstring

Interaction status:

in_progress: in progress
requires_action: you need to provide more input, for example by running the function and sending the result back
completed: completed
failed: failed
cancelled: cancelled
incomplete: ended, but the result is incomplete, for example because max_output_tokens was reached
queued: queued, waiting to be processed

For background tasks, query every few seconds until status becomes completed, failed, cancelled, or incomplete.

stepsobject[]

Steps that make up this interaction. The types that appear in the examples are below. The full Step definition follows the official Gemini documentation.

`type`	Description	Main fields
`user_input`	User input	`content`: array of content blocks
`model_output`	Model output	`content`: array of content blocks
`function_call`	Function call started by the model	`id`, `name`, `arguments`

usageobject

Token usage for this interaction, which can be used to check usage.

total_input_tokensinteger

Number of tokens used by the prompt and context.

total_output_tokensinteger

Number of tokens used by the generated content.

total_thought_tokensinteger

Number of tokens used by the thinking process.

total_tool_use_tokensinteger

Number of tokens related to tool use.

total_tokensinteger

Total number of tokens for this interaction, including input, output, and other internal tokens.

input_tokens_by_modalityobject[]

Usage split by modality. Each item contains modality (text, image, audio, video, document) and tokens. Output, cache, and tool use also have corresponding *_by_modality arrays.

POST `/v1beta/interactions/{interactionsId}/cancel`

Cancel an interaction

Cancel a background interaction that is still running, by ID. This applies only to tasks that were created with background: true and have not finished.

Path Parameters

Name	Type	Required	Description
`interactionsId`	string	Yes	ID of the interaction to cancel

Responses

200: Cancelled successfully. Returns an Interaction resource with status cancelled

Content-Type: application/json

Request Example

curl -X POST "https://api.autorouter.top/v1beta/interactions/{interactionsId}/cancel" \
  -H "Authorization: Bearer sk-xxxxxx"

Response Example

{
  "agent": "deep-research-pro-preview-12-2025",
  "created": "2026-06-22T04:55:47Z",
  "id": "v1_ChdVc0E0YXJTYk1zYlV6N0lQcXRXVG1BYxIXVXNBNGFyU2JNc2JVejdJUHF0V1RtQWM",
  "object": "interaction",
  "status": "cancelled",
  "steps": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Research the history of the Google TPUs with a focus on 2025 specs."
        }
      ]
    }
  ],
  "updated": "2026-06-22T04:55:47Z"
}

GET `/v1beta/interactions/{interactionsId}`

Query an interaction

Get the interaction details from the id returned at creation. Use this to poll a background task, or to retrieve a stored result.

Headers

Name	Type	Required	Description
`Authorization`	string	Yes	Request authentication. Format: `Bearer sk-xxxxxx`

Path Parameters

Name	Type	Required	Description
`interactionsId`	string	Yes	ID of the interaction to query

Query Parameters

Name	Type	Required	Description
`include_input`	boolean	No	When `true`, the response includes the original input
`stream`	boolean	No	When `true`, interaction events are returned as a Server-Sent Events stream. See "InteractionSseEvent" at the end for event fields
`last_event_id`	string	No	Resume streaming after this event ID. Used only when `stream` is `true`

Responses

200: Query succeeded. Returns an Interaction resource. The fields are the same as the create endpoint

Content-Type: application/json

Request Example

curl -X GET "https://api.autorouter.top/v1beta/interactions/{interactionsId}" \
  -H "Authorization: Bearer sk-xxxxxx"

Response Example

{
  "created": "2025-11-26T12:25:15Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3.6-flash",
  "object": "interaction",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "I'm doing well, thank you. What can I help you with?"
        }
      ]
    }
  ],
  "updated": "2025-11-26T12:25:15Z"
}

DELETE `/v1beta/interactions/{interactionsId}`

Delete an interaction

Delete a stored interaction by ID.

Path Parameters

Name	Type	Required	Description
`interactionsId`	string	Yes	ID of the interaction to delete

Responses

200: Deleted successfully. The response body is empty

Request Example

curl -X DELETE "https://api.autorouter.top/v1beta/interactions/{interactionsId}" \
  -H "Authorization: Bearer sk-xxxxxx"

Content blocks

input and a Step's content use content blocks, distinguished by type. annotations on a text block mark citations and appear on text the model generates.

`type`	Description	Main fields
`text`	Text	`text`. Optional `annotations`
`image`	Image	`data` (Base64) or `uri`, plus `mime_type` and `resolution`
`audio`	Audio	`data` or `uri`, plus `mime_type`, `channels`, and `sample_rate`
`video`	Video	`data` or `uri` (which can be a video link), plus `mime_type`, `resolution`, and `processing`
`document`	Document	`data` or `uri`, plus `mime_type`

Image mime_type: image/png, image/jpeg, image/webp, image/heic, image/heif, image/gif, image/bmp, image/tiff

Audio mime_type: audio/wav, audio/mp3, audio/aiff, audio/aac, audio/ogg, audio/flac, audio/mpeg, audio/m4a, audio/l16, audio/opus, audio/alaw, audio/mulaw, audio/webm

Video mime_type: video/mp4, video/mpeg, video/mpg, video/mov, video/avi, video/x-flv, video/webm, video/wmv, video/3gpp

Document mime_type: application/pdf, text/csv

resolution values for images and video: low, medium, high, ultra_high.

Video processing controls how the model reads the video:

agentic: the model browses the frames dynamically
static: sample frames at a fixed frame rate and place them in the context. You can pass the string "static" directly, or pass an object and set start_offset, end_offset (for example "10.5s", "30s"), and fps

annotations on text use start_index / end_index to mark the cited span (start_index is counted in bytes, and end_index does not include that position).

`type`	Description	Main fields
`url_citation`	Web citation	`url`, `title`
`file_citation`	File citation	`file_name`, `document_uri`, `page_number`, `source`, `media_id`, `custom_metadata`
`place_citation`	Place citation	`name`, `place_id`, `url`, `review_snippets`
`speech_metadata`	Speech annotation	`speaker`, `style`
`word_info`	Word-level annotation of the transcription	`text`, `start_offset`, `end_offset`, `speaker`

{
  "type": "text",
  "text": "Hello, how are you?"
}

Tools

When you create an interaction, tools declares the tools the model can call, distinguished by type. The same declaration also appears on the returned Interaction. Whether a tool is called, and which one, is controlled by generation_config.tool_choice: auto, any, none, validated.

When the model decides to call a custom function, the interaction status is requires_action, and a function_call appears in steps. After you finish running the function, send the result back as the next turn's input.

`type`	Description	Main fields
`function`	Custom function	`name`, `description`, `parameters`
`code_execution`	Execute code	No other fields
`url_context`	Extract URL content	No other fields
`computer_use`	Operate a computer	`environment`, `excluded_predefined_functions`, `disabled_safety_policies`, `enable_prompt_injection_detection`
`mcp_server`	Call an MCP server	`name`, `url`, `headers`, `allowed_tools`
`google_search`	Search Google	`search_types`
`file_search`	Search a file store	`file_search_store_names`, `top_k`, `metadata_filter`
`google_maps`	Query Google Maps	`enable_widget`, `latitude`, `longitude`
`retrieval`	Retrieve files	`retrieval_types`, `vertex_ai_search_config`

A custom function tool the model can use. When the model decides to call it, the interaction returns a function_call step, and the status is requires_action.

Example: function calling

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "tools": [{
    "type": "function",
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "The city and state, e.g. San Francisco, CA"
        }
      },
      "required": ["location"]
    }
  }],
  "input": "What is the weather like in Boston, MA?"
}'

Example response (the model requests a function call, and the status is requires_action)

{
  "created": "2025-11-26T12:22:47Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3.6-flash",
  "object": "interaction",
  "status": "requires_action",
  "steps": [
    {
      "name": "get_weather",
      "type": "function_call",
      "arguments": {
        "location": "Boston, MA"
      },
      "id": "gth23981"
    }
  ],
  "updated": "2025-11-26T12:22:47Z",
  "usage": {
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 100
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 100,
    "total_output_tokens": 25,
    "total_thought_tokens": 0,
    "total_tokens": 125,
    "total_tool_use_tokens": 50
  }
}

A tool the model can use to execute code. This type has no other fields.

Example: code execution

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "tools": [{
    "type": "code_execution"
  }],
  "input": "Calculate the first 10 Fibonacci numbers"
}'

A tool the model can use to extract URL context. This type has no other fields.

Example: URL context

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "tools": [{
    "type": "url_context"
  }],
  "input": "Summarize the page at https://example.com"
}'

A tool the model can use to operate a computer. It must be paired with a model that supports this capability, for example gemini-2.5-computer-use-preview-10-2025.

Example: computer use

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-2.5-computer-use-preview-10-2025",
  "tools": [{
    "type": "computer_use"
  }],
  "input": "Find a flight to Tokyo"
}'

An MCP server the model can call to perform actions.

Example: MCP server

Replace the server address, token, and tool names with your own.

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "tools": [{
    "type": "mcp_server",
    "name": "weather",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_TOKEN"
    },
    "allowed_tools": {
      "mode": "auto",
      "tools": ["get_forecast"]
    }
  }],
  "input": "What is the forecast for Boston tomorrow?"
}'

A tool the model can use to search Google.

Example: Google search

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "tools": [{
    "type": "google_search",
    "search_types": ["web_search"]
  }],
  "input": "What are the latest developments in solid-state batteries?"
}'

A tool the model can use to search files.

Example: file search

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "tools": [{
    "type": "file_search",
    "file_search_store_names": ["fileSearchStores/m64d1sevsr4y-xfyawui3fxqg"]
  }],
  "input": "Who is the author of the book?"
}'

A tool the model can use to query Google Maps.

Example: Google Maps

The coordinates are example values.

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "tools": [{
    "type": "google_maps",
    "enable_widget": true,
    "latitude": 37.7749,
    "longitude": -122.4194
  }],
  "input": "Find a good coffee shop near me"
}'

A tool the model can use to retrieve files.

No request example is available for this type.

InteractionSseEvent

When stream is true, both create and query push events as Server-Sent Events, distinguished by event_type. Every event can include an event_id. On query, pass the previous event_id as last_event_id to continue after that event.

`event_type`	Description	Main fields
`interaction.created`	Interaction created	`interaction`
`interaction.completed`	Interaction completed	`interaction`. `steps` is empty, and the body is assembled from the preceding `step.delta`
`interaction.status_update`	Status update	`interaction_id`, `status`
`error`	An error occurred	`error.code`, `error.message`
`step.start`	Step started	`index`, `step`
`step.delta`	Step delta	`index`, `delta`
`step.stop`	Step ended	`index`

A text reply arrives roughly in this order: interaction.created, then interaction.status_update (in_progress), then step.start, several step.delta, step.stop, and finally interaction.completed. There can be multiple steps in between.

Open an event_type to view the fields of that event.

step.delta's delta is also distinguished by type. Open a type to view its fields, purpose, and values.

{
  "event_type": "interaction.created",
  "interaction": {
    "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg",
    "model": "gemini-3-flash-preview",
    "status": "in_progress",
    "created": "2025-12-04T15:01:45Z",
    "updated": "2025-12-04T15:01:45Z"
  },
  "event_id": "evt_123"
}

Error handling

HTTP 400 parameter error

Scenario	Suggested handling
Neither `model` nor `agent` was passed	Provide one of the two
Mutually exclusive parameters were set on both `model` and `agent`	Use `generation_config` for a model, and `agent_config` for an agent
Unknown model name	Use a model ID from Model Plaza that is available to this API Key

HTTP 401 / 403 authentication error

401 Unauthorized: the API Key is invalid or expired
403 Forbidden: the API Key is not allowed to access this model (check the token's model allowlist)

HTTP 402 insufficient balance

Returns an insufficient balance error. Please top up in the AutoRouter console.

Interaction `failed` / `incomplete`

Status	Suggested handling
`failed`	Check `errors[].message` in the response, then adjust the input or safety settings and retry
`incomplete`	The result was truncated because the output limit was reached, or for a similar reason. You can increase `generation_config.max_output_tokens` and retry
`requires_action`	Run the function from the `function_call` in `steps`, then send the result back as the next turn's `input`

When an interaction fails, diagnostic information is in the errors array: code identifies the error type, and message is a human-readable description.

Interactions API (v1beta)

modelstring(conditional)

Available models

agentstring(conditional)

Available agents

inputstring | object | array(optional)

toolsobject[](optional)

Properties

generation_configobject(optional)

Properties

backgroundboolean(optional)

storeboolean(optional)

streamboolean(optional)

environmentstring | object(optional)

previous_interaction_idstring(optional)

safety_settingsobject[](optional)

Properties

service_tierstring(optional)

statusstring

stepsobject[]

usageobject

Properties

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

interaction.created

interaction.completed

interaction.status_update

error

step.start

step.stop

text

image

audio

document

video

thought_summary

thought_signature

text_annotation_delta

arguments_delta

On this page