@remotion-studio/sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,56 +1,13 @@
-# Remotion Studio
+# @remotion-studio/sdk
 
-Generate, edit, play, and render AI-created Remotion compositions from your own apps.
+Official SDK for the hosted Remotion Studio API.
 
-`@remotion-studio/sdk` is the official package for [Remotion Studio](https://remotionstudio.io). It gives you:
+This package includes:
 
-- `@remotion-studio/sdk` to call the Remotion Studio API
-- `@remotion-studio/sdk/runtime` to render returned artifacts inside a Remotion project
+- `@remotion-studio/sdk` for calling the API
+- `@remotion-studio/sdk/runtime` for rendering returned artifacts inside Remotion or `@remotion/player`
 
-If you want a visual workflow, use the Remotion Studio UI. If you want to automate generation, build editors, run async jobs, or embed generated scenes in your own product, use the SDK.
-
-With this package you can:
-
-- generate new Remotion compositions from prompts
-- edit compositions through follow-up instructions
-- play returned artifacts directly inside a Remotion app
-- queue long-running async generation or edit jobs
-- start Remotion Lambda renders and track render progress
-- embed the returned artifact directly inside your own Remotion app
-
-## Why Use It
-
-- Generate motion graphics from prompts
-- Edit existing compositions iteratively
-- Play returned artifacts immediately in Remotion
-- Stream generation output
-- Queue long-running jobs and use polling or webhooks
-- Start cloud renders and poll for the final video output
-- Render the returned artifact directly inside Remotion
-
-## Use It Two Ways
-
-### 1. Use the UI
-
-Use [Remotion Studio](https://remotionstudio.io) when you want a visual workflow:
-
-- create and refine compositions in the browser
-- manage prompts, edits, and threads
-- create API tokens for external apps
-
-### 2. Use the API and SDK
-
-Use `@remotion-studio/sdk` when you want to:
-
-- generate compositions from your own app
-- build internal tools or automations
-- trigger async jobs from servers or background workers
-- start Remotion Lambda renders programmatically
-- embed generated artifacts in a Remotion pipeline
-
-## Quick Start
-
-Install:
+## Install
 
 ```bash
 npm install @remotion-studio/sdk
@@ -64,137 +21,91 @@ pnpm add @remotion-studio/sdk
 bun add @remotion-studio/sdk
 ```
 
-Create a client:
+## Authentication
+
+Create a personal API token in the Remotion Studio web app, then use it as a bearer token.
 
 ```ts
 import { createRemotionStudioClient } from "@remotion-studio/sdk";
 
 const client = createRemotionStudioClient({
-  baseUrl: "https://your-remotionstudio-domain.com",
+  baseUrl: "https://remotionstudio.io",
   headers: {
     Authorization: `Bearer ${process.env.REMOTIONSTUDIO_API_TOKEN}`,
   },
 });
 ```
 
-Generate a composition:
+The plaintext token is shown only once when it is created.
 
-```ts
-const generated = await client.generate({
-  prompt: "A cinematic product hero reveal with dramatic lighting",
-  reasoningEffort: "none",
-});
-```
+## Client Options
 
-Edit it:
+`createRemotionStudioClient()` accepts:
 
-```ts
-const edited = await client.edit({
-  prompt: "Make it faster, cleaner, and more typography-driven",
-  currentCode: generated.code,
-  threadId: generated.thread?.id,
-});
-```
+- `baseUrl?: string`
+- `headers?: HeadersInit`
+- `fetch?: typeof fetch`
 
-Use the artifact in Remotion:
+`baseUrl` should be the Remotion Studio origin, for example `https://remotionstudio.io`, not `https://remotionstudio.io/api`.
 
-```tsx
-import { MotionGraphicsSlot } from "@remotion-studio/sdk/runtime";
+## SDK Methods
 
-export const MyComposition = ({ artifact }: { artifact: any }) => {
-  return <MotionGraphicsSlot artifact={artifact} />;
-};
-```
+| Method                 | HTTP   | Endpoint                     | Purpose                                         |
+| ---------------------- | ------ | ---------------------------- | ----------------------------------------------- |
+| `generate()`           | `POST` | `/api/generate`              | Generate a composition                          |
+| `generateStream()`     | `POST` | `/api/generate`              | Stream generation output with `streaming: true` |
+| `edit()`               | `POST` | `/api/edit`                  | Edit existing code                              |
+| `generateAsync()`      | `POST` | `/api/generate/async`        | Queue a generation job                          |
+| `getGenerationJob()`   | `GET`  | `/api/generate/async/:jobId` | Read generation job state                       |
+| `pollGenerationJob()`  | `GET`  | `/api/generate/async/:jobId` | Wait for generation completion                  |
+| `editAsync()`          | `POST` | `/api/edit/async`            | Queue an edit job                               |
+| `getEditJob()`         | `GET`  | `/api/edit/async/:jobId`     | Read edit job state                             |
+| `pollEditJob()`        | `GET`  | `/api/edit/async/:jobId`     | Wait for edit completion                        |
+| `render()`             | `POST` | `/api/render/render`         | Start a Remotion Lambda render                  |
+| `getRenderProgress()`  | `POST` | `/api/render/progress`       | Fetch render progress                           |
+| `pollRenderProgress()` | `POST` | `/api/render/progress`       | Wait for render completion                      |
 
-Start a Remotion Lambda render:
-
-```ts
-const render = await client.render({
-  inputProps: {
-    code: generated.code,
-    durationInFrames: generated.artifact.composition.durationInFrames,
-    fps: generated.artifact.composition.fps,
-  },
-  threadId: generated.thread?.id,
-});
-
-const progress = await client.pollRenderProgress({
-  id: render.renderId,
-  bucketName: render.bucketName,
-});
-```
-
-Successful renders consume `0.1` credit when the final video is returned.
-
-## Getting Access
-
-To use the hosted product, create an account in [Remotion Studio](https://remotionstudio.io).
-
-To generate, edit, or render compositions through the hosted product, you also need active access to Remotion Studio credits or a subscription plan.
-
-For programmatic usage:
-
-1. Sign in to Remotion Studio
-2. Open `Settings -> API Tokens`
-3. Create a token
-4. Use it as a bearer token in the SDK client
-
-The plaintext token is shown only once.
-
-## What The SDK Returns
-
-You do not import generated files directly.
-
-Instead:
-
-1. Call the API with `@remotion-studio/sdk`
-2. Receive a JSON payload containing `artifact`
-3. Pass `artifact` into `@remotion-studio/sdk/runtime`
-
-The artifact is the stable contract between generation and playback.
-
-## Core API
-
-### Generate
-
-```ts
-const generated = await client.generate({
-  prompt: "A clean fintech dashboard animation with sliding cards",
-  reasoningEffort: "high",
-});
-```
-
-#### Presets
-
-Pass a `presetId` to generate compositions using a predefined style template:
+## Generate
 
 ```ts
 const generated = await client.generate({
-  prompt: "A product showcase with smooth transitions",
-  presetId: "preset-abc123",
+  prompt: "A cinematic product hero reveal with dramatic lighting",
+  reasoningEffort: "none",
 });
 ```
 
-The response includes preset information in the metadata:
+Request fields:
 
-```ts
-console.log(generated.metadata.preset);
-// { id: "preset-abc123", name: "Corporate Minimal", source: "builtin" | "custom" }
-```
+- `prompt: string`
+- `presetId?: string`
+- `model?: string`
+- `reasoningEffort?: "none" | "low" | "medium" | "high" | "xhigh"`
+- `frameImages?: string[]`
 
-Presets are created and managed in the Remotion Studio UI. Builtin presets are provided by Remotion Studio. Custom presets are user-created templates that encode style preferences, animation patterns, and design choices.
-
-### Edit
+## Edit
 
 ```ts
 const edited = await client.edit({
-  prompt: "Use a brighter palette and add more depth",
+  prompt: "Make it faster, cleaner, and more typography-driven",
   currentCode: generated.code,
   threadId: generated.thread?.id,
 });
 ```
 
-### Stream
+Common request fields:
+
+- `prompt: string`
+- `currentCode: string`
+- `threadId?: string`
+- `conversationHistory?: { role: "user" | "assistant"; content: string; attachedImages?: string[] }[]`
+- `hasManualEdits?: boolean`
+- `errorCorrection?: { error: string; source?: "compilation" | "runtime" | "generation"; attemptNumber: number; maxAttempts: number; failedEdit?: { description: string; old_string: string; new_string: string; lineNumber?: number } }`
+- `previouslyUsedSkills?: string[]`
+- `frameImages?: string[]`
+- `model?: string`
+- `reasoningEffort?: "none" | "low" | "medium" | "high" | "xhigh"`
+
+## Stream Generation
 
 ```ts
 const result = await client.generateStream(
@@ -205,9 +116,15 @@ const result = await client.generateStream(
     onMetadata: (metadata) => {
       console.log(metadata);
     },
+    onReasoningStart: () => {
+      console.log("reasoning started");
+    },
     onReasoning: (reasoning) => {
       console.log(reasoning);
     },
+    onTextStart: () => {
+      console.log("code started");
+    },
     onCode: (partialCode) => {
       console.log(partialCode);
     },
@@ -217,14 +134,9 @@ const result = await client.generateStream(
 
 ## Async Jobs
 
-Use async jobs for:
-
-- high-reasoning generations
-- server-to-server automation
-- long-running edits
-- webhook-driven integrations
+Use async methods for long-running generations or edits.
 
-Queue a generation:
+### Queue A Generation
 
 ```ts
 const job = await client.generateAsync({
@@ -244,56 +156,151 @@ const generated = await client.pollGenerationJob(job.id, {
 });
 ```
 
-Queue an edit:
+### Read A Generation Job
+
+```ts
+const jobState = await client.getGenerationJob(job.id);
+```
+
+### Queue An Edit
 
 ```ts
-const job = await client.editAsync({
+const editJob = await client.editAsync({
   prompt: "Add more contrast and speed up the transitions",
   currentCode: generated.code,
   threadId: generated.thread?.id,
 });
 
-const edited = await client.pollEditJob(job.id);
+const edited = await client.pollEditJob(editJob.id);
 ```
 
-If you provide a webhook, Remotion Studio sends the terminal job payload to your callback URL after completion or failure.
+### Read An Edit Job
+
+```ts
+const editJobState = await client.getEditJob(editJob.id);
+```
 
-Webhook authentication is handled by caller-provided headers. Remotion Studio forwards those headers when delivering the callback.
+Webhook headers are caller-owned. Remotion Studio forwards them when delivering the callback.
 
-There is no built-in webhook signature mechanism.
+## Render
 
-The recommended pattern is:
+Start a render:
 
 ```ts
-await client.generateAsync({
-  prompt: "...",
-  webhook: {
-    url: "https://your-app.example.com/remotionstudio/webhook",
-    headers: {
-      Authorization: "Bearer your-app-owned-callback-token",
-    },
+const render = await client.render({
+  inputProps: {
+    code: generated.code,
+    durationInFrames: generated.artifact.composition.durationInFrames,
+    fps: generated.artifact.composition.fps,
   },
+  threadId: generated.thread?.id,
+});
+```
+
+Check progress once:
+
+```ts
+const progress = await client.getRenderProgress({
+  id: render.renderId,
+  bucketName: render.bucketName,
 });
 ```
 
-Remotion Studio may include neutral metadata headers such as `X-RemotionStudio-Job-Id` and `X-RemotionStudio-Job-Type`, but it does not sign, mutate, wrap, or replace caller-provided webhook headers.
+Poll until done:
 
-## Local Dev And Production
+```ts
+const completed = await client.pollRenderProgress(
+  {
+    id: render.renderId,
+    bucketName: render.bucketName,
+  },
+  {
+    intervalMs: 2000,
+    timeoutMs: 10 * 60 * 1000,
+  },
+);
+
+console.log(completed.url);
+```
 
-The async API contract stays the same across environments:
+## Responses
 
-- local `next dev`: jobs are stored in the database and processed by a local runner
-- Vercel preview/production: jobs are stored in the database and executed through Vercel Workflow
+`generate()` and `edit()` return:
 
-In both cases:
+- `code`
+- `summary`
+- `metadata`
+- `artifact`
+- `thread?`
 
-- polling endpoints remain the source of truth
-- webhooks receive the same terminal payload shape
-- transient webhook failures are retried
+The `artifact` is the stable runtime contract for playback and rendering.
 
 ## Runtime
 
-Use `@remotion-studio/sdk/runtime` when you want to render returned artifacts inside a Remotion project.
+`@remotion-studio/sdk/runtime` exports:
+
+- `MotionGraphicsSlot`
+- `MotionGraphicsComposition`
+- `calculateMotionGraphicsMetadata`
+- `compileMotionGraphicsArtifact`
+
+The runtime executes generated code inside your app process. Treat returned artifacts as trusted code only.
+
+### Render Inside An Existing Composition
+
+Use `MotionGraphicsSlot` when you want to place a generated artifact inside your own composition tree.
+
+```tsx
+import { AbsoluteFill } from "remotion";
+import {
+  MotionGraphicsSlot,
+  type MotionGraphicsArtifact,
+} from "@remotion-studio/sdk/runtime";
+
+export const MyComposition = ({
+  artifact,
+}: {
+  artifact: MotionGraphicsArtifact;
+}) => {
+  return (
+    <AbsoluteFill>
+      <MotionGraphicsSlot artifact={artifact} />
+    </AbsoluteFill>
+  );
+};
+```
+
+### Render In `@remotion/player`
+
+```tsx
+import { Player } from "@remotion/player";
+import {
+  MotionGraphicsComposition,
+  type MotionGraphicsArtifact,
+} from "@remotion-studio/sdk/runtime";
+
+export const ArtifactPlayer = ({
+  artifact,
+}: {
+  artifact: MotionGraphicsArtifact;
+}) => {
+  return (
+    <Player
+      component={MotionGraphicsComposition}
+      inputProps={{ artifact }}
+      durationInFrames={artifact.composition.durationInFrames}
+      fps={artifact.composition.fps}
+      compositionWidth={artifact.composition.width}
+      compositionHeight={artifact.composition.height}
+      controls
+    />
+  );
+};
+```
+
+### Register As A Remotion Composition
+
+Use `MotionGraphicsComposition` with `calculateMotionGraphicsMetadata` when the artifact should define the composition dimensions and timing.
 
 ```tsx
 import { Composition } from "remotion";
@@ -319,51 +326,51 @@ export const RemotionRoot = ({ artifact }: MotionGraphicsCompositionProps) => {
 };
 ```
 
-The runtime expects a normal Remotion project with the peer dependencies installed, including `react`, `remotion`, `three`, `@babel/standalone`, `@remotion/lottie`, `@remotion/shapes`, `@remotion/three`, and `@remotion/transitions`.
-
-## Render API
+### Runtime Props
 
-If your Remotion Studio instance is configured with Remotion Lambda, the SDK also supports:
+Both `MotionGraphicsSlot` and `MotionGraphicsComposition` accept:
 
-- `client.render()` to queue a render
-- `client.getRenderProgress()` to fetch the latest render state
-- `client.pollRenderProgress()` to wait until the render completes
+- `artifact: MotionGraphicsArtifact`
+- `componentProps?: Record<string, unknown>`
 
-The render endpoints return the Remotion Lambda render identifiers and progress state, including the final output URL when rendering is done.
+`componentProps` is forwarded to the generated component at runtime.
 
-## Model And Credit Notes
+## Runtime Dependencies
 
-The base model is controlled by the Remotion Studio admin. External clients should usually send only `reasoningEffort`.
-Supported `reasoningEffort` values are `none`, `low`, `medium`, `high`, and `xhigh`. Use `none` to explicitly disable reasoning.
+If you only use the API client from `@remotion-studio/sdk`, you do not need any runtime dependencies.
 
-Current credit usage is:
+If you use `@remotion-studio/sdk/runtime`, the package installs its runtime helper dependencies for you.
 
-- default request or `reasoningEffort: "none"`: 1 credit
-- successful render completion: 0.1 credit
-- `low`: 2 credits
-- `medium`: 3 credits
-- `high`: 4 credits
-- `xhigh`: 5 credits
+You still need to use it inside a normal React + Remotion app, and install `@remotion/player` separately if you want to use the player example above.
 
-Legacy clients may still send `model: "provider/model:medium"`, but only the reasoning suffix is used.
+## Errors
 
-## API Docs
+API failures throw `RemotionStudioError`.
 
-If you run your own Remotion Studio instance, the generated API reference is available at:
+Useful fields:
 
-```text
-https://your-remotionstudio-domain.com/api-docs
-```
+- `message`
+- `type`
+- `status?`
+- `failedEdit?`
+- `availableCredits?`
+- `requiredCredits?`
 
-## Links
+## API Docs
 
-- Website: [remotionstudio.io](https://remotionstudio.io)
-- Product: [Remotion Studio](https://remotionstudio.io)
-- Repository: [github.com/prismosoft/remotionstudio](https://github.com/prismosoft/remotionstudio)
+- Hosted API reference: [remotionstudio.io/api-docs](https://remotionstudio.io/api-docs)
 
 ## Package Exports
 
 ```ts
-import { createRemotionStudioClient } from "@remotion-studio/sdk";
-import { MotionGraphicsSlot } from "@remotion-studio/sdk/runtime";
+import {
+  createRemotionStudioClient,
+  RemotionStudioError,
+} from "@remotion-studio/sdk";
+import {
+  MotionGraphicsSlot,
+  MotionGraphicsComposition,
+  calculateMotionGraphicsMetadata,
+  compileMotionGraphicsArtifact,
+} from "@remotion-studio/sdk/runtime";
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remotion-studio/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "description": "Official Remotion Studio package for generating, editing, playing, and rendering AI-powered Remotion compositions.",
   "packageManager": "bun@1.3.3",
@@ -39,16 +39,32 @@
   "publishConfig": {
     "access": "public"
   },
-  "peerDependencies": {
+  "dependencies": {
     "@babel/standalone": "^7.28.5",
+    "@react-three/fiber": "^9.1.0",
     "@remotion/lottie": "^4.0.429",
     "@remotion/shapes": "^4.0.429",
     "@remotion/three": "^4.0.429",
     "@remotion/transitions": "^4.0.429",
-    "react": "^19.2.1",
-    "remotion": "^4.0.429",
+    "lottie-web": "^5.13.0",
     "three": "^0.178.0"
   },
+  "peerDependencies": {
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
+    "remotion": "^4.0.429"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "remotion": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "test": "bun test ./test",