[{"data":1,"prerenderedAt":907},["ShallowReactive",2],{"doc-guide\u002Fagents":3},{"id":4,"title":5,"author":6,"body":7,"date":887,"description":888,"draft":889,"extension":890,"faq":891,"meta":892,"navigation":893,"path":894,"schemaType":895,"seo":896,"stem":897,"tags":898,"updatedAt":905,"__hash__":906},"content\u002Fguide\u002Fagents.md","Agents","YT2Text Team",{"type":8,"value":9,"toc":863},"minimark",[10,14,23,26,50,55,58,72,75,98,102,105,129,132,156,162,166,169,200,204,207,223,226,235,238,242,360,364,404,408,458,462,465,468,476,479,485,492,498,502,505,508,542,545,572,576,580,583,661,664,667,673,676,682,688,692,695,702,794,797,801,805,808,812,815,819,822,826,829,833,836,854,859],[11,12,5],"h1",{"id":13},"agents",[15,16,17,18,22],"p",{},"YT2Text is usable from AI agents today through the public REST API at ",[19,20,21],"code",{},"https:\u002F\u002Fapi.yt2text.cc\u002Fapi\u002Fv1",".",[15,24,25],{},"The public onboarding files are:",[27,28,29,35,40,45],"ul",{},[30,31,32],"li",{},[19,33,34],{},"https:\u002F\u002Fyt2text.cc\u002Fskill.md",[30,36,37],{},[19,38,39],{},"https:\u002F\u002Fyt2text.cc\u002Fskill.json",[30,41,42],{},[19,43,44],{},"https:\u002F\u002Fyt2text.cc\u002Fskill.jsonl",[30,46,47],{},[19,48,49],{},"https:\u002F\u002Fyt2text.cc\u002Fagents",[51,52,54],"h2",{"id":53},"who-this-is-for","Who this is for",[15,56,57],{},"This guide is for agent systems that can:",[27,59,60,63,66,69],{},[30,61,62],{},"read Markdown instructions",[30,64,65],{},"store API keys securely",[30,67,68],{},"make authenticated HTTPS requests",[30,70,71],{},"poll asynchronous jobs and fetch results later",[15,73,74],{},"That includes common agent\u002Foperator environments such as:",[27,76,77,80,83,86,89,92,95],{},[30,78,79],{},"Codex",[30,81,82],{},"GPT-based agents",[30,84,85],{},"Claude",[30,87,88],{},"Claude Code",[30,90,91],{},"OpenClaw",[30,93,94],{},"Hermes agents",[30,96,97],{},"internal orchestration agents",[51,99,101],{"id":100},"human-setup","Human setup",[15,103,104],{},"Before an agent can call the API, a human must:",[106,107,108,114,120,126],"ol",{},[30,109,110,111],{},"Create an account at ",[19,112,113],{},"https:\u002F\u002Fyt2text.cc\u002Fauth\u002Fsignup",[30,115,116,117],{},"Choose a plan at ",[19,118,119],{},"https:\u002F\u002Fyt2text.cc\u002Fpricing",[30,121,122,123],{},"Open ",[19,124,125],{},"https:\u002F\u002Fyt2text.cc\u002Fdashboard\u002Fapi-keys",[30,127,128],{},"Create an API key and copy it immediately",[15,130,131],{},"Plan gates:",[27,133,134,144,150],{},[30,135,136,139,140,143],{},[19,137,138],{},"free",": no API keys, ",[19,141,142],{},"tldr"," only",[30,145,146,149],{},[19,147,148],{},"plus",": API keys enabled, all summary modes",[30,151,152,155],{},[19,153,154],{},"pro",": batch processing, webhooks, custom prompts, PDF export, infographics, AI chat, priority queue",[15,157,158,159,161],{},"If the goal is external agent usage, ",[19,160,148],{}," is the minimum plan.",[51,163,165],{"id":164},"api-first-workflow","API-first workflow",[15,167,168],{},"Recommended flow:",[106,170,171,176,182,188,194],{},[30,172,173,174],{},"Read ",[19,175,34],{},[30,177,178,179],{},"Store the key in an environment variable such as ",[19,180,181],{},"YT2TEXT_API_KEY",[30,183,184,185],{},"Submit a video with ",[19,186,187],{},"POST \u002Fapi\u002Fv1\u002Fvideos\u002Fprocess",[30,189,190,191],{},"Poll ",[19,192,193],{},"GET \u002Fapi\u002Fv1\u002Fvideos\u002Fstatus\u002F{job_id}",[30,195,196,197],{},"Fetch ",[19,198,199],{},"GET \u002Fapi\u002Fv1\u002Fvideos\u002Fresult\u002F{job_id}",[51,201,203],{"id":202},"authentication","Authentication",[15,205,206],{},"Preferred header:",[208,209,214],"pre",{"className":210,"code":211,"language":212,"meta":213,"style":213},"language-http shiki shiki-themes github-light github-dark","Authorization: Bearer \u003Capi_key>\n","http","",[19,215,216],{"__ignoreMap":213},[217,218,221],"span",{"class":219,"line":220},"line",1,[217,222,211],{},[15,224,225],{},"Also supported:",[208,227,229],{"className":210,"code":228,"language":212,"meta":213,"style":213},"X-API-Key: \u003Capi_key>\n",[19,230,231],{"__ignoreMap":213},[217,232,233],{"class":219,"line":220},[217,234,228],{},[15,236,237],{},"Query parameter authentication is not supported.",[51,239,241],{"id":240},"example-request","Example request",[208,243,247],{"className":244,"code":245,"language":246,"meta":213,"style":213},"language-bash shiki shiki-themes github-light github-dark","curl -X POST https:\u002F\u002Fapi.yt2text.cc\u002Fapi\u002Fv1\u002Fvideos\u002Fprocess \\\n  -H \"Authorization: Bearer $YT2TEXT_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"url\": \"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=dQw4w9WgXcQ\",\n    \"options\": {\n      \"summary_modes\": [\"tldr\", \"detailed\"],\n      \"language\": \"en\"\n    },\n    \"service_name\": \"agent-platform\",\n    \"agent_name\": \"research-agent\",\n    \"client_reference\": \"job-123\"\n  }'\n","bash",[19,248,249,269,287,297,306,312,318,324,330,336,342,348,354],{"__ignoreMap":213},[217,250,251,255,259,263,266],{"class":219,"line":220},[217,252,254],{"class":253},"sScJk","curl",[217,256,258],{"class":257},"sj4cs"," -X",[217,260,262],{"class":261},"sZZnC"," POST",[217,264,265],{"class":261}," https:\u002F\u002Fapi.yt2text.cc\u002Fapi\u002Fv1\u002Fvideos\u002Fprocess",[217,267,268],{"class":257}," \\\n",[217,270,272,275,278,282,285],{"class":219,"line":271},2,[217,273,274],{"class":257},"  -H",[217,276,277],{"class":261}," \"Authorization: Bearer ",[217,279,281],{"class":280},"sVt8B","$YT2TEXT_API_KEY",[217,283,284],{"class":261},"\"",[217,286,268],{"class":257},[217,288,290,292,295],{"class":219,"line":289},3,[217,291,274],{"class":257},[217,293,294],{"class":261}," \"Content-Type: application\u002Fjson\"",[217,296,268],{"class":257},[217,298,300,303],{"class":219,"line":299},4,[217,301,302],{"class":257},"  -d",[217,304,305],{"class":261}," '{\n",[217,307,309],{"class":219,"line":308},5,[217,310,311],{"class":261},"    \"url\": \"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=dQw4w9WgXcQ\",\n",[217,313,315],{"class":219,"line":314},6,[217,316,317],{"class":261},"    \"options\": {\n",[217,319,321],{"class":219,"line":320},7,[217,322,323],{"class":261},"      \"summary_modes\": [\"tldr\", \"detailed\"],\n",[217,325,327],{"class":219,"line":326},8,[217,328,329],{"class":261},"      \"language\": \"en\"\n",[217,331,333],{"class":219,"line":332},9,[217,334,335],{"class":261},"    },\n",[217,337,339],{"class":219,"line":338},10,[217,340,341],{"class":261},"    \"service_name\": \"agent-platform\",\n",[217,343,345],{"class":219,"line":344},11,[217,346,347],{"class":261},"    \"agent_name\": \"research-agent\",\n",[217,349,351],{"class":219,"line":350},12,[217,352,353],{"class":261},"    \"client_reference\": \"job-123\"\n",[217,355,357],{"class":219,"line":356},13,[217,358,359],{"class":261},"  }'\n",[51,361,363],{"id":362},"agent-specific-guidance","Agent-specific guidance",[27,365,366,369,372,387,394],{},[30,367,368],{},"Prefer async processing, not synchronous assumptions",[30,370,371],{},"Keep keys server-side only",[30,373,374,375,378,379,382,383,386],{},"Use ",[19,376,377],{},"service_name",", ",[19,380,381],{},"agent_name",", and ",[19,384,385],{},"client_reference"," for correlation",[30,388,389,390,393],{},"Treat ",[19,391,392],{},"\u002Fapi\u002Fv1\u002Fusage\u002F*"," as diagnostic today, not billing truth",[30,395,396,397,400,401],{},"Back off on ",[19,398,399],{},"429"," responses using ",[19,402,403],{},"Retry-After",[51,405,407],{"id":406},"public-documentation","Public documentation",[27,409,410,417,422,428,434,440,446,452],{},[30,411,412],{},[413,414,416],"a",{"href":415},"\u002Fguide\u002Fgetting-started","Getting Started",[30,418,419],{},[413,420,203],{"href":421},"\u002Fguide\u002Fauthentication",[30,423,424],{},[413,425,427],{"href":426},"\u002Fapi\u002Fvideos","Videos API",[30,429,430],{},[413,431,433],{"href":432},"\u002Fapi\u002Fbatch","Batch API",[30,435,436],{},[413,437,439],{"href":438},"\u002Fapi\u002Fwebhooks","Webhooks",[30,441,442],{},[413,443,445],{"href":444},"\u002Freference\u002Frate-limits","Rate Limits",[30,447,448],{},[413,449,451],{"href":450},"\u002Freference\u002Fsdk-roadmap","SDK roadmap",[30,453,454],{},[413,455,457],{"href":456},"\u002Freference\u002Fagents-roadmap","Agents roadmap",[51,459,461],{"id":460},"mcp-server","MCP server",[15,463,464],{},"YT2Text now exposes a remote Model Context Protocol server.",[15,466,467],{},"Endpoint:",[208,469,474],{"className":470,"code":472,"language":473,"meta":213},[471],"language-text","https:\u002F\u002Fmcp.yt2text.cc\u002Fmcp\n","text",[19,475,472],{"__ignoreMap":213},[15,477,478],{},"Public setup page:",[208,480,483],{"className":481,"code":482,"language":473,"meta":213},[471],"https:\u002F\u002Fyt2text.cc\u002Fmcp\n",[19,484,482],{"__ignoreMap":213},[15,486,487,488,491],{},"Auth is per-request: send the user's yt2text API key as ",[19,489,490],{},"Authorization: Bearer sk_...",". The server forwards that key to the public yt2text API for the call. No server-side key storage.",[15,493,494,495,497],{},"That means MCP setup uses the same key a user creates in ",[19,496,125],{},". The key should live in the MCP client's secret store, environment variables, or local MCP config. Do not paste API keys into prompts, public repos, shared chat logs, or frontend code.",[51,499,501],{"id":500},"how-mcp-tool-behavior-works","How MCP tool behavior works",[15,503,504],{},"YT2Text does not need a separate behavior definition for every LLM. MCP defines the callable tools, their names, descriptions, and input schemas. The client model decides when to call a tool based on the user request and the tool metadata.",[15,506,507],{},"Practical guidance:",[27,509,510,513,520,533,539],{},[30,511,512],{},"Ask the client to use YT2Text when a task needs a YouTube transcript, summary, video notes, or Markdown export.",[30,514,515,516,519],{},"Prefer ",[19,517,518],{},"summarize_youtube_video"," when the agent should complete the whole flow in one step.",[30,521,515,522,525,526,525,529,532],{},[19,523,524],{},"process_youtube_video"," plus ",[19,527,528],{},"get_video_job_status",[19,530,531],{},"get_video_result"," when the agent needs explicit async control.",[30,534,374,535,538],{},[19,536,537],{},"export_video_markdown"," when the next step is research notes, documentation, publishing, or handoff to another agent.",[30,540,541],{},"Keep the YT2Text API key out of model-visible instructions whenever the client supports secret headers or environment variables.",[15,543,544],{},"Tools exposed:",[27,546,547,552,557,562,567],{},[30,548,549,551],{},[19,550,524],{}," — queue a video, return a job id",[30,553,554,556],{},[19,555,528],{}," — check job status",[30,558,559,561],{},[19,560,531],{}," — fetch completed transcript and summaries",[30,563,564,566],{},[19,565,518],{}," — queue + poll until complete",[30,568,569,571],{},[19,570,537],{}," — convert a result to Markdown",[51,573,575],{"id":574},"client-setup","Client setup",[577,578,85],"h3",{"id":579},"claude",[15,581,582],{},"Example remote HTTP config:",[208,584,588],{"className":585,"code":586,"language":587,"meta":213,"style":213},"language-json shiki shiki-themes github-light github-dark","{\n  \"mcpServers\": {\n    \"yt2text\": {\n      \"url\": \"https:\u002F\u002Fmcp.yt2text.cc\u002Fmcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer sk_...\"\n      }\n    }\n  }\n}\n","json",[19,589,590,595,603,610,624,631,641,646,651,656],{"__ignoreMap":213},[217,591,592],{"class":219,"line":220},[217,593,594],{"class":280},"{\n",[217,596,597,600],{"class":219,"line":271},[217,598,599],{"class":257},"  \"mcpServers\"",[217,601,602],{"class":280},": {\n",[217,604,605,608],{"class":219,"line":289},[217,606,607],{"class":257},"    \"yt2text\"",[217,609,602],{"class":280},[217,611,612,615,618,621],{"class":219,"line":299},[217,613,614],{"class":257},"      \"url\"",[217,616,617],{"class":280},": ",[217,619,620],{"class":261},"\"https:\u002F\u002Fmcp.yt2text.cc\u002Fmcp\"",[217,622,623],{"class":280},",\n",[217,625,626,629],{"class":219,"line":308},[217,627,628],{"class":257},"      \"headers\"",[217,630,602],{"class":280},[217,632,633,636,638],{"class":219,"line":314},[217,634,635],{"class":257},"        \"Authorization\"",[217,637,617],{"class":280},[217,639,640],{"class":261},"\"Bearer sk_...\"\n",[217,642,643],{"class":219,"line":320},[217,644,645],{"class":280},"      }\n",[217,647,648],{"class":219,"line":326},[217,649,650],{"class":280},"    }\n",[217,652,653],{"class":219,"line":332},[217,654,655],{"class":280},"  }\n",[217,657,658],{"class":219,"line":338},[217,659,660],{"class":280},"}\n",[577,662,91],{"id":663},"openclaw",[15,665,666],{},"Use the same remote server URL and configure the YT2Text key as a secret header:",[208,668,671],{"className":669,"code":670,"language":473,"meta":213},[471],"URL: https:\u002F\u002Fmcp.yt2text.cc\u002Fmcp\nHeader: Authorization: Bearer sk_...\n",[19,672,670],{"__ignoreMap":213},[577,674,94],{"id":675},"hermes-agents",[15,677,678,679,681],{},"Hermes or other orchestrators should keep ",[19,680,181],{}," in the runtime secret store and attach it as the Bearer token for MCP requests.",[208,683,686],{"className":684,"code":685,"language":473,"meta":213},[471],"MCP_URL=https:\u002F\u002Fmcp.yt2text.cc\u002Fmcp\nYT2TEXT_API_KEY=sk_...\n",[19,687,685],{"__ignoreMap":213},[577,689,691],{"id":690},"codex-and-other-mcp-capable-clients","Codex and other MCP-capable clients",[15,693,694],{},"Use remote HTTP MCP when the client supports URL-based MCP servers. Use the local stdio adapter when the client expects a command.",[15,696,697,698,701],{},"A local stdio adapter is also published in ",[19,699,700],{},"mcp\u002Fyt2text-mcp"," for embedded use:",[208,703,705],{"className":585,"code":704,"language":587,"meta":213,"style":213},"{\n  \"mcpServers\": {\n    \"yt2text\": {\n      \"command\": \"node\",\n      \"args\": [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fyt2text\u002Fmcp\u002Fyt2text-mcp\u002Fdist\u002Findex.js\"],\n      \"env\": {\n        \"YT2TEXT_API_KEY\": \"sk_...\",\n        \"YT2TEXT_API_BASE\": \"https:\u002F\u002Fapi.yt2text.cc\"\n      }\n    }\n  }\n}\n",[19,706,707,711,717,723,735,749,756,768,778,782,786,790],{"__ignoreMap":213},[217,708,709],{"class":219,"line":220},[217,710,594],{"class":280},[217,712,713,715],{"class":219,"line":271},[217,714,599],{"class":257},[217,716,602],{"class":280},[217,718,719,721],{"class":219,"line":289},[217,720,607],{"class":257},[217,722,602],{"class":280},[217,724,725,728,730,733],{"class":219,"line":299},[217,726,727],{"class":257},"      \"command\"",[217,729,617],{"class":280},[217,731,732],{"class":261},"\"node\"",[217,734,623],{"class":280},[217,736,737,740,743,746],{"class":219,"line":308},[217,738,739],{"class":257},"      \"args\"",[217,741,742],{"class":280},": [",[217,744,745],{"class":261},"\"\u002Fabsolute\u002Fpath\u002Fto\u002Fyt2text\u002Fmcp\u002Fyt2text-mcp\u002Fdist\u002Findex.js\"",[217,747,748],{"class":280},"],\n",[217,750,751,754],{"class":219,"line":314},[217,752,753],{"class":257},"      \"env\"",[217,755,602],{"class":280},[217,757,758,761,763,766],{"class":219,"line":320},[217,759,760],{"class":257},"        \"YT2TEXT_API_KEY\"",[217,762,617],{"class":280},[217,764,765],{"class":261},"\"sk_...\"",[217,767,623],{"class":280},[217,769,770,773,775],{"class":219,"line":326},[217,771,772],{"class":257},"        \"YT2TEXT_API_BASE\"",[217,774,617],{"class":280},[217,776,777],{"class":261},"\"https:\u002F\u002Fapi.yt2text.cc\"\n",[217,779,780],{"class":219,"line":332},[217,781,645],{"class":280},[217,783,784],{"class":219,"line":338},[217,785,650],{"class":280},[217,787,788],{"class":219,"line":344},[217,789,655],{"class":280},[217,791,792],{"class":219,"line":350},[217,793,660],{"class":280},[15,795,796],{},"The MCP server respects the same plan limits as the REST API (Plus minimum, Pro for batch \u002F custom prompts \u002F PDF \u002F chat \u002F infographics).",[51,798,800],{"id":799},"mcp-faq","MCP FAQ",[577,802,804],{"id":803},"does-every-user-need-their-own-api-key","Does every user need their own API key?",[15,806,807],{},"Yes. The remote MCP server is stateless for credentials. Each user sends their own YT2Text API key as a Bearer token.",[577,809,811],{"id":810},"does-the-mcp-server-call-an-llm","Does the MCP server call an LLM?",[15,813,814],{},"No. The MCP server exposes tools and forwards authenticated requests to the YT2Text public API. The MCP client and its LLM decide when to call tools.",[577,816,818],{"id":817},"can-free-users-use-mcp","Can free users use MCP?",[15,820,821],{},"No. API keys start at Plus, so Plus is the minimum plan for MCP. Pro unlocks higher-volume and automation features.",[577,823,825],{"id":824},"should-agents-use-rest-or-mcp","Should agents use REST or MCP?",[15,827,828],{},"Use REST when you are building your own integration code and want full request control. Use MCP when your client can discover and call tools directly.",[51,830,832],{"id":831},"what-comes-next","What comes next",[15,834,835],{},"The current state of YT2Text agent support:",[106,837,838,841,848,851],{},[30,839,840],{},"REST API and public skill files — live",[30,842,843,844,847],{},"Remote MCP server at ",[19,845,846],{},"mcp.yt2text.cc\u002Fmcp"," — live",[30,849,850],{},"First-party SDKs — planned",[30,852,853],{},"Native n8n node — planned",[15,855,856,857,22],{},"See ",[413,858,457],{"href":456},[860,861,862],"style",{},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}",{"title":213,"searchDepth":271,"depth":271,"links":864},[865,866,867,868,869,870,871,872,873,874,880,886],{"id":53,"depth":271,"text":54},{"id":100,"depth":271,"text":101},{"id":164,"depth":271,"text":165},{"id":202,"depth":271,"text":203},{"id":240,"depth":271,"text":241},{"id":362,"depth":271,"text":363},{"id":406,"depth":271,"text":407},{"id":460,"depth":271,"text":461},{"id":500,"depth":271,"text":501},{"id":574,"depth":271,"text":575,"children":875},[876,877,878,879],{"id":579,"depth":289,"text":85},{"id":663,"depth":289,"text":91},{"id":675,"depth":289,"text":94},{"id":690,"depth":289,"text":691},{"id":799,"depth":271,"text":800,"children":881},[882,883,884,885],{"id":803,"depth":289,"text":804},{"id":810,"depth":289,"text":811},{"id":817,"depth":289,"text":818},{"id":824,"depth":289,"text":825},{"id":831,"depth":271,"text":832},"2026-03-30","Use YT2Text from Codex, GPT agents, Claude, Claude Code, OpenClaw, Hermes agents, and other agent runtimes through the public REST API, skill files, and MCP.",false,"md",null,{},true,"\u002Fguide\u002Fagents","TechArticle",{"title":5,"description":888},"guide\u002Fagents",[899,13,900,901,902,579,903,904],"guide","api","skill","codex","gpt","mcp","2026-04-29","1_xfTD3403b2OOupFZ0jQ7PTKnmbNI_oU9eu6GzEG3I",1792448456900]