JavaScript SDK

@indreamai/client 1.1.0 provides typed API requests, export polling and cancellation, uploads, and webhook verification. Use Node.js 18 or later, or a server runtime with the required standard Web APIs.

Install and initialize

pnpm add @indreamai/client@1.1.0

import { IndreamClient } from '@indreamai/client'

const client = new IndreamClient({
  apiKey: '<YOUR_API_KEY>',
  baseURL: 'https://api.indream.ai',
  timeout: 60_000,
  maxRetries: 2,
})

The SDK sends your API key as a Bearer credential. Keep it on the server. timeout is the timeout for an individual request; export completion can take longer.

Export a video

The Quick Start includes a complete script that loads the sample state, validates it, creates an export, waits, and saves the file.

For TypeScript, use TEditorStateV1 for state you author. The request envelope and the state itself both need stateSchemaVersion: 'v1':

import type { TEditorStateV1 } from '@indreamai/client'

async function exportVideo(editorState: TEditorStateV1) {
  const validation = await client.editor.validate(editorState)
  if (!validation.valid) throw new Error(JSON.stringify(validation.errors))

  const created = await client.exports.create({
    editorState,
    stateSchemaVersion: 'v1',
    ratio: '16:9',
    scale: 1,
    fps: 30,
    format: 'mp4',
    filename: 'video.mp4',
  })
  return client.exports.wait(created.taskId, { timeoutMs: 600_000 })
}

This function continues the initialization example. Output settings must be allowed by your workspace. The returned task includes filename, outputUrl, and billing fields.

Save projects and upload files

Projects shows a complete create, sync, and export sequence. All create and sync requests include stateSchemaVersion: 'v1'.

For an upload from Node.js:

import { readFileSync } from 'node:fs'

const asset = await client.uploads.upload(readFileSync('hero.png'), {
  filename: 'hero.png',
  contentType: 'image/png',
})
console.log(asset.assetId, asset.fileUrl)

Pass projectId to bind the upload immediately. For a ReadableStream, also pass its exact contentLength; byte arrays, buffers, and blobs supply their length automatically. Assets explains file limits and editor-state mapping.

Observe and cancel exports

const task = await client.exports.get('<TASK_ID>')
console.log(task.status, task.exportPhase, task.progress)

const page = await client.exports.list({ pageSize: 20 })
console.log(page.items, page.nextPageCursor)

exports.wait returns only on completion and throws APIError with TASK_TERMINAL_FAILURE when the task fails or is canceled. To cancel server work, call client.exports.cancel(taskId).

Use an AbortSignal to stop a client request or wait. An abort or wait timeout does not cancel the export. Request timeouts and export wait timeouts are separate from task failures.

Handle errors and retries

import { APIError } from '@indreamai/client'

try {
  await client.exports.get('<TASK_ID>')
} catch (error) {
  if (error instanceof APIError) {
    console.error(error.status, error.errorCode)
  } else {
    throw error
  }
}

AuthError, ValidationError, and RateLimitError extend APIError. Select a recovery action by errorCode; not every 429 should be retried. See Errors and retries.

Automatic retries apply to eligible transient failures on reads and export submissions with a stable idempotency value. Uploads and other writes are not automatically repeated. For export retries, pass { idempotencyKey: 'your-stable-request-key' } as the second argument to exports.create and keep the payload unchanged.

Verify webhooks

Use verifyExportWebhookRequest to check the raw body and signature headers, then parseExportWebhookEvent to parse the payload. The Webhook guide includes a handler and delivery requirements.

Find supported visuals

client.editor.capabilities() lists supported presets. client.illustrations.search('creative') finds illustration names you can use in editor state.

Source and issues: indream-client-js on GitHub. Package: @indreamai/client.