Explainers

Overview

The Explainers component turns your study materials into a narrated explainer video. Video generation starts in the background as soon as the component is created; the embed shows progress until the video is ready, and you can also check on the video from your server.

Explainer videos are generated in English. The React Native SDK does not support Explainers yet; use the iframe embed.

Creating an Explainers Component

JavaScript

import StudyfetchSDK from '@studyfetch/sdk';

const client = new StudyfetchSDK({
  apiKey: 'your-api-key',
  baseURL: 'https://studyfetchapi.com',
});

const explainerComponent = await client.v1.components.create({
  name: 'Cell Biology Explainer',
  type: 'explainers',
  config: {
    materials: ['mat-123', 'mat-456'],
    folders: ['folder-789'],
    title: 'Understanding Cell Structure and Function',
    style: 'professional',
    targetLength: 120,
    model: 'gpt-4o-mini-2024-07-18',
    imageSearch: true,
    webSearch: true,
    verticalVideo: false,
  },
});

console.log('Explainer component created:', explainerComponent._id, explainerComponent.componentId);

Python

from studyfetch_sdk import StudyfetchSDK

client = StudyfetchSDK(
    api_key="your-api-key",
    base_url="https://studyfetchapi.com",
)

explainer_component = client.v1.components.create(
    name="Cell Biology Explainer",
    type="explainers",
    config={
        "materials": ["mat-123", "mat-456"],
        "folders": ["folder-789"],
        "title": "Understanding Cell Structure and Function",
        "style": "professional",
        "target_length": 120,
        "model": "gpt-4o-mini-2024-07-18",
        "image_search": True,
        "web_search": True,
        "vertical_video": False,
    },
)

print(f"Explainer component created: {explainer_component.api_id} {explainer_component.component_id}")

Java

import com.studyfetch.javasdk.client.StudyfetchSdkClient;
import com.studyfetch.javasdk.client.okhttp.StudyfetchSdkOkHttpClient;
import com.studyfetch.javasdk.models.v1.components.ComponentResponse;
import com.studyfetch.javasdk.models.v1.components.ComponentCreateParams;

import java.util.List;

public class CreateExplainersComponent {
    public static void main(String[] args) {
        StudyfetchSdkClient client = StudyfetchSdkOkHttpClient.builder()
            .fromEnv()
            .baseUrl("https://studyfetchapi.com")
            .build();

        ComponentCreateParams params = ComponentCreateParams.builder()
            .name("Cell Biology Explainer")
            .type(ComponentCreateParams.Type.EXPLAINERS)
            .config(ComponentCreateParams.Config.ExplainersConfigDto.builder()
                .materials(List.of("mat-123", "mat-456"))
                .folders(List.of("folder-789"))
                .title("Understanding Cell Structure and Function")
                .style("professional")
                .targetLength(120)
                .model("gpt-4o-mini-2024-07-18")
                .imageSearch(true)
                .webSearch(true)
                .verticalVideo(false)
                .build())
            .build();

        ComponentResponse component = client.v1().components().create(params);
        System.out.println("Explainer component created: " + component._id());
    }
}

C#

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.Components;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public class CreateExplainersComponent
{
    public static async Task CreateExplainer()
    {
        var client = new StudyfetchSDKClient()
        {
            APIKey = Environment.GetEnvironmentVariable("STUDYFETCH_API_KEY"),
            BaseUrl = new Uri("https://studyfetchapi.com")
        };

        var explainerComponent = await client.V1.Components.Create(new()
        {
            Name = "Cell Biology Explainer",
            Type = StudyfetchSDK.Models.V1.Components.ComponentCreateParamsProperties.Type.Explainers,
            Config = new StudyfetchSDK.Models.V1.Components.ComponentCreateParamsProperties.ConfigProperties.ExplainersConfigDto()
            {
                Materials = new List<string> { "mat-123", "mat-456" },
                Folders = new List<string> { "folder-789" },
                Title = "Understanding Cell Structure and Function",
                Style = "professional",
                TargetLength = 120,
                Model = "gpt-4o-mini-2024-07-18",
                ImageSearch = true,
                WebSearch = true,
                VerticalVideo = false,
            }
        });

        Console.WriteLine($"Explainer component created: {explainerComponent._ID}");
    }
}

Configuration Parameters

name

string · required

Name of the explainers component

type

string · required

Must be "explainers"

config

object · required

Explainers configuration object. Provide at least one material or folder. Unknown keys are rejected with 400.

Configuration Properties

These properties go inside config.

materials

array

Material IDs to build the video from. Provide materials, folders, or both.

folders

array

Folder IDs whose materials (including subfolders) the video is built from

title

string

Title of the explainer video. Defaults to the component name.

style

string · default: professional

Style of the video, as free text (for example, professional)

targetLength

number · default: 60

Target video length in seconds. Use a value from 15 to 1200; the API does not check this range when the component is created.

model

string · default: gpt-4o-mini-2024-07-18

Model that summarizes your materials into the brief the video is generated from

imageSearch

boolean · default: false

Search for relevant images to include in the video

webSearch

boolean · default: false

Search the web for additional information and context

verticalVideo

boolean · default: false

Create the video in vertical format (9:16) for mobile viewing

Response

{
  "_id": "6650f1c2a9b3e4d5f6a7b8c9",
  "componentId": "explainers_V1StGXR8_Z",
  "name": "Cell Biology Explainer",
  "type": "explainers",
  "status": "active",
  "origin": "api",
  "organization": "64f0a1b2c3d4e5f6a7b8c9d0",
  "materials": ["mat-123", "mat-456"],
  "folders": ["folder-789"],
  "config": {
    "materials": ["mat-123", "mat-456"],
    "folders": ["folder-789"],
    "title": "Understanding Cell Structure and Function",
    "style": "professional",
    "targetLength": 120,
    "model": "gpt-4o-mini-2024-07-18",
    "imageSearch": true,
    "webSearch": true,
    "verticalVideo": false
  },
  "usageCount": 0,
  "createdAt": "2026-10-06T10:00:00.000Z",
  "updatedAt": "2026-10-06T10:00:00.000Z"
}

The component is active as soon as it is created. The video's own progress is tracked separately; see Getting the Video.

Getting the Video

To check on the video from your server, send { "action": "get_video" } to POST /api/v1/components/{id}/interact, where {id} is the component's _id. It returns the component's most recent video. If the component has no video yet, this starts generating one.

The SDKs' interact methods don't send a request body yet, so use cURL or an HTTP client.

curl -X POST "https://studyfetchapi.com/api/v1/components/6650f1c2a9b3e4d5f6a7b8c9/interact" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "action": "get_video" }'

Response

{
  "video": {
    "_id": "6650f2d3b4c5d6e7f8a9b0c1",
    "title": "Understanding Cell Structure and Function",
    "componentId": "explainers_V1StGXR8_Z",
    "status": "READY",
    "config": {
      "model": "gpt-4o-mini-2024-07-18",
      "targetLength": 120,
      "webSearch": true,
      "imageSearch": true,
      "verticalVideo": false,
      "style": "professional"
    },
    "results": {
      "videoUrl": "https://...",
      "thumbnailUrl": "https://...",
      "streamUrl": "https://...",
      "transcript": "...",
      "sections": [],
      "webSearchResults": [],
      "imageSources": []
    },
    "createdAt": "2026-10-06T10:00:01.000Z",
    "updatedAt": "2026-10-06T10:03:12.000Z"
  }
}

results also carries the outline (sections), transcript, web sources, and image sources that the embed shows in its tabs.

Embedding This Component

Once you've created an Explainers component, you can embed it on your website using the embedding API. The component must be active.

Generate Embed URL

JavaScript

const embedResponse = await client.v1.components.generateEmbed(explainerComponent._id, {
  // User tracking
  userId: 'user-456',
  studentName: 'Jane Smith',  // Student name for display
  groupIds: ['class-101', 'class-102'],
  sessionId: 'session-789',

  // Explainer-specific features
  features: {
    enableBadWordsFilter: true,  // Required by the SDK type; no effect on Explainers
    enableWebSearchSources: true,
    enableImageSources: true,
    enableTranscript: true,
    enableOutline: true,
  },

  // Dimensions
  width: '100%',
  height: '600px',
});

console.log(embedResponse.embedUrl);

Python

embed_response = client.v1.components.generate_embed(
    explainer_component.api_id,
    user_id="user-456",
    student_name="Jane Smith",  # Student name for display
    group_ids=["class-101", "class-102"],
    session_id="session-789",
    features={
        "enable_bad_words_filter": True,  # Required by the SDK type; no effect on Explainers
        "enable_web_search_sources": True,
        "enable_image_sources": True,
        "enable_transcript": True,
        "enable_outline": True,
    },
    width="100%",
    height="600px",
)

print(embed_response.embed_url)

Java

import com.studyfetch.javasdk.models.v1.components.ComponentGenerateEmbedParams;
import com.studyfetch.javasdk.models.v1.components.ComponentGenerateEmbedResponse;

ComponentGenerateEmbedParams params = ComponentGenerateEmbedParams.builder()
    .id(explainerComponent._id())
    // User tracking
    .userId("user-456")
    .studentName("Jane Smith")  // Student name for display
    .groupIds(List.of("class-101", "class-102"))
    .sessionId("session-789")

    // Explainer-specific features
    .features(ComponentGenerateEmbedParams.Features.builder()
        .enableBadWordsFilter(true)  // Required: build() throws without it
        .enableWebSearchSources(true)
        .enableImageSources(true)
        .enableTranscript(true)
        .enableOutline(true)
        .build())

    // Dimensions
    .width("100%")
    .height("600px")
    .build();

ComponentGenerateEmbedResponse embedResponse = client.v1().components()
    .generateEmbed(params);

System.out.println(embedResponse.embedUrl());

C#

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.Components;
using StudyfetchSDK.Models.V1.Components.ComponentGenerateEmbedParamsProperties;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public class GenerateExplainersEmbed
{
    public static async Task GenerateEmbed(string explainerComponentId)
    {
        var client = new StudyfetchSDKClient()
        {
            APIKey = Environment.GetEnvironmentVariable("STUDYFETCH_API_KEY"),
            BaseUrl = new Uri("https://studyfetchapi.com")
        };

        var embedResponse = await client.V1.Components.GenerateEmbed(new()
        {
            ID = explainerComponentId,
            UserID = "user-456",
            StudentName = "Jane Smith",  // Student name for display
            GroupIDs = new List<string> { "class-101", "class-102" },
            SessionID = "session-789",
            Features = new Features(enableBadWordsFilter: true)
            {
                EnableWebSearchSources = true,
                EnableImageSources = true,
                EnableTranscript = true,
                EnableOutline = true
            },
            Width = "100%",
            Height = "600px"
        });

        Console.WriteLine($"Embed URL: {embedResponse.EmbedURL}");
        Console.WriteLine($"Token: {embedResponse.Token}");
    }
}

The response contains embedUrl, token, expiresAt, componentId (the component's _id), componentType, and options (width and height, defaulting to 100% and 600px).

Explainer-Specific Embedding Features

The embed shows the video with up to four tabs below it. Each feature turns one tab on or off.

features.enableOutline

boolean · default: true

Outline tab: the video's sections

features.enableTranscript

boolean · default: true

Transcript tab: the narration text

features.enableWebSearchSources

boolean · default: true

Web Sources tab: web pages used when webSearch is on

features.enableImageSources

boolean · default: true

Images tab: sources of images used when imageSearch is on

Embed in Your HTML

Use the embedUrl from the response as the iframe source. The host can differ per organization, so don't build the URL yourself.

<iframe
  src="EMBED_URL_FROM_RESPONSE"
  width="100%"
  height="600px"
  frameborder="0"
  allowfullscreen
  style="border: 1px solid #e5e5e5; border-radius: 8px;">
</iframe>