# tscaps: instructions for AI agents

You are helping a person add animated captions (subtitles burned into the video, word by word) to their videos with tscaps. Follow these steps in order. Use any HTTP tool you have: `curl`, `fetch`, Python `requests`.

- API: `https://staging-api.tscaps.io`
- Every request and response body is JSON.
- Send the API key as `Authorization: Bearer <key>`.

## 1. Get an API key

If `TSCAPS_API_KEY` is already set in the environment, or in a `.env` file in the project, use it and go to step 2.

Otherwise, ask tscaps for a key. The person approves it in their browser with one click; you never ask them to copy a key.

```bash
curl -s -X POST https://staging-api.tscaps.io/v1/api-key-requests \
  -H "Content-Type: application/json" \
  -d '{"client": "<your name, for example Claude Code, Cursor or Codex>"}'
```

The response:

```json
{
  "code": "WDJB-MJHT",
  "approvalUrl": "https://staging.tscaps.io/app/developers/connect?code=WDJB-MJHT",
  "pollToken": "tscaps_kr_...",
  "pollIntervalSeconds": 5,
  "expiresAt": "2026-11-12T20:15:00.000Z"
}
```

Show the person the link and the code, in one short message. For example:

> To caption your video I need a tscaps API key. Open this link and click **Approve**: https://staging.tscaps.io/app/developers/connect?code=WDJB-MJHT
> Check that the page shows the code **WDJB-MJHT**. If you have no tscaps account, you can sign up there for free. A free account includes 5 automation minutes per month.

If you can open a browser for the person (for example with `open` on macOS or `xdg-open` on Linux), you may also open the link for them.

Then poll, waiting `pollIntervalSeconds` seconds between calls. Keep the `pollToken` secret.

```bash
curl -s -X POST https://staging-api.tscaps.io/v1/api-key-requests/poll \
  -H "Content-Type: application/json" \
  -d '{"pollToken": "<pollToken>"}'
```

The response always has a `status`:

| `status` | What to do |
| --- | --- |
| `pending` | The person has not answered yet. Wait and poll again. The request expires after about 15 minutes. |
| `approved` | The response has `apiKey.token` (`tscaps_sk_...`). It is sent **only once**: save it now. |
| `denied` | The person refused. Stop and tell them. |
| `expired` | Nobody answered in time. Ask the person whether to start again with a new request. |
| `redeemed` | The key was already sent in an earlier response. Use the key you saved. |

When the key arrives:

- Save it as `TSCAPS_API_KEY=<token>` in the project's `.env` file (create the file if needed). Make sure `.env` is in `.gitignore`.
- Never print the full key in the chat, never put it in source code, and never commit it.
- The person can see and delete the key at https://staging.tscaps.io/app/developers/keys.

## 2. Give tscaps the video

**The video has a public URL** (a direct link to the file, not a web page that plays it): use it as `videoUrl` in step 3.

**The video is a local file**: upload it first.

```bash
# a) Ask for an upload URL. sizeBytes must be the exact file size.
curl -s -X POST https://staging-api.tscaps.io/v1/automation-jobs/uploads \
  -H "Authorization: Bearer $TSCAPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName": "video.mp4", "sizeBytes": 14205000}'
# → { "uploadId": "...", "uploadUrl": "https://...", "contentType": "video/mp4", ... }

# b) PUT the raw bytes to uploadUrl. No Authorization header, no multipart form.
#    Content-Length must equal sizeBytes (curl sets it from the file).
curl -s -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" --data-binary @video.mp4
```

Then use the `uploadId` in step 3.

## 3. Start the job

```bash
curl -s -X POST https://staging-api.tscaps.io/v1/automation-jobs \
  -H "Authorization: Bearer $TSCAPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"uploadId": "<uploadId>", "templateId": "mira"}'
# or: -d '{"videoUrl": "https://example.com/video.mp4", "templateId": "mira"}'
# → 201 { "id": "...", "status": "queued" }
```

`templateId` is the caption style. Use `mira` unless the person asked for a look. Some others:

| `templateId` | Look |
| --- | --- |
| `mira` | Clean modern sans-serif with a soft outline. Works for any video. |
| `enzo` | Heavy sans-serif with italic serif accents on key words. |
| `loki` | Comic-book capitals with a thick outline and a bouncy entrance. |
| `nova` | Two lines: a large yellow headline over white body text. |
| `naya` | Bold condensed capitals with emojis. |
| `lewis` | One word at a time with neon accents and emojis. |
| `vera` | Business style on a dark strip with a blue highlight. |

The full list, with a description of each: https://github.com/francozanardi/tscaps/blob/main/skills/tscaps-api/references/templates.md. The person can also design a style in the tscaps editor, save it, and give you its ID from https://staging.tscaps.io/app/developers/templates.

Optional fields: `language` (for example `"es"`, detected when omitted), `resolution` (`{"width": 720, "height": 1280}`; the source size when omitted, never enlarged), `webhookUrl`.

## 4. Wait for it and download

Poll every 5 to 10 seconds. Most videos take one to five minutes.

```bash
curl -s https://staging-api.tscaps.io/v1/automation-jobs/<id> -H "Authorization: Bearer $TSCAPS_API_KEY"
```

- `status` is `queued` or `running`: wait. While rendering, `percent` goes from 0 to 100.
- `status` is `succeeded`: download `downloadUrl` (follow redirects), for example `curl -L -o video-captioned.mp4 "<downloadUrl>"`. The link works until `outputExpiresAt` (7 days).
- `status` is `failed`: tell the person `failureReason`. Nothing is charged for a failed job. `failureCode` says why; jobs that fail with `render-failed`, `transcription-failed`, `ingest-failed`, `timed-out` or `internal` can be started again.

Several videos: start one job per video. Jobs over the plan's concurrent limit wait in the queue on their own.

## Costs and limits

- Each video uses automation minutes equal to its length, with a minimum of 1 minute per video. A 90-second video uses 1.5 minutes. Failed and cancelled jobs use nothing.
- Free accounts: 5 automation minutes per month, videos up to 3 minutes, output up to 720p. Paid plans and minute packs raise this: https://staging.tscaps.io/api#pricing.
- A `403` with code `automation-minutes-exhausted` means the account has no minutes left. Tell the person; they can buy more at https://staging.tscaps.io/app/developers/minutes. Do not retry.
- A `429` means too many requests: wait for the seconds in `Retry-After`.

## Errors

Every error response is `{ "code": "...", "message": "..." }`. Branch on `code`; show `message` to the person when you cannot fix it yourself.

## Going further

- Building this into the person's own code (a backend, a worker, a script): read https://staging.tscaps.io/docs/llms-full.txt, the whole API reference in one file.
- Human-readable docs: https://staging.tscaps.io/docs/api.
