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.
On this page
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). "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), 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). 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).
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; 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.
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).
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.
npx deepspace integrations invoke exa/search --body '{"query": "local bakeries opening 2026"}'
3. Set billing to the owner#
// 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).
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). 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.
// 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). To restrict image generation to the owner, return an error when env.OWNER_USER_ID is set and differs from userId (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).
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). 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).
7. Deploy and verify#
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) |
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). Confirm with your user before handling their key. Store changes reach a deployed app only at the next deploy.
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). 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.
Building this for a business? See deep.space/enterprise.