Response Schema¶

Full reference for the result object returned when a job is done.

Top-level structure¶

{
  "summary": "string",
  "visual":   { ... },
  "audio":    { ... },
  "content":  { ... },
  "metadata": { ... },
  "platform_meta": { ... } | null
}

`summary`¶

Type: string

One sentence describing the video.

"summary": "A chef demonstrates how to make pasta carbonara in under 60 seconds."

`visual`¶

Type: object

What is visible in the video.

"visual": {
  "description": "Close-up shots of hands working in a professional kitchen. The chef chops vegetables on a cutting board, then adds guanciale to a hot pan...",
  "setting": "Indoor, professional kitchen",
  "subjects": ["chef", "pasta", "pan", "eggs", "guanciale"],
  "text_on_screen": ["CARBONARA", "3 ingredients only", "@chefmario", "No cream!"]
}

Field	Type	Description
`description`	string	Detailed visual description — people, actions, environment, lighting, mood
`setting`	string	Where the video takes place
`subjects`	string[]	Main subjects visible: people, objects, brands
`text_on_screen`	string[]	All text visible on screen — menus, signs, URLs, hashtags, prices, captions, subtitles. Empty array if none.

OCR use cases

text_on_screen is especially useful for extracting:

Restaurant menus and prices
Place names and addresses
URLs, @handles, and hashtags
Product names and brand names
Subtitles and captions
Overlaid infographics

`audio`¶

Type: object

Speech and music in the video.

"audio": {
  "transcript": "Today I'm going to show you the only carbonara recipe you'll ever need. Three ingredients: guanciale, eggs, and pecorino...",
  "language": "en",
  "has_music": true,
  "music_description": "Upbeat Italian-style background music with accordion"
}

Field	Type	Description
`transcript`	string	Verbatim transcription of all spoken words. Empty string if no speech.
`language`	string	ISO 639-1 language code of spoken content (`en`, `ru`, `es`, etc.)
`has_music`	boolean	Whether background music is present
`music_description`	string	Description of music style and mood. Empty string if no music.

`content`¶

Type: object

Narrative and structural elements.

"content": {
  "topics": ["cooking", "Italian cuisine", "quick recipes", "pasta"],
  "hooks": ["'The only carbonara recipe you'll ever need' — bold claim at 0s"],
  "tone": "educational",
  "call_to_action": "Follow for more recipes",
  "key_moments": [
    { "timestamp_s": 0, "description": "Hook: chef introduces the recipe with bold claim" },
    { "timestamp_s": 15, "description": "Adding guanciale to pan — key technique shown" },
    { "timestamp_s": 45, "description": "Final plating and taste reaction" }
  ]
}

Field	Type	Description
`topics`	string[]	3–8 content topics
`hooks`	string[]	What grabs attention in the first 3–5 seconds
`tone`	string	One of: `educational`, `entertaining`, `inspirational`, `promotional`, `informational`, `humorous`, `other`
`call_to_action`	string	Explicit CTA if any. Empty string if none.
`key_moments`	KeyMoment[]	Important moments with timestamps

`KeyMoment`¶

{ "timestamp_s": 15.0, "description": "Adding guanciale to pan" }

Field	Type	Description
`timestamp_s`	number	Time in seconds from the start
`description`	string	What happens at this moment

`metadata`¶

Type: object

High-level video properties.

"metadata": {
  "estimated_duration_s": 58,
  "format": "tutorial",
  "target_audience": "home cooks, food enthusiasts",
  "sentiment": "positive"
}

Field	Type	Description
`estimated_duration_s`	number	Estimated video length in seconds
`format`	string	One of: `tutorial`, `vlog`, `ad`, `review`, `recipe`, `travel`, `comedy`, `other`
`target_audience`	string	Description of the likely audience
`sentiment`	string	One of: `positive`, `neutral`, `negative`

`platform_meta`¶

Type: object | null

Metadata extracted from Instagram. May be null if the video is private or the platform didn't provide metadata.

"platform_meta": {
  "title": "The only carbonara recipe",
  "uploader": "@chefmario",
  "like_count": 142000,
  "view_count": 2100000,
  "upload_date": "20250110",
  "description": "Real carbonara, no cream 🍝 #pasta #cooking",
  "tags": ["pasta", "cooking", "italian"]
}

Field	Type	Description
`title`	string	Video title from Instagram
`uploader`	string	Creator's @handle
`like_count`	integer	Like count (0 if private or unavailable)
`view_count`	integer	View count (0 if private or unavailable)
`upload_date`	string	Upload date in `YYYYMMDD` format
`description`	string	Caption text from Instagram
`tags`	string[]	Hashtags from the caption (without `#`)

Complete example¶

{
  "summary": "A chef demonstrates how to make pasta carbonara in under 60 seconds.",
  "visual": {
    "description": "Close-up shots of hands working in a professional kitchen. The chef chops guanciale on a cutting board, renders it in a hot pan, mixes egg yolks with pecorino in a bowl, cooks spaghetti, and combines everything off the heat.",
    "setting": "Indoor, professional kitchen with warm lighting",
    "subjects": ["chef", "pasta", "pan", "eggs", "guanciale", "pecorino", "cutting board"],
    "text_on_screen": ["CARBONARA", "3 ingredients only", "@chefmario", "No cream!", "PASTA", "EGGS", "GUANCIALE"]
  },
  "audio": {
    "transcript": "Today I'm going to show you the only carbonara recipe you'll ever need. Three ingredients: guanciale, eggs, and pecorino. No cream. Ever.",
    "language": "en",
    "has_music": true,
    "music_description": "Upbeat Italian-style background music with accordion and percussion"
  },
  "content": {
    "topics": ["cooking", "Italian cuisine", "quick recipes", "pasta", "food tutorial"],
    "hooks": ["'The only carbonara recipe you'll ever need' — confident claim at 0s with close-up of finished dish"],
    "tone": "educational",
    "call_to_action": "Follow for more recipes",
    "key_moments": [
      { "timestamp_s": 0, "description": "Hook: finished carbonara shown, bold claim made" },
      { "timestamp_s": 8, "description": "Chopping guanciale — technique explained" },
      { "timestamp_s": 22, "description": "Rendering guanciale in pan, no-cream rule emphasized" },
      { "timestamp_s": 38, "description": "Off-heat technique for combining eggs shown" },
      { "timestamp_s": 52, "description": "Final plating and taste reaction" }
    ]
  },
  "metadata": {
    "estimated_duration_s": 58,
    "format": "tutorial",
    "target_audience": "home cooks and food enthusiasts interested in Italian cuisine",
    "sentiment": "positive"
  },
  "platform_meta": {
    "title": "The only carbonara recipe",
    "uploader": "@chefmario",
    "like_count": 142000,
    "view_count": 2100000,
    "upload_date": "20250110",
    "description": "Real carbonara, no cream 🍝 #pasta #cooking #italian",
    "tags": ["pasta", "cooking", "italian", "carbonara", "recipe"]
  }
}

Response Schema¶

Top-level structure¶

summary¶

visual¶

audio¶

content¶

KeyMoment¶

metadata¶

platform_meta¶

Complete example¶

`summary`¶

`visual`¶

`audio`¶

`content`¶

`KeyMoment`¶

`metadata`¶

`platform_meta`¶