# VEED Subtitles (captions)

> VEED Subtitles transcribes the speech in a clip and burns styled subtitles into it. It returns a rendered, delivery-ready video and no timing data.

Status: roasOS API v1.1. Catalog `model-catalog@2026-10-06.v5`, pricing `customer-pricing@2026-11-05.v15`. The endpoint `POST /v1/captions/veed-subtitles` is live. `POST /v1/generations` has no `captions` type, so this endpoint is the only path to this model.

## Endpoint
POST https://api.roasos.com/v1/captions/veed-subtitles
Auth: Authorization: Bearer roasos_sk_… (scope api:write). Idempotency-Key required. quote_only / quote_id / webhook_url as in https://docs.roasos.com/llms.txt.

## Good at
Ship captions on a finished ad. Pick a preset: it sets the fonts, colours, layout and animation, and it also sets the price. Nine of the thirty presets are dynamic and cost double; the other twenty-one are basic and cost the base rate.

The price is $0.10 for each minute of the SOURCE clip, with a one-minute minimum. A dynamic preset doubles it. A source above 1080p on its short side doubles it again. A `translation_language` adds a flat $0.20 per minute on top. The worst case is $0.60 per minute — six times the base — so read the quote before you confirm.

roasOS measures the source before it quotes. The source must be 480 seconds or shorter. When the length or the resolution cannot be measured, the request is refused; roasOS never assumes the cheap tier.

## Pricing
Unit: source_minute. Pricing key: `veed-subtitles`.

| request | credits |
|---|---|
| `30s_source` | 2 |
| `60s_source` | 2 |
| `120s_source` | 3 |
| `60s_source_dynamic_preset` | 3 |
| `60s_source_worst_case` | 8 |

Credits come from the roasOS pricing table (`MODEL_COSTS`) through the catalog. No other field changes the price.

## Modes
- `subtitle`
Provider endpoints: `veed/subtitles`.

## Request fields
| field | type | required | default | rule |
|---|---|---|---|---|
| `language` | string | no | — | ≥ 2 characters; ≤ 35 characters |
| `position` | enum | no | — | `top`, `center`, `bottom` |
| `preset` | enum | yes | — | `glass`, `whisper`, `glide2`, `fusion`, `glide`, `terminal`, `handwritten`, `backdrop`, `backdrop2`, `simple`, `plain`, `beans`, `corpo`, `boo`, `shadeplay`, `casper`, `capri`, `lowkey`, `vinta`, `diego`, `ali`, `slay`, `kitty`, `hustle`, `karl`, `sprout`, `flex`, `mint`, `rizz`, `vegas` |
| `quote_id` | string | no | — | UUID |
| `quote_only` | boolean | no | `false` | — |
| `translation_language` | string | no | — | ≥ 2 characters; ≤ 35 characters |
| `video_url` | string | yes | — | https URL; ≤ 4,096 characters |
| `vocabulary` | object[] | no | — | 1–100 items; each `{ word, replaces }` |
| `wait_timeout_seconds` | integer | no | `0` | 0–60 |
| `webhook_url` | string | no | — | https URL; ≤ 4,096 characters |

The schema is strict: a field that is not in this table returns `400 unsupported_option`. Field names are the roasOS role names, one name per role across every family.

## Media
- `video_url` — the source video

| role | items | max size | content types | duration |
|---|---|---|---|---|
| `video_url` | ≤ 1 | 100 MB | `video/mp4` | 0–480 s |

- Refused: `avatar_id`, `elements`, `product_id`, `product_images`, `references`, `reference_images`, `image_url`, `end_image_url`, `scene_id`, `scene_image`, `video_urls`, `audio_urls`, `audio_url`, `voice_id`. A refused role returns `400 unsupported_option`.
- Every URL must be an immutable object on `https://cdn.roasos.com/…` that your workspace owns; any other URL is `400 reference_media_not_workspace_owned`. Upload with `POST /v1/uploads` (direct POST of the bytes to `put_url`, or a `source_url` import), then use the returned CDN URL.

## Prompt
None. This model takes no prompt.

Pick `preset` deliberately; it is the one field that changes both the look and the bill. Set `language` only when the source is hard to detect. Set `translation_language` only when you want the captions in a different language from the speech.

## Not exposed
- `srt_content`: not accepted by this public endpoint.
- `srt_file_url`: not accepted by this public endpoint.
- `customization.shadow`: not accepted by this public endpoint.
- `customization.text_customizations`: not accepted by this public endpoint.

## Result
Result kind `video`. Always present: `url`.
```json
{ "data": { "id": "gen_…", "kind": "video", "model": "veed-subtitles", "status": "completed", "result": {"url":"https://cdn.roasos.com/workspaces/ws_01/result"} } }
```
Files live on `https://cdn.roasos.com` and are immutable; a result URL can be a media input to the next call. Poll `GET /v1/jobs/{id}/status` → `{ id, status, updated_at }`, then `GET /v1/jobs/{id}/result` (`409 run_not_completed` until the job is `completed`, `failed` or `canceled`). Statuses: `queued → processing → completed | failed | canceled`.

## Example
```bash
# 1. quote — nothing is spent
curl -X POST https://api.roasos.com/v1/captions/veed-subtitles \
  -H "Authorization: Bearer roasos_sk_live_…" \
  -H "Idempotency-Key: 0f1c9e2a-veed-subtitles-0001" \
  -H "Content-Type: application/json" \
  -d '{"quote_only":true,"preset":"glass","video_url":"https://cdn.roasos.com/workspaces/ws_01/uploads/video_url.mp4"}'
# → 200 { "data": { "kind": "quote", "quote_id": "q_7Hk…", "credits": 2, "expires_at": "…", "confirmation": { "model": "veed-subtitles", "example": "30s_source" } } }

# 2. run — the same body and the same Idempotency-Key, quote_id instead of quote_only
curl -X POST https://api.roasos.com/v1/captions/veed-subtitles \
  -H "Authorization: Bearer roasos_sk_live_…" \
  -H "Idempotency-Key: 0f1c9e2a-veed-subtitles-0001" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"q_7Hk…","preset":"glass","video_url":"https://cdn.roasos.com/workspaces/ws_01/uploads/video_url.mp4"}'
# → 201 { "data": { "id": "gen_…", "kind": "video", "model": "veed-subtitles", "status": "queued", "credits_reserved": 2, "links": { "status": "/v1/jobs/gen_…/status", "result": "/v1/jobs/gen_…/result" } } }

# 3. poll
curl https://api.roasos.com/v1/jobs/gen_…/status -H "Authorization: Bearer roasos_sk_live_…"
curl https://api.roasos.com/v1/jobs/gen_…/result -H "Authorization: Bearer roasos_sk_live_…"
```

## Today
The endpoint is `POST /v1/captions/veed-subtitles`.

It is live.

## See also
https://docs.roasos.com/models/captions/veed-subtitles · https://api.roasos.com/v1/catalog/captions/veed-subtitles · veed/subtitles