1. Copy the source/ directory into your project, for example at src/runway/.

2. In your tsconfig.json ensure moduleResolution supports path aliases and modern module output:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "outDir": "dist",
    "rootDir": "src"
  }
}

3. If you use path aliases, add the source root:

{
  "compilerOptions": {
    "paths": {
      "@runway/*": ["src/runway/*"]
    }
  }
}

4. Set your API key as an environment variable before running the server:

export RUNWAYML_API_SECRET=your_api_key_here

5. Import the client from wherever you placed the source:

import RunwayML from './runway/index';

Public API

RunwayML

import RunwayML, { type ClientOptions } from './runway/index';

const client = new RunwayML({
  apiKey: string;          // defaults to process.env['RUNWAYML_API_SECRET']
  maxRetries?: number;     // default 2
  timeout?: number;        // milliseconds, default 60_000
  baseURL?: string;
});

The main client. Instantiate once per process. All resource namespaces (client.imageToVideo, client.tasks, client.avatars, etc.) are properties on this instance. Pass ClientOptions to override retry/timeout behavior globally.

APIError

import { APIError, BadRequestError, NotFoundError, RateLimitError } from './runway/index';

try {
  await client.imageToVideo.create(params);
} catch (err) {
  if (err instanceof APIError) {
    err.status;   // HTTP status code
    err.name;     // e.g. "BadRequestError"
    err.headers;  // response headers
  }
}

Base class for all HTTP error responses. Subclass by status code: BadRequestError (400), AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), UnprocessableEntityError (422), RateLimitError (429), InternalServerError (>=500), APIConnectionError (network).

toFile

import { toFile, type Uploadable } from './runway/index';
import fs from 'fs';

const uploadable: Uploadable = await toFile(fs.createReadStream('./audio.mp3'), 'audio.mp3', {
  type: 'audio/mpeg',
});

Converts a ReadableStream, Buffer, Blob, or file path into an Uploadable that the SDK can attach as multipart form data. Use this whenever a resource parameter accepts a file input.

TaskFailedError / TaskTimedOutError

import { TaskFailedError, TaskTimedOutError, type WaitForTaskOutputOptions } from './runway/index';

Thrown by the polling helpers in lib/polling.ts when an async task ends in a failure state or exceeds the polling timeout. Use these to distinguish terminal failures from transient errors.

Working examples

Scenario - Generate a video from an image

Create a generation task and poll until the output URL is available.

import RunwayML, { TaskFailedError, TaskTimedOutError } from './runway/index';

const client = new RunwayML({
  apiKey: process.env.RUNWAYML_API_SECRET,
});

async function generateVideo() {
  const task = await client.imageToVideo
    .create({
      model: 'gen4_turbo',
      promptImage: 'https://example.com/assets/bunny.jpg',
      ratio: '1280:720',
      promptText: 'The bunny is eating a carrot',
    })
    .waitForTaskOutput({ pollingIntervalMs: 5000, timeoutMs: 300_000 });

  console.log('Output URL:', task.output);
}

generateVideo().catch((err) => {
  if (err instanceof TaskFailedError) {
    console.error('Task failed:', err.message);
  } else if (err instanceof TaskTimedOutError) {
    console.error('Task timed out');
  } else {
    throw err;
  }
});

Scenario - Text-to-image with error handling

Submit a text-to-image request and handle HTTP errors by status code.

import RunwayML, { APIError, RateLimitError, AuthenticationError } from './runway/index';
import type { TextToImageCreateParams } from './runway/resources/index';

const client = new RunwayML();

async function makeImage(prompt: string) {
  const params: TextToImageCreateParams = {
    promptText: prompt,
    model: 'gen4_image',
    ratio: '1024:1024',
  };

  try {
    const result = await client.textToImage.create(params);
    console.log('Task ID:', result.id);
    return result;
  } catch (err) {
    if (err instanceof AuthenticationError) {
      console.error('Invalid API key');
    } else if (err instanceof RateLimitError) {
      console.error('Rate limited - back off and retry');
    } else if (err instanceof APIError) {
      console.error(`API error ${err.status}: ${err.name}`);
    } else {
      throw err;
    }
  }
}

Scenario - List avatars with cursor-based pagination

Page through all avatars in the organization using the cursor page helper.

import RunwayML from './runway/index';
import type { AvatarListResponsesCursorPage } from './runway/resources/index';

const client = new RunwayML();

async function listAllAvatars() {
  const page: AvatarListResponsesCursorPage = await client.avatars.list({ limit: 20 });

  for await (const avatar of page) {
    console.log(avatar.id, avatar.name);
  }
}

listAllAvatars();

File walkthrough

• source/client.ts - Defines RunwayML class and ClientOptions; wires all resource sub-clients as properties; handles retry, timeout, auth header injection.
• source/index.ts - Single entry point re-exporting every public symbol; this is the file your code should import from.
• source/resources/ - Each file wraps one REST resource (ImageToVideo, Tasks, Avatars, Documents, SoundEffect, etc.) with typed create/retrieve/list/update methods.
• source/core/api-promise.ts - APIPromise<T> extends native Promise with .withResponse() and .asResponse() to access raw headers/status alongside data.
• source/core/pagination.ts - CursorPage and PagePromise implementations for iterating multi-page results.
• source/core/error.ts - All typed HTTP error classes; source of truth for error hierarchy.
• source/core/uploads.ts - toFile helper and Uploadable type for multipart uploads.
• source/lib/polling.ts - waitForTaskOutput and waitForWorkflowInvocation with configurable polling interval and timeout; exports TaskFailedError, TaskTimedOutError, WorkflowInvocationFailedError, WorkflowInvocationTimedOutError.
• source/internal/ - Platform detection, header merging, query string serialization, fetch shims; not intended to be imported directly.
• source/version.ts - Exports VERSION string ("3.20.0").

Common pitfalls and fixes

• Missing RUNWAYML_API_SECRET env var - The constructor silently accepts undefined but every request will return 401; always validate process.env.RUNWAYML_API_SECRET at startup.
• Node.js < 18 has no global fetch - Install node-fetch and assign global.fetch = require('node-fetch') before importing the client, or upgrade to Node 18+.
• ESM/CJS interop errors with moduleResolution - Set "moduleResolution": "NodeNext" and "module": "NodeNext" together; mixing "CommonJS" module with "bundler" resolution breaks internal relative imports.
• waitForTaskOutput never resolves in tests - The polling helper uses real setTimeout; in Jest use jest.useFakeTimers() and advance timers manually, or pass a very short timeoutMs to force TaskTimedOutError.
• toFile with fs.createReadStream fails in edge runtimes - Edge/Cloudflare Workers have no fs module; use new Blob([buffer]) passed directly to toFile instead.
• Deprecated shim imports - source/api-promise.ts, source/pagination.ts, and source/error.ts are marked @deprecated; import from source/core/* or source/index.ts to avoid warnings.

Vibe-coding prompt template

I have the RunwayML TypeScript SDK source checked into my project at `src/runway/`
(upstream package: @runwayml/sdk@3.20.0). The integration guide is in `USAGE.md`.

Please help me integrate this SDK into my existing Node.js/TypeScript project step by step:

1. Read `USAGE.md` and `src/runway/index.ts` to understand every public export.
2. Instantiate the `RunwayML` client using `process.env.RUNWAYML_API_SECRET`.
3. Add a function that calls `client.imageToVideo.create(...)` with the params I describe,
   then uses `.waitForTaskOutput()` to poll until the video URL is ready.
4. Add typed error handling using `TaskFailedError`, `TaskTimedOutError`, and `APIError`
   from `src/runway/index.ts`.
5. Show me where to place environment variables and how to update `tsconfig.json`
   if needed.
6. All imports must reference `src/runway/index` or `src/runway/resources/index`;
   do not use the npm package name `@runwayml/sdk` directly.

License and credit

The upstream package is @runwayml/sdk by Runway AI, Inc. The source is generated by Stainless from the RunwayML OpenAPI spec. See source/LICENSE if present for the full license text. REST API documentation: docs.dev.runwayml.com. npm: https://npmjs.org/package/@runwayml/sdk.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。

Twilio Video JavaScript SDK for Web Apps

Automation, Utilities & Developer Tools

免费