---
title: "How to Serve a Typed AI Endpoint with Pixeltable"
date: "2026-09-25"
author: "Pierre Brunelle"
tags:
  - Serving
  - FastAPI
  - OpenAPI
  - TypeScript
  - Next.js
  - Pixeltable Cloud
  - API Keys
  - TableModel
description: "Turn a Pixeltable table into a typed HTTP endpoint: serve it locally, deploy it to Pixeltable Cloud, and call it from Next.js with generated TypeScript types."
url: "https://pixeltable.com/blog/serve-typed-ai-endpoint-pixeltable"
---

# How to Serve a Typed AI Endpoint with Pixeltable

**Summary:** A Pixeltable service turns tables into HTTP routes. You declare the table and its routes in one `app.py`, run two commands to serve it locally, and three to host it on Pixeltable Cloud. Every service publishes an OpenAPI schema, so a TypeScript app gets generated types for every route, and a hosted service accepts only requests that carry a Pixeltable API key. This post walks the whole path, from the table to a typed call in a Next.js app.

 
The reference docs are [HTTP serving](https://docs.pixeltable.com/howto/deployment/serving) and [Deploy to Pixeltable Cloud](https://docs.pixeltable.com/howto/deployment/cloud). Everything below uses Pixeltable 0.7.11 or later.

 
## What a service gives you

 
A route is a table operation exposed over HTTP. You choose the operation and the columns; Pixeltable writes the handler, the request and response models, and the schema.

 
| Route | What a request does | Typical use |
| --- | --- | --- |
| add_insert_route | Inserts a row, runs its computed columns, returns the outputs you list | Ingest a document, an image, a transcript |
| add_compute_route | Runs the computed columns without storing a row | Classify, summarize, or embed on demand |
| add_update_route | Updates a row by key and recomputes what depends on it | Correct a field, rerun a model |
| add_delete_route, query routes | Delete rows, or return the rows a query selects | Cleanup, search, lookups |

 
Routes can accept file uploads, return a file instead of JSON (`return_fileresponse=True`), or run in the background and return a job handle (`background=True`).

 
## Declare the table and its routes

 
This is the Quickstart application. `pxt service example --out app.py` writes it for you.

 
```python
import pixeltable as pxt
import pixeltable.functions as pxtf
from pixeltable.serving import FastAPIRouter

TableModel = pxt.model_base()

@pxt.udf
def excerpt(text: str, n: int = 12) -> str:
 return text if len(text) <= n else f'{text[:n]}...'

class Docs(TableModel, name='docs'):
 id = pxt.Column(value=pxtf.uuid.uuid7(), primary_key=True)
 title: pxt.String
 body: pxt.String | None
 title_upper = pxtf.string.upper(title)
 summary = excerpt(title)

ingest = FastAPIRouter(name='ingest')
ingest.add_insert_route(
 Docs, path='/docs', inputs=[Docs.title, Docs.body], outputs=[Docs.id, Docs.title_upper, Docs.summary]
)
ingest.add_update_route(
 Docs, path='/docs/update', inputs=[Docs.title], outputs=[Docs.id, Docs.title_upper]
)
ingest.add_compute_route(Docs, path='/titles', inputs=[Docs.title], outputs=[Docs.title_upper])
```

 
Each column named in `outputs` becomes a typed field of the response, computed columns included. Swap `pxt.String` for `pxt.Image`, `pxt.Video`, `pxt.Audio`, or `pxt.Document` and the same routes serve a media pipeline.

 
## Serve it locally

 
```bash
pip install -U 'pixeltable[serve]'
pxt init
pxt schema update app.py my_app -f
pxt service update app.py my_app -f
pxt service list my_app --json
```

 
`pxt schema update` creates the tables; it does not start HTTP. `pxt service update` starts HTTP; it does not create tables. Pass `-f` whenever a script, CI job, or coding agent runs these commands: without a terminal to confirm in, commands that change things refuse to proceed.

 
The service gets its own port, so read the endpoint from `pxt service list --json` rather than assuming port 8000. Interactive docs are at `/docs` and the schema at `/openapi.json`. A local service needs no key.

 
## Deploy the same file to Pixeltable Cloud

 
Pixeltable Cloud is in Limited Beta; email [contact@pixeltable.com](mailto:contact@pixeltable.com) for an account. Sign in with `pxt login`, or create an API key in the dashboard and export it as `PIXELTABLE_API_KEY`. A key in the environment or in the config file takes precedence over a `pxt login` session, so remove a stale one before you sign in.

 
Name the hosted database in `pixeltable.toml`:

 
```toml
[[pixeltable.database]]
name = 'pxt://acme:prod'
```

 
Then run the three commands:

 
```bash
pxt db update pxt://acme:prod -f
pxt schema update app.py pxt://acme:prod -f
pxt service update app.py pxt://acme:prod -f
```

 

 - `pxt db update` creates the database and uploads the project. It rebuilds the image only when your dependencies changed, which is the slow step; a code change is just an upload.

 - `pxt schema update` creates the tables in the hosted database.

 - `pxt service update` starts the hosted service.

 

 
The hosted image installs the Pixeltable version your lockfile (`uv.lock` or `requirements.txt`) pins, so pin 0.7.11 or later there too. `pxt service list pxt://acme:prod --json` prints the service URL, and `pxt service diff app.py pxt://acme:prod` shows what would change before you apply it. The docs list [what to run after each kind of change](https://docs.pixeltable.com/howto/deployment/cloud#what-to-run-after-a-change).

 
## Give your app its own key

 
Your app server needs a key that does not expire and does no more than the app needs. Create one per app and environment:

 
```bash
pxt key create my-app --grant access:pxt://acme:prod/services/ingest
```

 
With the grant, the key belongs to the organization and can call the `ingest` service and nothing else. It cannot list services, reconfigure them, or reach another database. Keys with grants are a preview; until your organization has them, omit `--grant` for a key that acts as you. The secret prints once. Store it in your app server's environment as `PIXELTABLE_API_KEY`, never under a `NEXT_PUBLIC_` name that would ship it to the browser. See [`pxt key`](https://docs.pixeltable.com/platform/cli#pxt-key) for the full grant table.

 
## Generate TypeScript types from the schema

 
A hosted schema needs the key to download. It declares the `X-api-key` header on every route, so generated clients know how to authenticate:

 
```bash
export PIXELTABLE_SERVICE_URL='https://…' # the endpoint from pxt service list
curl -fsS -H "X-api-key: $PIXELTABLE_API_KEY" "${PIXELTABLE_SERVICE_URL%/}/openapi.json" -o openapi.json
npx openapi-typescript openapi.json -o src/pixeltable.d.ts
```

 
File responses are typed as binary, and the background job status route is in the schema, so polling is typed too. Regenerate the file whenever the Python routes change, and let your TypeScript check catch any mismatch before you deploy.

 
## Call it from a Next.js server

 
Generated types do not check a raw `fetch`, so call routes through `openapi-fetch`. Run `npm install openapi-fetch server-only` and add `src/lib/pixeltable-client.ts`:

 
```typescript
import 'server-only';
import createClient from 'openapi-fetch';
import type { paths } from '../pixeltable';

const apiKey = process.env.PIXELTABLE_API_KEY;

export const pixeltable = createClient<paths>({
 baseUrl: process.env.PIXELTABLE_SERVICE_URL,
 headers: apiKey ? { 'X-api-key': apiKey } : {},
 cache: 'no-store',
});

export class PixeltableError extends Error {
 status: number;
 body: unknown;
 constructor(status: number, body: unknown) {
 super(`Pixeltable service returned HTTP ${status}`);
 this.status = status;
 this.body = body;
 }
}

export async function computeTitle(title: string) {
 const { data, error, response } = await pixeltable.POST('/titles', { body: { title } });
 if (error !== undefined || !response.ok) throw new PixeltableError(response.status, error);
 return data; // typed from the service schema
}
```

 
The key is set once on the client, so no call has to pass it. `import 'server-only'` makes the build fail if a client component imports the module. Call it from a Server Action:

 
```typescript
// src/app/actions.ts
'use server';
import { computeTitle } from '@/lib/pixeltable-client';

export async function titleCase(title: string) {
 // check your own user session here before exposing a write route
 const result = await computeTitle(title);
 // compute routes are typed nullable: a view filter can drop the row
 return result?.title_upper ?? null;
}
```

 
The same module calls a local service: point `PIXELTABLE_SERVICE_URL` at the local endpoint and leave `PIXELTABLE_API_KEY` unset. A deployment on Vercel or any other host needs the hosted endpoint, since it cannot reach your laptop. In the Cloud dashboard, the service page's **API docs** lets you try every route as your signed-in user, and **Use this endpoint** gives server-side snippets.

 
## Handle errors and retries

 
`PixeltableError.body` is the parsed error response. Branch on the shape of its `detail`, not on the status:

 
| detail is | When |
| --- | --- |
| An object with error_code, message, retryable, sometimes retry_after | A Pixeltable runtime error, or an error the Cloud gateway answers itself |
| A string | A missing row |
| An array | A request that failed validation |

 
The gateway answers these itself, with the same object:

 
| Status | Meaning | Retry? |
| --- | --- | --- |
| 401 | Missing or invalid key | No: fix the key |
| 403 | The key has no access to this service | No: add a grant |
| 404 | No service at this URL | No: check the endpoint |
| 429 | The key is rate limited | Yes, after Retry-After |
| 503 | The service is not running | Yes |

 
Retry a write only when `detail.retryable` is true, waiting `retry_after` seconds when it is present. That one rule covers service and gateway errors alike.

 
## Files, uploads, and background jobs

 

 - **File responses.** A `return_fileresponse=True` route needs `parseAs: 'blob'`, or `parseAs: 'stream'` to pipe the body through your Route Handler with the upstream `Content-Type`. Without it the client tries to parse the file as JSON.

 - **Uploads.** Generated types describe upload fields as strings, so send uploads with `fetch`, a `FormData` body, and the same `X-api-key` header. Let `fetch` set the multipart boundary.

 - **Background jobs.** A `background=True` route returns an `id` and a `job_url` right away. Polling is a typed call on the same client: `pixeltable.GET('/_pxt/jobs/{job_id}', { params: { path: { job_id: id } } })` returns `pending`, `done` with the result, or `error` with an `error_detail` that follows the same retry rule.

 - **Media outputs.** Image and video URLs in a hosted JSON response are signed and expire after an hour. Render them directly; do not store them.

 

 
## Secrets, logs, and changes

 
Provider keys such as `OPENAI_API_KEY` are secrets, not API keys. Set them in the dashboard or with the CLI, then restart so the service reads them:

 
```bash
pxt secret set pxt://acme:prod OPENAI_API_KEY=...
pxt db restart pxt://acme:prod
pxt service logs ingest
```

 
A database secret overrides an organization secret of the same name. After a code change, run `pxt db update` and then `pxt service update`; after a column change, add `pxt schema update` between them.

 
## The checklist

 

 - Pin Pixeltable 0.7.11 or later in the project's lockfile.

 - Serve locally first, with `-f` in anything scripted.

 - Sign in with `pxt login`, or export one API key; a stored key wins over the login.

 - Deploy with `pxt db update`, `pxt schema update`, `pxt service update`.

 - Create one key per app and environment, granted only the service it calls.

 - Generate types from the hosted schema and regenerate after every route change.

 - Call the service from server code only, through the typed client.

 - Check from outside: a request without the key returns 401 with a JSON `detail`, and one with the key returns 200.

 - Retry only when `detail.retryable` is true.

 - Set provider secrets, then restart the database.

 

 
Full reference: [HTTP serving](https://docs.pixeltable.com/howto/deployment/serving), [Deploy to Pixeltable Cloud](https://docs.pixeltable.com/howto/deployment/cloud), and the [CLI](https://docs.pixeltable.com/platform/cli). For why the same file runs locally and in the cloud, read [why the local-cloud loop matters](/blog/why-local-cloud-loop-matters).