Video SEO: How to Get Your Videos Indexed and Ranked by Google

Google indexes video the same way it indexes anything else, by reading structured data, not by watching the video itself. VideoObject schema markup is the specific structured-data format that does the telling, and it's worth checking directly rather than assuming: AIOZ Stream doesn't generate this markup for you. What it does have, confirmed by reading the actual API response fields, is every piece of data VideoObject schema needs, just not assembled into the format Google expects. That's a build-it-yourself gap, not a dead end.

TL;DR:

• Google discovers and understands video primarily through VideoObject structured data (Schema.org), not by analyzing video content directly. Google's own documentation lists three required properties, name, thumbnailUrl, uploadDate, plus recommended ones including description, duration, contentUrl, and embedUrl.
• Checked directly against AIOZ Stream's API: it doesn't mention VideoObject schema, structured data, JSON-LD, oEmbed, or sitemaps anywhere in its documentation. There's no auto-generated markup to enable.
• What it does return maps cleanly onto every VideoObject property needed: title, description, thumbnail_url, created_at, duration, and multiple playback URLs are all real, documented fields on every video object.
• One real gotcha worth knowing before writing the mapping code: AIOZ's duration field is a plain number in seconds (example from its own docs: 283.492426), while Google requires ISO 8601 duration format (PT4M43S for that same value). That conversion has to happen before the data is valid schema.
• Transcripts and captions genuinely help too, giving search engines readable text to crawl alongside the video, which AIOZ Stream's own Caption/Transcript API already supports, covered in an earlier article.

Why VideoObject schema is the foundation

Search engines can't watch a video the way a person does, so they rely on structured data to know what's actually in it, title, description, how long it runs, what it looks like as a thumbnail, and where the playable file or embed actually lives. Google's own documentation is direct about what's required: name, thumbnailUrl, and uploadDate in ISO 8601 format are mandatory for VideoObject markup to be valid at all, with description, duration, contentUrl, and embedUrl listed as recommended additions that unlock richer search features like key-moments timestamps. Sitemaps and schema do different jobs here rather than one replacing the other: a video sitemap is what Google's own documentation recommends specifically for discovery, helping Google find that a video page exists at all, while VideoObject schema on the page itself is what tells Google what the video actually contains once it's found. Skipping either one leaves a real gap, a sitemap with no schema gets a video discovered without Google understanding much about it, and schema with no sitemap depends entirely on Google finding the page through some other path first.

Mapping AIOZ Stream's real fields to VideoObject

Checked directly against AIOZ Stream's documented video-detail response rather than assumed, every field VideoObject needs already exists on a video object, just not packaged as schema:

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "{{ video.title }}",
  "description": "{{ video.description }}",
  "thumbnailUrl": "{{ video.assets.thumbnail_url }}",
  "uploadDate": "{{ video.created_at }}",
  "duration": "{{ video.duration | convert_to_iso8601 }}",
  "contentUrl": "{{ video.assets.source_url }}",
  "embedUrl": "{{ video.assets.hls_player_url }}"
}

title, description, created_at, and duration sit directly on the video object; thumbnail_url, source_url, and hls_player_url live inside the nested assets object, alongside mp4_url and dash_player_url as alternates depending on which delivery format a given page actually embeds. None of this requires calling anything beyond the standard get-video-detail endpoint already covered in the developer guide, the data was already there, it just needs to be rendered into a <script type="application/ld+json"> block on whatever page embeds the player.

The duration gotcha

Worth flagging specifically because it's exactly the kind of mismatch that silently produces invalid schema: AIOZ's documented example response returns duration as a plain float in seconds, 283.492426, not an ISO 8601 duration string. Google's structured-data validator expects the ISO 8601 format instead, PT4M43S for that same 283-second clip, four minutes and forty-three seconds, written as PT (period of time) followed by hours, minutes, and seconds. Passing AIOZ's raw seconds value straight into a duration field without converting it first won't throw an obvious error, it'll just quietly fail schema validation or get treated as invalid, one of the more common ways VideoObject markup ends up broken without anyone noticing at a glance.

What still has to be built manually

Being direct about the actual gap: AIOZ Stream's documentation contains no mention of VideoObject schema, JSON-LD, oEmbed, or automatic sitemap generation for embedded videos anywhere. Every field needed exists in the API response, but assembling it into valid, correctly-formatted schema and injecting it into a page's markup is work a developer has to do themselves, there's no toggle or auto-generated snippet AIOZ Stream produces for this. That's consistent with AIOZ Stream being an infrastructure and delivery API rather than a full content-management or SEO product, the same shape of gap already found for DRM and other platform-layer features elsewhere in this series. One thing that does genuinely help beyond schema: transcripts and captions give search engines actual readable text to crawl alongside a video, already fully supported through AIOZ Stream's own Caption and Transcript API, worth pairing with a manually-built VideoObject block rather than treating either alone as sufficient.

Frequently Asked Questions

What are the required fields for VideoObject schema?
Per Google's own documentation: name, thumbnailUrl, and uploadDate (in ISO 8601 format) are required. description, duration, contentUrl, and embedUrl are recommended for richer search features.

Does AIOZ Stream automatically generate VideoObject schema markup?
No, confirmed directly against its documentation. There's no mention of structured data, JSON-LD, oEmbed, or sitemap generation anywhere in the API docs.

Which AIOZ Stream API fields map to VideoObject properties?
title → name, description → description, assets.thumbnail_url → thumbnailUrl, created_at → uploadDate, duration → duration (after format conversion), assets.source_url → contentUrl, assets.hls_player_url → embedUrl.

Why would my VideoObject schema fail validation even with all the fields filled in?
The most likely cause is the duration field. AIOZ Stream returns duration as plain seconds (a float like 283.492426), while Google requires ISO 8601 format (PT4M43S). That conversion has to happen before the value is valid.

Do captions and transcripts actually help video SEO?
Yes, they give search engines readable text to crawl alongside the video itself, a genuinely separate signal from VideoObject schema, not a replacement for it.

Do I need both a sitemap and schema markup?
They solve different problems. A video sitemap, Google's recommended discovery method, helps Google find that a video page exists; schema markup tells Google what's actually in it once found. Relying on only one leaves a real gap in the other.

Related Reading

• Multi-Language Captions and Transcripts: A Developer's Guide: the transcript data that complements VideoObject schema as a separate SEO signal
• Media Chapter vs Media Transcript API: the chapter data that can also feed Google's key-moments features alongside schema
• How to Embed the AIOZ Stream Player on Your Website: the page this article's schema block actually gets added to
• How to White-Label the AIOZ Stream Video Player via API: the same embedUrl and asset fields used for player customization
• AIOZ Stream Developer Guide: the get-video-detail endpoint every field in this article's schema mapping comes from

References

• Google Search Central: Video (VideoObject) structured data: the required/recommended properties and ISO 8601 duration format quoted above
• Google Search Central: Video sitemaps: the sitemap-as-discovery-mechanism guidance quoted above