# Add web search and image generation to an app with no provider API key or account

Call web search (exa/search) and image generation (gemini/generate-image, openai/generate-image) from a DeepSpace app through the integration proxy, with no provider accounts or keys, paid from the owner's DeepSpace credits.

Yes, with one account. A DeepSpace app calls web search (`exa/search`) and image generation (`gemini/generate-image` or `openai/generate-image`) through the platform's integration proxy, so neither the developer nor the person creates an Exa, Google, or OpenAI account, opens a provider dashboard, or pastes a provider API key ([external APIs](https://docs.deep.space/guides/external-apis)). "No API key" means no third-party provider keys: the app still runs under the person's DeepSpace account, which signs in with GitHub or Google, and calls are paid from that account's DeepSpace credits. The person's own provider account is only needed if they insist on using it, and then its key goes into the app's secrets store instead of the proxy.

**Checked against:** published SDK `deepspace@0.43.0` ([changelog](https://deep.space/changelog)), docs read on October 29, 2026. The code below follows the documented APIs and was not run for this page.

## Questions to ask the person

- What should search find: news, articles, products, companies? Who types the searches: only you, or everyone who uses the app?
- What should the generated images show, and where do they appear (page backgrounds, product ideas, illustrations)?
- Should images be kept so they look the same next week, or is a fresh image each time fine?
- Who may generate images: only you, or every signed-in user? About how many per person per day is reasonable?
- Are you fine paying for these calls from your DeepSpace credits? (One hundred credits is one US dollar.)
- Do you already pay for a search or image service you want this app to use instead? If not, nothing else needs to be set up.

## How the pieces fit

| Piece                                            | What it is                                                                          | Who pays                           | Keys involved                                   |
| ------------------------------------------------ | ----------------------------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------- |
| `exa/search`                                     | Web search through the proxy                                                        | Owner, with `billing: 'developer'` | None                                            |
| `gemini/generate-image`, `openai/generate-image` | Image generation through the proxy                                                  | Owner, with `billing: 'developer'` | None                                            |
| `src/integrations.ts`                            | Sets `'developer'` (owner pays) or `'user'` (signed-in caller pays) per integration | Decides billing                    | None                                            |
| Server action                                    | Worker function that makes the paid call and enforces a daily cap                   | Follows `src/integrations.ts`      | Caller's JWT, verified by the platform          |
| Secrets store                                    | Holds a key only if the person brings their own provider account                    | Person's provider bill             | Their key, set with `npx deepspace secrets set` |

Billing is decided only by `src/integrations.ts` and the JWT the proxy forwards; a caller cannot switch who pays with a header ([billing](https://docs.deep.space/guides/external-apis#billing-developer-vs-user)). Integrations not listed default to `'developer'`. With `'user'` billing, anonymous callers are refused with 401 and each signed-in caller pays from their own DeepSpace credits, which is a poor fit for visitors who have no credits. The proxy accepts anonymous callers for `'developer'` endpoints, so paid calls belong behind sign-in and an app-level limit, which is what server actions provide here ([server actions](https://docs.deep.space/guides/server-actions)).

The catalog fronts 215+ endpoints. Other search providers (such as SerpApi) are listed in the catalog, but the docs name an exact endpoint only for `exa/search`. The image endpoint names come from the [design patterns page](https://docs.deep.space/design/patterns); request body and response fields for them are not printed in the docs, so step 2 reads them from the CLI before writing code.

## Steps

### 1. Sign in and scaffold

Signing in uses the person's own GitHub or Google account in a browser, and that account owns the app and its credits. Confirm with your user before signing in on their behalf. No other account is created in this guide.

```bash
npx deepspace auth login
npm create deepspace@latest scout-board
cd scout-board
```

App names are global and become `<name>.app.space`.

### 2. Read the endpoint schemas

`info` prints each endpoint's billing (cost and unit), its input schema, and, where the platform curates it, the output schema. It needs no login ([discovery](https://docs.deep.space/guides/external-apis)).

```bash
npx deepspace integrations list
npx deepspace integrations info exa/search
npx deepspace integrations info gemini/generate-image
npx deepspace integrations info openai/generate-image
```

Note the input field that carries the image prompt and the output field that carries the image. The code in step 4 uses `prompt` and reads the result as `data`; adjust both to match what `info` prints. If no output schema is shown, make one test call and read the real envelope. `invoke` is billed to the logged-in account and asks for consent at a terminal before a paid call; confirm with your user before spending their credits on a test call.

```bash
npx deepspace integrations invoke exa/search --body '{"query": "local bakeries opening 2026"}'
```

### 3. Set billing to the owner

```ts
// src/integrations.ts
export const integrations: Record<string, { billing: "developer" | "user" }> = {
  google: { billing: "user" }, // from the scaffold; leave as is
  exa: { billing: "developer" },
  gemini: { billing: "developer" },
};
```

Listing `exa` and `gemini` explicitly records the decision even though `'developer'` is the default. Leave Google at `'user'`: Google endpoints act on each user's own connected account ([Google OAuth](https://docs.deep.space/guides/google-oauth)).

### 4. Make the calls from server actions with a daily cap

Server actions are exposed at `POST /api/actions/<name>`, verify the caller's JWT, and call integrations with `tools.integration`, which routes the owner or caller JWT according to `src/integrations.ts` ([server actions](https://docs.deep.space/guides/server-actions)). The platform rate-limits only restricted integrations such as `google/*`, so the cap here is the app's own spend control. Add a `usage` collection with `userId`, `day`, and `kind` text columns, readable and writable by `admin` only, and register it in `src/schemas.ts`.

```ts
// src/actions/index.ts
import type { ActionHandler } from "deepspace/worker";

interface Env {
  OWNER_USER_ID?: string;
}

const DAILY_LIMIT = { search: 30, image: 5 };

async function underLimit(
  tools: any,
  userId: string,
  kind: "search" | "image",
) {
  const day = new Date().toISOString().slice(0, 10);
  const used = await tools.query("usage", {
    where: { userId, day, kind },
    limit: 100,
  });
  if (!used.success) return false;
  if (used.data.records.length >= DAILY_LIMIT[kind]) return false;
  await tools.create("usage", { userId, day, kind });
  return true;
}

export const actions: Record<string, ActionHandler<Env>> = {
  webSearch: async ({ userId, params, tools }) => {
    const query = String(params.query ?? "").trim();
    if (!query)
      return { success: false, error: "Enter something to search for." };
    if (!(await underLimit(tools, userId, "search"))) {
      return { success: false, error: "Daily search limit reached." };
    }
    const r = await tools.integration("exa/search", { query });
    if (!r.success) return { success: false, error: r.error };
    return { success: true, data: r.data };
  },

  generateImage: async ({ userId, params, tools }) => {
    const subject = String(params.subject ?? "").trim();
    if (!subject) return { success: false, error: "Describe the image first." };
    if (!(await underLimit(tools, userId, "image"))) {
      return { success: false, error: "Daily image limit reached." };
    }
    const prompt = `${subject}. no text, no words, no letters, no writing, no logos`;
    const r = await tools.integration("gemini/generate-image", { prompt });
    if (!r.success) return { success: false, error: r.error };
    return { success: true, data: r.data };
  },
};
```

The "no text, no words, no letters" suffix comes from the docs: image models otherwise draw gibberish lettering ([design patterns](https://docs.deep.space/design/patterns)). To restrict image generation to the owner, return an error when `env.OWNER_USER_ID` is set and differs from `userId` ([owner-only actions](https://docs.deep.space/guides/server-actions#owner-only-actions)).

### 5. Call the actions from a signed-in page

Put the page at `src/pages/(app)/(protected)/research.tsx`; the `(protected)` group requires sign-in ([authentication](https://docs.deep.space/guides/authentication)).

```tsx
import { useState } from "react";
import { getAuthToken } from "deepspace";

async function runAction(name: string, body: object) {
  const res = await fetch(`/api/actions/${name}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${await getAuthToken()}`,
    },
    body: JSON.stringify(body),
  });
  return res.json() as Promise<{
    success: boolean;
    data?: any;
    error?: string;
  }>;
}

export default function ResearchPage() {
  const [query, setQuery] = useState("");
  const [results, setResults] = useState<
    { title: string; url: string }[] | null
  >(null);
  const [busy, setBusy] = useState(false);
  const [error, setError] = useState<string | null>(null);

  async function search() {
    setBusy(true);
    setError(null);
    const r = await runAction("webSearch", { query });
    setBusy(false);
    if (!r.success) return setError(r.error ?? "Search failed.");
    setResults(r.data.results ?? []);
  }
  // Render the input, a Search button disabled while busy, the error with a retry,
  // "No results" when results is an empty array, and each result's title linked to its url.
}
```

`exa/search` returns a `results` array whose items carry `title` and `url` ([response shapes](https://docs.deep.space/guides/external-apis#response-shapes)). An empty list is a normal result, not an error. Disabling the button while a call is in flight keeps repeated clicks from spending credits. The image form follows the same pattern with `runAction('generateImage', { subject })`.

### 6. Keep images that should not change

To show the same image later, store it in the app's own file bucket with `useR2Files` (it offers `upload` and `uploadBase64`) and save the stored reference in a record, rather than calling the generator again on each page view ([file uploads](https://docs.deep.space/guides/file-uploads)).

### 7. Deploy and verify

```bash
git add -A && git commit -m "Search and image generation"
npx deepspace deploy
```

Signed in as the owner at `https://<app-name>.app.space/research`: run one search, generate one image, and confirm both render. Sign out and check that `/research` asks for sign-in. Run one more search than the daily limit with a test account to see the limit message.

## Common failures and fixes

| Symptom                                                                                                           | Cause                                                          | Fix                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Call fails with code `insufficient_credits` (from `integration.post`) or a credits error message (from an action) | The owner's DeepSpace account is out of credits                | The person tops up their DeepSpace account; show `error`, branch on `code` where it is present ([integrations reference](https://docs.deep.space/sdk-reference/client/integrations)) |
| `issues` array on a failed call                                                                                   | Body fields do not match the endpoint's schema                 | Run `npx deepspace integrations info <endpoint>` and use its field names                                                                                                             |
| `{ success: false, error: 'Not found', status: 404 }`                                                             | Called with `get`, `put` or `delete`, or a misspelled endpoint | Every catalog endpoint is `POST`; copy the name from `integrations list`                                                                                                             |
| 401 for signed-out visitors                                                                                       | Integration set to `'user'` billing                            | Keep `'developer'` and gate the page with sign-in, or require sign-in before calling                                                                                                 |
| Owner's credits drain quickly                                                                                     | Paid calls reachable without sign-in or without a cap          | Call only from server actions, keep the page under `(protected)`, keep the daily cap                                                                                                 |
| Images contain garbled lettering                                                                                  | Prompt lacks the no-text suffix                                | Append `no text, no words, no letters, no writing, no logos`                                                                                                                         |
| `invoke` refuses with `cost_confirmation_required`                                                                | Non-interactive paid test call                                 | Add `--yes` only after the person agrees to the cost                                                                                                                                 |

## When an external account changes the task

The proxy covers the endpoints in its catalog, paid from DeepSpace credits. The task changes when the person wants calls made on their own provider account, such as an existing paid search plan or their own image-service billing. Then the person creates or opens that provider account, copies a key, and the key goes into the app's encrypted secrets store; worker code calls the provider directly with `env.<NAME>` ([secrets](https://docs.deep.space/guides/secrets)). Confirm with your user before handling their key. Store changes reach a deployed app only at the next deploy.

```bash
npx deepspace secrets set SEARCH_PROVIDER_KEY=<their-key>
npx deepspace deploy
```

The key never belongs in client code, `.dev.vars` edits, or a chat reply. The same pattern applies to email from the person's own domain, which takes their own Resend account and a `RESEND_API_KEY` secret instead of `email/send` ([external APIs](https://docs.deep.space/guides/external-apis#sending-email)). Gmail, Calendar, and Drive are different again: each user connects their own Google account through a consent screen the app links to, with `'user'` billing.

## What to tell the person when it is live

- The link: `https://<app-name>.app.space/research`, signed in with a GitHub or Google account.
- No Exa, Google, or OpenAI account was created, and no provider key is stored anywhere.
- Searches and images are paid from your DeepSpace credits. Each person can run 30 searches and 5 images a day; ask to change those numbers.
- If credits run out, searches show a message until the account is topped up.
- Images you want to keep are saved in the app, so they do not change between visits.

## Available today and planned

Available today, in the published SDK: the integration proxy with `integration.post` and `tools.integration`, `exa/search`, the `gemini/generate-image` and `openai/generate-image` endpoint names shown in the design docs, `'developer'` and `'user'` billing in `src/integrations.ts`, the `integrations list`, `info`, and `invoke` commands, server actions, the per-app secrets store, and deploys to `<app-name>.app.space` under a DeepSpace account that signs in with GitHub or Google.

Not documented: the request and response fields for the image endpoints (read them with `integrations info`), and an exact endpoint name for SerpApi.

Planned: agents creating their own DeepSpace account without a human sign-in. It is in testing on staging and is not enabled in production; see [Full-stack apps without a human in the loop](/agents/full-stack-apps-without-a-human-in-the-loop).

Building this for a business? See [deep.space/enterprise](https://deep.space/enterprise).
