Videostew Developer Documentation

Request Format Note When making POST requests, we recommend sending the JSON body directly with the Content-Type: application/json header. If using application/x-www-form-urlencoded, serialize the parameters as JSON and send them in the payload field. Example: payload={"apiKey":"...","secret":"..."}

The // comments in the JSON examples in this document are for explanation only. Standard JSON does not allow comments, so do not include comments in your actual request body. (Blocks containing comments are marked as jsonc.)

Automation API

An API for automatically generating and exporting videos without the editing interface. To prevent token exposure, call this API from the backend only.

POST https://videostew.com/api/automations

Automates both project creation and export in a single call. The final result is delivered via POST to the webhookUrl or the Export Webhook configured in your app settings. Projects created this way are automatically deleted one week after export.

Authentication Headers

Body Parameters

Request Example

curl -X POST "https://videostew.com/api/automations" \
  -H "Authorization: Bearer {{bearerToken}}" \
  -H "x-nonce: $RANDOM" \
  -H "Content-Type: application/json" \
  -d '{
    "baseProjectId": "88282f69vmqbqr9",
    "injector": {
      "wizard": {
        "source": "url",
        "sourceContent": "https://doo39oi115k60.cloudfront.net/wizard-url-example/"
      }
    }
  }'

Response Example

{
  "status": "done",
  "result": {
    "projectId": "abc123..."
  }
}

Checking the result: If you visit https://videostew.com/v/{projectId} and see the message "Exporting…", rendering is in progress. You can check the completed video at the same URL in about 5 minutes. To receive the completion event in code, specify a webhookUrl.

Webhook Response (on export completion)

{
  "status": "done",
  "projectId": "abc123...",
  "size": "1080x1920",
  "type": "mp4",
  "link": "https://cdn.videostew.com/projects/..."
}

Injector Detailed Options

Two data injection methods are available: wizard and data. They are mutually exclusive — only one can be used at a time.

injector.wizard

Pass text or a URL and AI will analyze it to automatically create a video. Detailed control is limited, but this is the simplest way to generate a video.

If all keys in adjust are set to keep, the original text is used as-is without any AI refinement.

{
  "wizard": {
    "source": "url",
    "sourceContent": "https://doo39oi115k60.cloudfront.net/wizard-url-example/",
    "language": "ko",
    "opts": {
      "replace": "all",
      "visual": "ai-image",
      "visualStyle": "illust",
      "autoLineBreak": "y"
    },
    "adjust": {
      "duration": "1m",
      "structure": "headbody",
      "style": "news"
    }
  }
}

Conversational (podcast) example - per-speaker AI voice assignment

When content includes speaker patterns such as 진행자: or 게스트:, you can use narrationVoices to assign a different voice to each speaker. Speaker names must exactly match the patterns in the content.

{
  "wizard": {
    "source": "text",
    "sourceContent": "<p>진행자: 안녕하세요, 오늘의 주제는...</p><p>게스트: 네, 반갑습니다...</p>",
    "language": "ko",
    "opts": {
      "replace": "all",
      "narrationVoices": {
        "neutral": "voice-library-id-default",
        "진행자": "voice-library-id-host",
        "게스트": "voice-library-id-guest"
      }
    }
  }
}

neutral: The default voice applied to slides that have no speaker pattern (e.g., intro/outro slides).

injector.data

Directly specifies the project/slide/element structure. Use this when you want to fully control how the video is built. If a match with an existing element is found it is replaced; otherwise a new one is created. Specify only the keys that need to change — unspecified values retain their values from the existing project.

Label ≠ API key: Even if the label you gave an element is img, the image injection key is always image. The label (label) is for choosing "which slide/element," while the injection keys (text image video) and the coordinate/style keys are fixed.

data keys

The bgm specified at the top level is applied as the default across the entire slides array. If a value is specified for an individual slide, that value takes precedence.

data.slides[] keys

Note: All fields that accept a URL (image, video, sound, bgm, narration, etc.) must be publicly accessible addresses in a standard file format supported by Chrome.

Example 1 - Text/image replacement + TTS narration

{
  "data": {
    "language": "ko",
    "bgm": "https://example.com/bgm.mp3",  // applied to all slides
    "slides": [
      {
        "label": "title",                   // matched by slide label in the base project
        "text": "오늘의 뉴스 제목",           // replaces the template's text element with this content
        "image": "https://doo39oi115k60.cloudfront.net/wizard-url-example/01.webp",
        "narration": "오늘의 뉴스를 전해드립니다."  // a string value generates TTS (follows the narration settings of the base project)
      },
      {
        "label": "body",
        "text": "본문 내용입니다.",
        "image": "https://doo39oi115k60.cloudfront.net/wizard-url-example/02.webp"
      },
      {
        "label": "outro",
        "text": ""                          // an empty string deletes that text element
      }
    ]
  }
}

Example 2 - Targeting elements by label

When a template has multiple text elements, you can use the { label, content } form to precisely specify which element receives what content. However, this approach requires that each text element in the Videostew editing screen has been pre-labeled. Elements without a label cannot be targeted. For example, if a template has the top element labeled title and the bottom AI voice element labeled voicetext, you can control each independently as shown below.

{
  "data": {
    "slides": [
      {
        "label": "main",
        "text": [
          { "label": "title", "content": "이거 진짜 될까?" },       // top title element on screen
          { "label": "voicetext", "content": "이거 진짜 될까" }     // subtitle element read by AI voice
        ]
      }
    ]
  }
}

Example 3 - Recorded narration + per-slide video

{
  "data": {
    "slides": [
      {
        "label": "intro",
        "narration": "https://doo39oi115k60.cloudfront.net/wizard-url-example/narration1.mp3", // self-recorded/synthesized audio file
        "video": "https://doo39oi115k60.cloudfront.net/wizard-url-example/video1.mp4"
      },
      {
        "label": "body",
        "narration": "https://doo39oi115k60.cloudfront.net/wizard-url-example/narration2.mp3", 
        "video": "https://doo39oi115k60.cloudfront.net/wizard-url-example/video2.mp4",
        "bgm": "https://example.com/this-slide-only.mp3"  // different BGM for this slide only
      }
    ]
  }
}

injector.data Advanced Settings (elements)

This is the extended mode of injector.data. Use the elements array when you need fine-grained control that cannot be expressed with the simple mode above (text/image/video strings) — such as element positioning, multiple elements of the same type, entrance animations, idle effects, and so on. The following is a complete list of available keys — include only what you need in your actual request.

baseProjectId required: Injection is based on a project/template owned by the caller. If you omit baseProjectId, elements will not be applied, so specify your own project ID. You cannot create a new slide layout that does not exist in the base using elements alone.

color format: [[R, G, B, A], degree] (R/G/B are 0–255, A is 0–1 opacity, degree is the gradient angle, 0 for solid color).

Media replacement uses a public URL in libraryId: If you put a public URL in an image/video element's libraryId, it is ingested and replaced. It cannot be replaced via custom.source or an element's image key.

Element entrance animation trans (a top-level field of the element, separate from the slide transition trans. Format: group__direction):

Element idle effect idle: pendulum pulse twitch updown leftright shake blink clockwise counterclockwise. Intensity is set with idleConf: { "speed": number, "distance": number }.

Slide transitions and element animations use different value systems. Slide transitions (slides[].trans.type) use hyphenated directions (fade, cube-ltr, reveal-rtl, etc.), while element entrance animations (elements[].trans.type) use the underscore directions from the table above (reveal__right, etc.).

Field tables

Slide level:

Element elements[] (common):

rect:

custom (text):

custom (video):

narration:

glb:

{
  "data": {
    "title": "프로젝트 제목",
    "language": "ko",
    "slides": [
      {
        "trans": {
          "type": "fade",       // auto | fade | flip-ltr | flip-ttb | cube-ltr | cube-rtl | reveal-ltr | reveal-rtl
          "durationTime": 0.3
        },
        "narration": {
          "type": "voice",      // voice (audio file) | tts (text synthesis)
          "libraryId": "https://doo39oi115k60.cloudfront.net/wizard-url-example/narration1.mp3",  // when type is voice
          "content": "",        // text to read when type is tts
          "volume": 1,
          "speed": 1.1,
          "trimStart": 0,
          "trimEnd": 0
        },
        "glb": {
          "bgmLibraryId": "https://example.com/bgm.mp3",
          "bgmVolume": 0.9,
          "bgmSpeed": 1,
          "soundLibraryId": "https://example.com/sfx.mp3",
          "soundVolume": 1,
          "soundEvery": true,
          "soundFit": false,
          "backgroundColor": [[0, 0, 0, 1], 0],
          "bgBlr": false,
          "bgBlrB": 0.4
        },
        "elements": [
          {
            "type": "text",
            "content": "텍스트 내용",
            "rect": {
              "top": 800, "left": 40, "width": 1000, "height": 200,
              "opacity": 1
            },
            "custom": {
              "fontSize": 48,
              "color": [[255, 255, 255, 1], 0],
              "align": "center",          // left | center | right
              "valign": "middle",         // top | middle | bottom
              "lineHeight": 1.2,
              "raType": "shadow",         // "" | block | inline | outline | shadow  (default inline)
              "raColor": [[0, 0, 0, 1], 0],
              "enabledTts": true,
              "splitLine": "1l",          // "" all | 1l one line at a time | 2l two lines at a time | p per paragraph
              "splitLineType": "replace"  // replace | add (accumulate)
            },
            "trans": { "type": "reveal__right", "txtRange": "line" }  // element entrance animation (table above)
          },
          {
            "type": "image",
            "libraryId": "https://doo39oi115k60.cloudfront.net/wizard-url-example/01.webp",
            "rect": {
              "top": 0, "left": 0, "width": 1080, "height": 1920,
              "opacity": 1,
              "innerType": "cover",       // cover | contain | fill
              "innerPosition": "50% 30%"  // CSS position format, image focus position
            },
            "idle": "updown",             // idle effect (list above)
            "idleConf": { "speed": 1.0, "distance": 1.0 }
          },
          {
            "type": "video",
            "libraryId": "https://doo39oi115k60.cloudfront.net/wizard-url-example/video1.mp4",
            "rect": {
              "top": 0, "left": 0, "width": 1080, "height": 1080,
              "innerType": "cover",
              "innerPosition": "50% 50%"
            },
            "custom": {
              "trimStart": 0,
              "trimEnd": 10,
              "speed": 1,
              "volume": 1,
              "loop": 9999    // 0 = no loop, 9999 = infinite loop
            }
          },
          {
            "type": "shape",
            "libraryId": "shape-library-id",
            "rect": {
              "top": 0, "left": 0, "width": 200, "height": 200
            },
            "custom": {
              "color": [[255, 100, 0, 1], 0]
            }
          }
        ]
      }
    ]
  }
}

dictionary

Text substitution rules applied during TTS/STT. Passed at the top level of the body alongside injector. Merged with the space dictionary, with values specified here taking precedence. Maximum 100 entries per section.

{
  "injector": {
    "wizard": { "source": "url", "sourceContent": "https://doo39oi115k60.cloudfront.net/wizard-url-example/" }
  },
  "dictionary": {
    "tts": [
      { "i": "3D", "o": "쓰리디" },       // prevents it from being read as "삼디"
      { "i": "AI", "o": "에이아이" }       // prevents it from being read as "아이"
    ],
    "stt": [
      { "i": "video studio", "o": "videostew" },   // corrects STT misrecognition
      { "i": "비디오 스튜", "o": "비디오스튜" }     // corrects spacing misrecognition
    ]
  }
}

Other APIs

GET https://videostew.com/api/spaces - List Workspaces

curl -X GET "https://videostew.com/api/spaces" \
  -H "Authorization: Bearer {{bearerToken}}" \
  -H "x-nonce: $RANDOM"

GET https://videostew.com/api/projects - List Projects

curl -X GET "https://videostew.com/api/projects?spaceId=0&limit=20&page=1" \
  -H "Authorization: Bearer {{bearerToken}}" \
  -H "x-nonce: $RANDOM"

GET https://videostew.com/api/projects/:projectId - Get Single Project

curl -X GET "https://videostew.com/api/projects/PROJECT_ID" \
  -H "Authorization: Bearer {{bearerToken}}" \
  -H "x-nonce: $RANDOM"

Query parameter: includeSlides=true — the response result includes a slides array (each slide: slideId, glb, duration, narration, trans, elements, note, etc., symmetric with the injection structure). Useful for verifying that injected values were actually applied. It is large, so use it only when needed.

GET https://videostew.com/api/exports - List Exports

curl -X GET "https://videostew.com/api/exports?projectId=PROJECT_ID&limit=20" \
  -H "Authorization: Bearer {{bearerToken}}" \
  -H "x-nonce: $RANDOM"

GET https://videostew.com/api/exports/:projectId/:exportId - Get Single Export

curl -X GET "https://videostew.com/api/exports/PROJECT_ID/EXPORT_ID" \
  -H "Authorization: Bearer {{bearerToken}}" \
  -H "x-nonce: $RANDOM"

POST https://videostew.com/api/exports/:projectId - Request Export

curl -X POST "https://videostew.com/api/exports/PROJECT_ID" \
  -H "Authorization: Bearer {{bearerToken}}" \
  -H "x-nonce: $RANDOM" \
  -H "Content-Type: application/json" \
  -d '{"type":"mp4","webhookUrl":"https://your-server.com/webhook"}'

Response:

{
  "status": "done",
  "result": {
    "id": "e-19",
    "projectId": "...",
    "status": "generate",
    "type": "mp4"
  }
}

Webhook response (on export completion):

{
  "status": "done",
  "projectId": "...",
  "size": "1280x720",
  "type": "mp4",
  "link": "https://cdn.videostew.com/projects/..."
}

SDK

Use this when you want to provide only the Videostew editing interface to your customers on your own website.

Authentication (Issuing / Expiring Access Tokens)

When using the SDK, you must issue a separate access token for each user. A token is valid for 1 month after its last use and is automatically renewed on reuse. If you receive a 401 Token is invalid response, issue a new token and handle the fallback.

!! To prevent secret key exposure, make this request from the backend only.

POST https://videostew.com/auth/access-token - Issue Access Token

curl -X POST "https://videostew.com/auth/access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "{{apiKey}}",
    "secret": "{{secret}}",
    "uniqueId": "user_123"
  }'

Response:

{
  "status": "done",
  "apiKey": "abc1de2fg3...",
  "token": "Qjky6mFiMkRnOmExYj..."
}

POST https://videostew.com/auth/revoke-access-token - Expire Access Token (Optional)

Force-expires a user's token when all activity ends (e.g., logout). Since tokens are not single-use, force-deleting one may cause issues in other open tabs. Call this when you are certain the user has stopped using the service (e.g., account deletion).

curl -X POST "https://videostew.com/auth/revoke-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "{{apiKey}}",
    "secret": "{{secret}}",
    "uniqueId": "user_123"
  }'

Launching the Editor

videostewSDK.open(options)

Opens the editor as a modal, typically from a button click or similar event.

<script src="https://cdn.videostew.com/web/sdk/sdk-latest.js"></script>
<script>
	videostewSDK.open({
		token: "Qjky6mFiMkRnOmEx...", // token value from the /auth/access-token response
		projectId: "...",     // ID of the project to edit (creates a new one if omitted)
		// baseProjectId: "...",  // use a specific project as a template (on new creation)
		// language: "ko",        // project and UI language setting
		// injector: { ... },     // data injection/transformation spec
		// dictionary: { ... },   // TTS/STT text substitution rules
		callbackFunc: function(result) {
			// called when the user clicks [Done]
			console.log(result.projectId);
			// result: { projectId, thumbnailUrl, spaceId, width, height, title, status, slideCount, savedAt }
		},
		eventFunc: function(projectId, eventName) {
			// called when an event occurs in the editing screen
			// eventName: openPreview, saveProject, openDownload,
			//            requestExportPng, requestExportMp4, exportedPng, exportedMp4,
			//            downloadPng, downloadMp4, openProjectInfo, updateProjectInfo
		},
		errorFunc: function(errorMessage) {
			// called on token expiry → issue a new token and retry
			// errorMessage: "Token is invalid"
		}
	});
</script>

videostewSDK.save()

Saves the current state of the editing screen. This is equivalent to the user pressing the [Save] button, so there is generally no need to call it explicitly.

videostewSDK.save();

videostewSDK.done()

Saves the edited content and delivers the result to callbackFunc or the Done Webhook.

videostewSDK.done();

videostewSDK.cancel(force?)

Closes the editor. A confirmation popup is shown if there are unsaved changes.

videostewSDK.cancel();
// videostewSDK.cancel(true); // force close