YouTube guide
How can an AI agent extract information from a YouTube video and return JSON?
Send a YouTube video URL, a prompt, and a JSON Schema to mamitsu. It watches the video, hears the audio, reads the available caption, and returns the information you need as structured JSON.
The request tells mamitsu what to understand
Give it a URL, a prompt, and a schema.
The YouTube URL selects the video. The prompt describes the information to extract. The schema defines the JSON contract your application receives. The mamitsu API reference documents these as the required url, prompt, and schema fields.
This example asks mamitsu to extract information from the content, not just return post metadata.
curl https://usemamitsu.com/api/v1/extract \
-H "Authorization: Bearer $XTRAKT_USER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"prompt": "Extract the main steps demonstrated in this video. Give each step a short title and a concise description. Include tools or products only when the video names or visibly shows them. Do not infer steps that are not supported by the video.",
"schema": {
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "The title or subject of the tutorial, or null when it is not clear"
},
"steps": {
"type": "array",
"description": "The ordered steps demonstrated or explained in the video",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "A short name for the step"
},
"description": {
"type": "string",
"description": "What the viewer should do in this step"
},
"tools_or_products": {
"type": "array",
"description": "Tools or products named or visibly shown in this step",
"items": {
"type": "string"
}
}
},
"required": [
"title",
"description",
"tools_or_products"
],
"additionalProperties": false
}
}
},
"required": [
"title",
"steps"
],
"additionalProperties": false
}
}'Extract the main steps demonstrated in this video. Give each step a short title and a concise description. Include tools or products only when the video names or visibly shows them. Do not infer steps that are not supported by the video.The result contains your data and the source
Your JSON comes back under data.
A successful response returns the object shaped by your schema and identifies the source provider and URL that were processed.
The example values are illustrative. Check the values that matter before using them in a customer-facing or automated workflow.
{
"type": "object",
"properties": {
"title": {
"type": ["string", "null"],
"description": "The title or subject of the tutorial, or null when it is not clear"
},
"steps": {
"type": "array",
"description": "The ordered steps demonstrated or explained in the video",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "A short name for the step"
},
"description": {
"type": "string",
"description": "What the viewer should do in this step"
},
"tools_or_products": {
"type": "array",
"description": "Tools or products named or visibly shown in this step",
"items": { "type": "string" }
}
},
"required": ["title", "description", "tools_or_products"],
"additionalProperties": false
}
}
},
"required": ["title", "steps"],
"additionalProperties": false
}{
"extraction_id": "ext_example",
"data": {
"title": "Example tutorial",
"steps": [
{
"title": "Prepare the input",
"description": "Collect the materials shown at the start of the tutorial.",
"tools_or_products": ["Example tool"]
}
]
},
"source": {
"provider": "youtube",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
}How mamitsu reads the source
mamitsu reads the video, not only its transcript
The URL is the input, not the information you want back. The mamitsu homepage describes the workflow as watching frames, hearing audio, and reading the caption. mamitsu interprets the content available in the video:
- Frames can show demonstrations, slides, products, diagrams, and on-screen text.
- Audio can carry explanations, instructions, and named entities.
- The caption can provide context that is not spoken or visible in a frame.
This is content understanding, not only retrieval
A transcript-only pipeline can capture spoken words but miss a demonstration, a slide, or a label on screen. mamitsu's extract workflow interprets the content available at the URL against your prompt and returns the result in the schema your application requested. That keeps the content question and the JSON contract in one request.
Keep the result honest
Allow missing facts instead of forcing guesses.
Long videos and tutorials often leave some details implicit. Make optional fields nullable when the source may not provide them. For arrays, describe whether an empty array means that nothing was found. Do not use a required string for a detail the video may never state. The API reference documents that nullable fields receive null when the value is not in the video.
{
"type": ["string", "null"],
"description": "The value, or null when the source does not state it"
}Build the edge cases into your agent
Know which URLs and limits apply.
Public videos work. A request times out after 90 seconds, and YouTube videos over 30 minutes return url_video_too_long. Private, removed, or blocked videos return an error instead of data. Useful error codes include unsupported_url, url_source_inaccessible, invalid_schema, and extraction_failed. The request body can be up to 64 KB. Schemas can be up to 16 KB, 8 levels deep, and 200 nodes.
YouTube Shortsyoutube.com/watch?v=...youtu.be/...
YouTube is one input to the same mamitsu workflow used for TikTok, Instagram, and X. Your agent sends a URL, a prompt, and a schema. mamitsu interprets the content available at that URL and returns the requested JSON with a source record.
Back to API referenceSources
The extraction endpoint is POST /api/v1/extract. Read the API reference for the complete schema and error-code list.