# Agent usage

Use vid2md when an agent needs stable Markdown from a video.

## Agent flow

1. Log in with `/v1/auth/start` and `/v1/auth/verify`, then create or reuse an API key. Send it as `Authorization: Bearer v2m_your_key`.
2. Choose input. Pass a public HTTPS URL, or upload bytes to `POST /v1/uploads` and use the returned tokenized `video_url`.
3. Create `POST /v1/jobs` with `mode`.
4. Poll `GET /v1/jobs/{job_id}` every `retry_after_seconds` until the job reaches a terminal state.
5. Download `GET /v1/jobs/{job_id}/result`.
6. Cite timestamps from the Markdown report.

## Modes and credits

- `concise`: 1 credit per started minute
- `regular`: 2x
- `detailed`: 4x
- `ultra-detailed`: 8x

Use `starter`, `growth`, or `scale` credit checkout packages. Use the archive subscription when an agent needs past Markdown results after the normal retention window.

## Storage and policy

vid2md does not keep source videos. Uploaded files move through a temporary tokenized R2 handoff and get deleted after processing. Keyframes pass moderation before Markdown generation. Jobs can fail with `content_policy_violation`.

## Copy as Markdown

Use these raw Markdown docs:

- `/api/markdown/quickstart`
- `/api/markdown/api`
- `/api/markdown/output-format`
- `/api/markdown/agents`
- `/api/markdown/privacy`

Use `/llms.txt` for the documentation index.