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

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 on the Search API screen of your SpecStream workspace. New accounts start with $10 of credit, no card.

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. Ask the agent for a search route

In the Build chat, send:

In the AI Studio Build chat

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. Check the server code

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

Server code
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. 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. 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).

Who pays

The published app calls SpecStream with your key, so every visitor spends from your balance. In Agents & API, 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 [email protected].

SpecStream for Google AI Studio covers what it does in Google AI Studio on one page. Every other tool has its guide in Connect your tools. You see the most a request can cost before it starts, and the matches are paid from your balance. Billing has the details. For help, email [email protected].