Start here
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:
- If a video might not be cached, call
get_processing_quotefirst. - Report
maximumCreditUnitsto the user, in dollars, and wait. - Only after approval, pass
max_credit_unitsat 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.
- 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.
- Is the artifact cached? A cached read is $0.002 and starts no work.
- 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_transcripttool on this URL. Do not use browsing." - "Call
get_processing_quotefirst 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.
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 for exact parameters
- Pricing and credits for cost math
- Limits and retention for caps and caching behavior