# For agents

How an agent should read this documentation, quote work, and avoid spending credits it was not granted.

This page is written for an agent that has to complete a task with minimal supervision.

## Required capabilities

You need an environment that can make HTTP requests, or an existing authorized MCP connection. Reading this page in a browser-only chat does not add either capability. If you cannot call the API or tools, say so instead of claiming to have processed a video. YouTube Translate is not currently listed in ChatGPT’s Directory.

For an API-capable agent, start with this user prompt:

```
Read https://youtubetranslate.com/docs/agents.md and use
YouTube Translate to summarize this video: [paste video URL].
Show me the quote and wait for approval before spending credits.
```

Ask for account authorization before registering an account or accepting terms on the user’s behalf. Store API credentials securely outside the conversation. Buying credits requires the payer’s authorization; never collect payment credentials.

## Read this first

Fetch the machine brief before planning anything:

```
https://api.youtubetranslate.com/llms.txt
```

It carries endpoints, tool names, prices, and limits in one response. This page explains how to behave once you have them.

## Machine-readable forms of this documentation

Every page here has a Markdown twin. Replace the trailing slash with `.md`:

| HTML | Markdown |
|---|---|
| `/docs/quickstart/` | `/docs/quickstart.md` |
| `/docs/mcp-tools/` | `/docs/mcp-tools.md` |
| `/docs/rest-api/` | `/docs/rest-api.md` |

The Markdown form is the same content without navigation, which is cheaper to read than the rendered page.

## The one rule that matters

**Never spend credit you were not explicitly granted.**

Concretely:

1. If a video might not be cached, call `get_processing_quote` first.
2. Report `maximumCreditUnits` to the user, in dollars, and wait.
3. Only after approval, pass `max_credit_units` at or above that maximum.

Do not infer approval from a request to "just get the transcript". Do not reuse an old budget for a different video. A refusal with `budget_required` is the service protecting the user's balance, and it is the correct outcome if you have no approval.

## Decision order

Cheapest first. Stop as soon as the task is satisfied.

1. **Is it one of the two demo videos?** Use the separate public demo endpoint to read its transcript for free. Normal authenticated API and MCP calls remain metered.
2. **Is the artifact cached?** A cached read is $0.002 and starts no work.
3. **Does the user need new processing?** Quote, get approval, then run.

## Choosing a surface

| Situation | Use |
|---|---|
| You are an MCP client with OAuth | The MCP tools |
| You have an API key and are writing a script | REST |
| You need to enqueue and keep talking | `start_video` then `get_video_status` |

## Prompt patterns that work

Be explicit about the app and the tools, because clients route to built-in browsing otherwise.

- *"Use the YouTube Translate `get_transcript` tool on this URL. Do not use browsing."*
- *"Call `get_processing_quote` first and show me the maximum cost before any paid work."*
- *"Search inside this video for 'pricing' and give me timestamps."*

## Failure handling

- `428 budget_required` - you skipped the quote step. Quote, ask, then retry with a budget.
- `402 insufficient_credits` - stop and tell the user to top up. Do not retry in a loop.
- `409 idempotency_conflict` - you reused a key with a new body. Use a fresh key.
- `503 processing_unavailable` - retry with backoff, keeping the same idempotency key.

Full table in [Errors and retries](/docs/errors.md).

## Boundaries to respect

- Public sources only. Refuse private, members-only, and age-restricted videos rather than working around them.
- Text artifacts only. There is no video or audio download.
- Never put a credential in a URL, a log, or a shared transcript.
- Never submit private or sensitive material, because the artifact cache is shared.

## Related

- [MCP tools](/docs/mcp-tools.md) for exact parameters
- [Pricing and credits](/docs/pricing.md) for cost math
- [Limits and retention](/docs/limits.md) for caps and caching behavior
