# AISTLabs

> AISTLabs is an AI studio for video, images and audio: top generation models in one place, with the credit price shown before each generation. Its AI director turns a product photo and a goal into a finished social video or ad, built on the brand's Brand Brain. Agents connect over MCP or REST (the source of truth; MCP exposes the same actions as tools) to make brand videos, manage Studio projects, find saved assets and favourites, and quote and run direct image, video or audio generation.

## Connect your agent

**Already have an API key?** Skip to step 3 and verify it with the authenticated
requests below. If they succeed, reuse that connection.

### 1. No key: request one link

```http
POST https://aistlabs.ai/api/v1/connect/requests
Content-Type: application/json

{"agentName": "ChatGPT Codex"}
```

No authorization is needed for this POST. Keep `pollUrl` and `pollToken` from
the response privately. Give the account owner `humanUrl` and ask them to
sign in and approve access. The link is valid for 60 minutes (`expiresAt`).

### 2. Wait for the owner's decision

Call the exact `pollUrl` from the POST response every 5–10 seconds:

```http
GET <pollUrl>
Authorization: Bearer <pollToken>
```

- `pending` does not mean the owner has signed in or granted access. Keep
  waiting; opening the link and signing in do not approve the request.
- `issued`: save `apiKey` in your secret manager immediately. It is returned only once,
  on the first poll after approval; later polls return `issued` with no key.
- `declined` or `expired`: stop polling and report that outcome to the owner.
  Do not create another request automatically.

Polling requires the POST response's `pollToken`, not an API key or browser
session. No token gives 401 `unauthorized`; a wrong token gives 404 `not_found`
to avoid disclosing another request. That 404 does not prove the request was lost.
Poll promptly after approval: an approved connection whose key was never
collected is revoked once `expiresAt` plus 15 minutes passes.

### 3. Verify access and restore context

With your existing or newly saved key, call these in order:

```http
GET https://aistlabs.ai/api/v1/last-activity
Authorization: Bearer <apiKey>
```

```http
GET https://aistlabs.ai/api/v1/me
Authorization: Bearer <apiKey>
```

Successful authenticated responses confirm access. Read `resume`, capabilities
and limits before doing work. Never paste `apiKey` or `pollToken` into chat.

### 4. First session with the owner

The goal of the first session is a first video, reached together with the
owner step by step — not automatically. MCP clients arrive here already
signed in: the client handled sign-in, so start at the access check.

1. **Confirm access with a real call**: `GET /api/v1/last-activity`, then
   `GET /api/v1/me` (MCP: `get_last_activity`, `get_me`).
2. **Look at what's available**: the actions you can take (OpenAPI or MCP
   `tools/list`), these docs, the owner's brands, capabilities (permissions),
   credit limits and balance (`/me`, `GET /api/v1/spend`).
3. **Tell the owner in 2–3 sentences what you can help with**, based on the
   capabilities this connection actually has — not a generic list.
4. **Ask which brand we're working on and what to make.** With one brand,
   propose it — don't pick it silently (a brand the owner started on the
   Create screen may have no name yet: `"name": "Your brand"`, `named: false`).
   With no brands, offer to create one and create it only after the owner
   agrees — a name and website are optional. If `resume` shows unfinished work,
   offer to continue it; a brief saved in AISTLabs is started as saved with
   `submit_brief_draft`, so nothing the owner entered is lost.
5. **Guide the owner to the first video, one step at a time**: the video needs
   only 1–3 products with a photo (`create_product` with `photoUrl`, or an
   upload link for a photo from the chat); brand name, Brand Brain and taste
   can come after the first video. Use what you
   already know about the company to fill gaps, ask one question at a time,
   show the brief (topic, format, length, language) and state the cost before
   starting the video — `create_content` writes the story and renders it in
   one go, there is no separate script approval.

Until the owner answers step 4, create, change and spend nothing. This is how
you work with a person, not a security mechanism: capabilities, limits and
approvals above them are enforced by the server on every call.

**Files from the chat.** Chat attachments don't reach AISTLabs tools by
themselves (MCP has no file channel). To get the owner's file into the brand:

- `create_upload` (`POST /api/v1/brands/{brandId}/uploads`) makes a one-time
  link for one role (logo, product photos, brand guidelines, brand visuals).
  Send the owner its `pageUrl`: they open it, drop the files and come back to
  the chat (if they are signed in to AISTLabs, it must be the account you are
  connected to). An agent that holds the file uploads it itself:
  `curl -T <file> '<uploadUrl>?name=<file name>'`.
- A public link that downloads the file itself (not a share or sign-in page):
  `import_from_url` (`POST /api/v1/brands/{brandId}/files/import`).
- ChatGPT attachments: `attach_file`.

The owner can also add files on the Brand page in AISTLabs (`https://aistlabs.ai/brand-brain`).
Then check that it's there (`get_upload`, or `GET /api/v1/brands/{brandId}/files`)
and continue. If a file didn't reach AISTLabs, say so in one sentence —
don't pretend you have it.


## Docs

- [Documentation index](https://aistlabs.ai/docs/index.md): every agent-facing guide
- [Connect — request access, verify it and run the first session with the owner](https://aistlabs.ai/docs/connect.md)
- [Quickstart — from API key to the first video](https://aistlabs.ai/docs/quickstart.md)
- [Workflow — states, nextAction and polling](https://aistlabs.ai/docs/workflow.md)
- [Brand Brain — sources, files, facts, products, taste](https://aistlabs.ai/docs/brand-brain.md)
- [Policies and limits — capabilities, budget, approvals](https://aistlabs.ai/docs/policies-and-limits.md)
- [Promo codes — trial credits and video downloads without a card](https://aistlabs.ai/docs/promo-codes.md)
- [OAuth 2.1 — discovery, registration, PKCE, tokens](https://aistlabs.ai/docs/oauth.md)
- [MCP — remote server over Streamable HTTP](https://aistlabs.ai/docs/mcp.md)
- [Studio — direct images and videos, exact quotes and saved results](https://aistlabs.ai/docs/studio.md)
- [Studio library — projects, favourites, assets and Elements](https://aistlabs.ai/docs/studio-library.md)
- [Webhooks — events, signature, retries](https://aistlabs.ai/docs/webhooks.md)
- [Errors — codes and what to do](https://aistlabs.ai/docs/errors.md)

## Machine-readable

- [OpenAPI](https://aistlabs.ai/openapi.json): REST contract for /api/v1
- [MCP server](https://aistlabs.ai/mcp): Streamable HTTP, Bearer API key or OAuth
- [OAuth resource metadata](https://aistlabs.ai/.well-known/oauth-protected-resource)
- [OAuth server metadata](https://aistlabs.ai/.well-known/oauth-authorization-server)

## Optional

- [Complete context](https://aistlabs.ai/llms-full.txt): all guides in one response