> SpecStream is the live web data engine for teams and agents. This is the Markdown copy of https://specstream.ai/docs/integrations/google-ai-studio. Every page, with what SpecStream does and costs: https://specstream.ai/llms.txt

# Google AI Studio

Give an app you build in Google AI Studio live web search. Store your SpecStream key as a secret, ask the agent for one server route, and the app gets answers and sources from the live web while the key stays on the server.

[SpecStream for Google AI StudioAgent frameworks & builders](https://specstream.ai/integrations/google-ai-studio.md)

## What you need

-   A web app in Google AI Studio's Build mode. Web apps get a Node.js server, which is where the key is used.
-   A SpecStream key. [Get your key](https://specstream.ai/workspace/search?utm_source=google-ai-studio&utm_medium=howto) on the Search API screen of your SpecStream workspace. New accounts start with $10 of credit, no card.

1.  1

    ## 1. Add your key as a secret

    Open your app in Build mode, open the **Settings** menu and find the **Secrets** section. Add a secret named `SPECSTREAM_API_KEY` with your SpecStream key as its value.

    Server code reads secrets as environment variables, and AI Studio keeps them out of the code the browser loads. If you send the prompt below first, the agent shows a card in the chat that asks for the key when it finds the new variable.

2.  2

    ## 2. Ask the agent for a search route

    In the Build chat, send:

    In the AI Studio Build chat

    ```text
    Add a server route POST /api/search. It reads { q } from the request body and calls POST https://api.specstream.ai/v1/web-search with the header Authorization: Bearer followed by process.env.SPECSTREAM_API_KEY, and the JSON body { q, num: 10 }. Return data.answer and data.sources from the reply. Never send the key to the browser. Add a search box that calls /api/search and shows the answer value with a link to answer.page, then each source's title, url and snippet.
    ```

3.  3

    ## 3. Check the server code

    Open the **Code** tab in the preview pane. The route the agent writes should come down to this:

    Server code

    ```typescript
    export async function searchWeb(q: string) {
      const reply = await fetch("https://api.specstream.ai/v1/web-search", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.SPECSTREAM_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ q, num: 10 }),
      })
      const body = await reply.json()
      if (!reply.ok) {
        throw new Error(body.error?.message ?? `SpecStream ${reply.status}`)
      }
      return { answer: body.data.answer, sources: body.data.sources }
    }
    ```

4.  4

    ## 4. Try it in the preview

    Type a question about something from this week into the search box in the preview. The answer shows with the page it was read from, and the sources list below it. Every reply is `{"data": {...}}`, or `{"error": {...}}` when a call stops, so the app reads every field inside `data`.

5.  5

    ## 5. Publish

    Click **Publish** in the top right corner. The published app runs the same server route on Cloud Run with a public URL, and every visitor's search runs on your key. If the published app answers 401 with `missing_api_key`, the secret did not reach the server: check it under **Secrets** and publish again.

## What comes back

`data.answer` holds the `value` as the pages print it, the `page` it was read from, every result that prints it in `sources` and the read time in `seen_at`. It is empty when no page prints one answer, for example for a request for a list. `data.sources` lists every search result read, in rank order, with `url`, `title`, `site`, `snippet` and the `published` date when the page states one.

## Give Gemini the pages

To have Gemini write from the live web, send `passages: true` in the body. Each source then carries an `excerpt`: the text of its page closest to the question, up to about 3,500 characters. Ask the agent:

## Read whole pages

For the full text of a page, the server posts to `https://api.specstream.ai/v1/extract` with `{"urls": ["<page>"], "format": "markdown"}` and the same header. One call reads up to 20 pages or documents, PDF, Word and Excel included, and `data.results` holds each page's `text`. Each page is $0.80 per 1,000 pages, and a page with no text is not charged.

## Compared with Grounding with Google Search

Gemini's own Google Search tool gives 5,000 free search requests per month, shared across Gemini 3 and newer models, then costs $14 per 1,000 requests, with a cap of 1,500 requests per day (Gemini API pricing, read November 12, 2026).

A SpecStream search costs $5 per 1,000 searches of up to 10 results. It returns the answer with its page and every source as data your code reads, stores and shows, and it works beside any model. SpecStream's Search API scores 97.9 F-score on all 1,000 SimpleQA Verified questions ([benchmarks](https://specstream.ai/benchmarks.md)).

## Who pays

The published app calls SpecStream with your key, so every visitor spends from your balance. In [Agents & API](https://specstream.ai/workspace/agents?tab=keys&utm_source=google-ai-studio), give the key a total spending limit. Calls past it stop with 403 until you raise it.

With Firebase Authentication in the app, cap each signed in user too: send `X-End-User-Id` with the user's ID and `X-End-User-Cap-Cents` with the most that user may spend in the month, in cents. A call past the cap gets 402. SpecStream keeps only a hash of the ID.

## If something doesn't work

| What you see | What to do |
| --- | --- |
| 401 with `missing_api_key` | The server sent no key. Check that the secret is named `SPECSTREAM_API_KEY` in **Secrets** and that the route reads that name. |
| 401 with `invalid_token` | The key is mistyped, expired or revoked. Create a new key and replace the secret. |
| 402 with `insufficient_balance` | The balance is empty. Add balance in your SpecStream workspace. |
| 403 | The key cannot spend, or it reached its limit. Use a key from the Search API screen, or raise its limit under **Agents & API**. |
| 503 with `Retry-After` | The account used its calls for the minute. Retry after that many seconds. Nothing is charged. |
| `answer` is null | No page printed one answer. Show the `sources` instead, or ask a narrower question. |

## Cost

Each search is one Search API call at $5 per 1,000 searches of up to 10 results. It comes out of your balance, with no quote and no approval, and a call that returns no results costs nothing. With `speed: "fast"` in the body, a search costs a fifth as much and returns sources with no answer. The reply's `price_usd` shows what each call cost. New accounts start with $10 of credit, no card.

## Remove

Delete the `SPECSTREAM_API_KEY` secret and the route. Revoking the key under **Agents & API** stops every app that holds it at once. Questions go to [support@specstream.ai](mailto:support@specstream.ai).

## More

[SpecStream for Google AI Studio](https://specstream.ai/integrations/google-ai-studio.md) covers what it does in Google AI Studio on one page. Every other tool has its guide in [Connect your tools](https://specstream.ai/docs/integrations.md). You see the most a request can cost before it starts, and the matches are paid from your balance. [Billing](https://specstream.ai/docs/billing.md) has the details. For help, email [support@specstream.ai](mailto:support@specstream.ai).