> For the complete documentation index, see [llms.txt](https://docs.firework.com/firework-for-developers/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.firework.com/firework-for-developers/additional-resources/video-seo-and-geo-ai-generated-descriptions.md).

# Video SEO & GEO: AI-Generated Descriptions

Use Firework's AI-generated video descriptions to make your shoppable videos readable by search engines (SEO) and AI answer engines (GEO).

Firework videos are embedded on your site through a JavaScript widget or an iframe. Because of this, search engine crawlers and AI crawlers (ChatGPT, Perplexity, Gemini, and others) often see little or no information about the video content on your page.

Firework can now generate a text description for each of your short videos and make it available to you, so you can publish it on your pages in a form that crawlers can read.

> ⚠ **Availability: feature flag required**
>
> AI-generated video descriptions are released behind a feature flag and are **not enabled by default**. To turn the feature on for your business, contact your **Client Leadership** or **Integration Solutions** team. They will enable it for your business on request.
>
> Publishing the descriptions on your site using the recommended method (Option 1 below) also requires development work on your side.

***

### 1. How it works

1. **Firework generates the description.** When the feature is enabled, Firework fills the video's **Description (Referenced in SEO)** field with an AI-generated summary of the video.
   * **New videos:** the description is generated automatically, a few minutes after the video finishes processing.
   * **Existing videos:** videos uploaded before the feature was enabled are not filled automatically. Descriptions can be generated for all existing videos in a channel in one run. Ask your Client Leadership or Integration Solutions contact to start it.
2. **Your own text is never overwritten.** Firework only fills the field when it is empty. If you have already written a description, or you edit the AI-generated one, your text is kept.
3. **You review and edit.** In Firework Business Portal, go to **Library**, open the video, and check the **Description (Referenced in SEO)** field on the **Details** tab (up to 415 characters). Edit or replace the text as needed. Your edits are kept and are never overwritten by Firework.
4. **You publish it on your site.** Choose one of the two delivery options in section 2.

***

### 2. Choose a delivery option

|                         | **Option 1: Server-side rendering via API (recommended)**                                                                                                 | **Option 2: Widget-injected JSON-LD (fallback)**                                                       |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **How it works**        | Your server pulls the video description and metadata from the Firework API, then renders a visible text block and `VideoObject` JSON-LD in the page HTML. | The Firework widget injects `VideoObject` JSON-LD into the page with JavaScript when the widget loads. |
| **Google indexing**     | Reliable                                                                                                                                                  | Partial. Google renders JavaScript, but with a delay and no guarantee.                                 |
| **AI crawlers (GEO)**   | Readable                                                                                                                                                  | Mostly not readable. Most AI crawlers don't run JavaScript.                                            |
| **Effort on your side** | Medium. Development work in your CMS or page templates.                                                                                                   | Low. A setting or embed attribute only.                                                                |
| **Best for**            | Sites with development resources that care about SEO and GEO results.                                                                                     | Sites without development resources. Better than nothing.                                              |

***

### 3. Option 1: Server-side rendering via API (recommended)

With this option, the description is part of the HTML your server sends, so every crawler can read it, including crawlers that don't run JavaScript.

#### 3.1 Prerequisites

* The AI video description feature is enabled for your business (see the availability note above).
* Firework API credentials (`client_id` and `client_secret`) with the `videos:read` scope. OAuth apps are registered by the Firework Integration Solutions team. See [Authentication](https://docs.firework.com/firework-for-developers/api/authentication).
* The Firework video ID of each video you embed on a page.

#### 3.2 Get an access token

```bash
curl -X POST https://api.firework.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id={CLIENT_ID}" \
  -d "client_secret={CLIENT_SECRET}" \
  -d "scope=videos:read"
```

The token is valid for 15 minutes (`expires_in: 900`).

#### 3.3 Fetch the description and video metadata

Request a single video, asking only for the fields you need:

```bash
curl "https://api.firework.com/api/v1/videos/{VIDEO_ID}?fields=caption,description,thumbnail_url,duration,published_at,watch_url" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
```

Example response:

```json
{
  "id": "encoded_video_id_xyz123",
  "caption": "Summer hydration routine",
  "description": "A presenter applies a lightweight moisturizer and explains how it fits into a three-step morning routine.",
  "thumbnail_url": "https://{FIREWORK_CDN}/thumbnail.jpg",
  "duration": 42.5,
  "published_at": "2026-10-28T09:15:00Z",
  "watch_url": "https://fw.tv/watch?fw_video=encoded_video_id_xyz123"
}
```

To fetch descriptions for many videos at once, use [List videos](https://docs.firework.com/firework-for-developers/api/videos) (`GET /api/v1/videos`) with `fields=caption,description,thumbnail_url,duration,published_at,watch_url` and `page_size` up to 100.

> 📝 **Note**:
>
> * `description` is `null` until a description has been generated or entered for the video. Skip the visible text block, or fall back to your own copy, when it is empty.
> * `caption` is used as the video's title (`name`) in search results. If your captions are file names (for example `unboxing_916.mp4`), update them to a readable title in Firework Business Portal.

#### 3.4 Render the description in your page HTML

Add two things to the server-rendered HTML of each page that embeds the video:

1. A **visible text block** near the video, containing the description.
2. A **`VideoObject` JSON-LD** block describing the video.

| `VideoObject` property | Firework API field | Notes                                                       |
| ---------------------- | ------------------ | ----------------------------------------------------------- |
| `name`                 | `caption`          | Required by Google                                          |
| `description`          | `description`      | Recommended                                                 |
| `thumbnailUrl`         | `thumbnail_url`    | Required by Google                                          |
| `uploadDate`           | `published_at`     | Required by Google. ISO 8601.                               |
| `duration`             | `duration`         | Convert seconds to ISO 8601 duration (for example `PT42S`). |
| `embedUrl`             | `watch_url`        | URL of the Firework player page for this video              |

Example (Node.js):

```javascript
// Convert seconds to an ISO 8601 duration, e.g. 125 -> "PT2M5S"
function toIsoDuration(seconds) {
  const s = Math.round(seconds || 0);
  const h = Math.floor(s / 3600);
  const m = Math.floor((s % 3600) / 60);
  const sec = s % 60;
  return `PT${h ? h + "H" : ""}${m ? m + "M" : ""}${sec}S`;
}

function escapeHtml(text) {
  return String(text)
    .replace(/&/g, "&amp;")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;");
}

function renderVideoSeo(video) {
  const jsonLd = {
    "@context": "https://schema.org",
    "@type": "VideoObject",
    name: video.caption,
    description: video.description || video.caption,
    thumbnailUrl: video.thumbnail_url,
    uploadDate: video.published_at,
    duration: toIsoDuration(video.duration),
    embedUrl: video.watch_url,
  };

  // Escape "<" so the description can't close the <script> tag early
  const safeJsonLd = JSON.stringify(jsonLd).replace(/</g, "\\u003c");

  return `
    <script type="application/ld+json">${safeJsonLd}</script>
    ${video.description
      ? `<p class="fw-video-description">${escapeHtml(video.description)}</p>`
      : ""}
  `;
}
```

> ⚠ **Important**:
>
> * **Render on the server.** Output this HTML in your server-side template. Don't add it with client-side JavaScript, or AI crawlers won't see it.
> * **Cache the API response.** Don't call the Firework API on every page view. Sync descriptions on a schedule (for example, daily) or when you publish a page, and store them in your CMS or cache.
> * **Escape the text.** Always HTML-escape the visible description and escape `<` in the JSON-LD, as in the example above.
> * **Avoid duplicate markup.** If you use this option, don't also turn on the widget JSON-LD (Option 2) for the same page, or the page will contain two `VideoObject` blocks for the same video.

***

### 4. Option 2: Widget-injected JSON-LD (fallback)

If you can't change your server-side templates, the Firework widget can add `VideoObject` JSON-LD to the page for you. Turn it on in one of these ways:

* **Channel setting:** In Firework Business Portal, open your channel, go to **Settings → Video Settings**, click **Edit**, and turn on **Video Structured Data (SEO)**. This setting is off by default.
* **Embed attribute:** Add `jsonld="true"` to your Firework widget embed code, for example:

```html
<fw-embed-feed
  channel="your_channel"
  playlist="your_playlist_id"
  jsonld="true">
</fw-embed-feed>
```

* **Shopify:** If you use the Firework app with Firework Embed, the **Enable SEO** option on the widget does the same thing.

The widget adds one `VideoObject` block per video in the feed. It uses the video's **Description (Referenced in SEO)** as the `description` when one is set. Otherwise it falls back to the video caption. The video's hashtags are appended in both cases.

> 📝 **Note**:
>
> * Because this markup is added with JavaScript, Google may index it with a delay or not at all, and most AI crawlers won't read it. Use Option 1 if SEO and GEO results matter to you.
> * Widget data is cached. After you add or edit a description, it can take some time before the new text appears in the widget's JSON-LD.

***

### 5. Content guidelines

AI-generated descriptions are a **baseline description** of what the video shows. They are not SEO-optimized copy. Before publishing:

* **Review every description.** AI text can misstate product claims, prices, or specifications. This matters most in regulated categories such as beauty, health, and finance. You are responsible for what you publish.
* **Add product context.** Current descriptions mostly describe what happens in the video. Add product names, use cases, and the terms your customers search for.
* **Avoid duplicate text.** Search engines may treat the same or very similar text across many pages as low-quality content. If the same video appears on several product pages, adjust the description per page or use it on the main page only.
* **Keep it short.** Aim for 1–2 sentences covering what the video shows. Google uses this as the video summary in search results.
* **Show it on the page.** A visible description, not just JSON-LD, gives both users and AI crawlers text to read.

***

### 6. Measuring results

Firework can't see rankings, organic traffic, or AI citations on your site. To measure the impact:

* Use **Google Search Console** to check the **Video indexing** report for your pages.
* Use Google's [Rich Results Test](https://search.google.com/test/rich-results) to confirm your `VideoObject` markup is valid.
* Compare organic traffic to pages with and without published descriptions.

See Google's [video structured data documentation](https://developers.google.com/search/docs/appearance/structured-data/video) for the full list of supported properties.

***

### 7. FAQ

**Will Firework overwrite descriptions I've already written?** No. Firework only fills the **Description (Referenced in SEO)** field when it is empty. Your text, and any edits you make to AI-generated text, are kept.

**Which videos are supported?** Short videos. Descriptions are generated for new videos automatically once the feature is on. Existing videos are filled when a channel-wide run is started on request.

**How do I turn the feature on or off?** Contact your Client Leadership or Integration Solutions team. The feature is controlled by a feature flag on your business.

**Do I need to change my embed code?** Not for Option 1. Your embed stays the same; you add the description and JSON-LD to your page template. For Option 2, you turn on the channel setting or add `jsonld="true"` to the embed.

***

### Related pages

* [Authentication](https://docs.firework.com/firework-for-developers/api/authentication)
* [Videos API](https://docs.firework.com/firework-for-developers/api/videos)
* [Web integration guide](https://docs.firework.com/firework-for-developers/web/integration-guide)
