Google AI Mode API

Endpoint

GET /v1/web/ai-mode

Parameters

prompt *

The AI Mode prompt (max 2000 characters)

country

2-letter ISO country code (default: us)

language

2-letter ISO language code (default: en)

session_token

Token from a previous response to continue the conversation

Response fields

reply_parts

Ordered list of typed reply parts; render in order to display the answer

reply_parts[].type

Part type: paragraph, heading, list, or images

reply_parts[].text

Text content (paragraph and heading parts)

reply_parts[].ordered

True for numbered lists (list parts)

reply_parts[].list

List items with title and text (list parts)

reply_parts[].images

Image array with url, label, width, height (images parts)

reference_links

Citation sources used in the reply

reference_links[].title

Citation title

reference_links[].link

Citation URL

reference_links[].snippet

Short preview of the cited source

reference_links[].source

Source name

reference_links[].favicon

Source favicon URL

reference_links[].date

Publication date (when available)

session_token

Token to pass in a subsequent request to continue this conversation

Example Request

curl "https://apidirect.io/v1/web/ai-mode?prompt=How%20do%20I%20make%20pizza%3F" \
  -H "X-API-Key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://apidirect.io/v1/web/ai-mode",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"prompt": "How do I make pizza?"}
)
data = response.json()

# Walk the reply_parts to display the answer
for part in data["reply_parts"]:
    if part["type"] in ("paragraph", "heading"):
        print(part["text"])
    elif part["type"] == "list":
        for item in part["list"]:
            print(f"- {item['title']} {item['text']}")

# Continue the same conversation
followup = requests.get(
    "https://apidirect.io/v1/web/ai-mode",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "prompt": "What about a gluten-free version?",
        "session_token": data["session_token"]
    }
)

Example Response

{
  "reply_parts": [
    {
      "type": "paragraph",
      "text": "Making pizza at home involves preparing the dough, sauce, and toppings, then baking at high heat."
    },
    {
      "type": "heading",
      "text": "1. Prepare the Dough"
    },
    {
      "type": "list",
      "ordered": false,
      "list": [
        {
          "title": "Activate Yeast:",
          "text": "Mix warm water with yeast and a pinch of sugar. Let it sit for 5-10 minutes until foamy."
        },
        {
          "title": "Mix and Knead:",
          "text": "Combine the yeast mixture with flour and salt. Knead for 5-10 minutes until smooth and elastic."
        }
      ]
    }
  ],
  "reference_links": [
    {
      "title": "Best Homemade Pizza Dough (photo tutorial)",
      "link": "https://www.crunchycreamysweet.com/the-best-homemade-pizza-dough-photo-tutorial/",
      "snippet": "Instructions. Place water and sugar in a large mixing bowl...",
      "source": "Crunchy Creamy Sweet",
      "favicon": "https://encrypted-tbn1.gstatic.com/faviconV2?url=https://www.crunchycreamysweet.com&size=128",
      "date": "Jul 6, 2012"
    }
  ],
  "session_token": "Q21vd1lUZHFaMjlNYWtOTWREQndWRmRyV1RNemFqRnViak01Ym1FeE1tdFZVemhFVGxCeFQxZE9RV1o0..."
}

Frequently asked questions

How is AI Mode different from a regular search?

AI Mode returns a conversational, structured answer generated by Google's AI model, along with citation links. Regular web search returns a list of ranked URLs.

How do I render the reply?

Walk reply_parts in order and render each block based on its type (paragraph, heading, list, images). The same structure is used by the AI Overview inside /v1/web/search.

How do I continue a conversation?

Every response includes a session_token. Pass that token back in your next call (along with the new prompt) to continue the same conversation with prior context preserved.

Is the session_token tied to my API key?

The token is opaque - treat it as a string you pass through unchanged. Each follow-up call is billed as a new $0.005 request.

What kinds of prompts work best?

AI Mode is designed for informational and how-to prompts. Questions like 'How do I...?', 'What's the difference between...?', or 'Explain X' work well. The prompt length is capped at 2000 characters.

How does pricing work?

You only pay for successful requests. The Google AI Mode API costs $0.005 per request. There are no monthly fees or commitments. You get 50 free requests per endpoint every month.

Do I need a credit card to start?

No. You can sign up and use the free tier (50 requests/endpoint/month) without adding a payment method. You only need to add a card when you want to exceed the free tier.

Are there rate limits?

Yes, there's a concurrency limit of 3 simultaneous requests per endpoint per user. If you need more, just get in touch.