seedance-video-sdk/README.md

Seedance AI Video Generation SDK - Create professional videos from text and images using ByteDance's advanced AI technology

# seedance-video-sdk

[![npm version](https://badge.fury.io/js/seedance-video-sdk.svg)](https://badge.fury.io/js/seedance-video-sdk)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://img.shields.io/npm/dm/seedance-video-sdk.svg)](https://www.npmjs.com/package/seedance-video-sdk)

Official Seedance AI Video Generation SDK - Create professional videos from text and images using ByteDance's advanced AI technology.

## 🚀 Features

- **Text-to-Video Generation** - Create videos from text prompts
- **Image-to-Video Generation** - Transform images into dynamic videos  
- **Multi-Shot Narrative** - Generate coherent multi-scene videos
- **Professional Quality** - Cinematic quality with natural motion
- **TypeScript Support** - Full type safety and IntelliSense
- **React Components** - Pre-built UI components for easy integration
- **Real-time Progress** - Track generation progress with webhooks or polling
- **Flexible Configuration** - Customize resolution, style, duration, and more

## 🎬 Live Demo

Try Seedance AI Video Generator: [https://seedance.studio](https://seedance.studio)

## 📦 Installation

```bash
npm install seedance-video-sdk
```

```bash
yarn add seedance-video-sdk
```

```bash
pnpm add seedance-video-sdk
```

## 🔑 Getting Started

### 1. Get Your API Key

Sign up at [Seedance Studio](https://seedance.studio) to get your API key.

### 2. Basic Usage

```typescript
import { SeedanceClient } from 'seedance-video-sdk';

const client = new SeedanceClient({
  apiKey: 'your-api-key'
});

// Generate video from text
const task = await client.generateVideo({
  prompt: 'A beautiful sunset over the ocean with gentle waves',
  duration: 5,
  resolution: '1080p',
  style: 'cinematic'
});

// Wait for completion
const completedTask = await client.waitForCompletion(task.taskId, {
  onProgress: (task) => console.log(`Progress: ${task.progress}%`)
});

console.log('Video URL:', completedTask.videoUrl);
```

### 3. Image-to-Video Generation

```typescript
// From file upload
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

const task = await client.generateVideo({
  prompt: 'Make this image come alive with gentle movement',
  image: file,
  duration: 5,
  resolution: '1080p'
});

// From URL
const task2 = await client.generateVideo({
  prompt: 'Add dynamic motion to this scene',
  image: 'https://example.com/image.jpg',
  duration: 5
});
```

## ⚛️ React Components

### VideoPlayer

```tsx
import { VideoPlayer } from 'seedance-video-sdk/react';

function MyComponent() {
  return (
    <VideoPlayer 
      src="https://example.com/video.mp4"
      poster="https://example.com/thumbnail.jpg"
      controls
      autoplay
      onLoadedData={() => console.log('Video loaded')}
      onError={(error) => console.error('Video error:', error)}
    />
  );
}
```

### ProgressIndicator

```tsx
import { ProgressIndicator } from 'seedance-video-sdk/react';

function GenerationStatus({ task }) {
  return (
    <ProgressIndicator 
      progress={task.progress}
      status={task.status}
      estimatedTime={task.estimatedTime}
      showPercentage
      showStatus
    />
  );
}
```

## 🛠️ Advanced Usage

### Custom Configuration

```typescript
const client = new SeedanceClient({
  apiKey: 'your-api-key',
  baseURL: 'https://api.seedance.studio/v1', // Custom endpoint
  timeout: 60000, // 60 seconds
  debug: true // Enable debug logging
});
```

### Webhook Integration

```typescript
// Configure webhook for real-time notifications
await client.configureWebhook({
  url: 'https://your-app.com/webhooks/seedance',
  events: ['task.completed', 'task.failed'],
  secret: 'your-webhook-secret'
});
```

### Batch Processing

```typescript
// Generate multiple videos
const prompts = [
  'A cat playing in a garden',
  'City skyline at night',
  'Ocean waves crashing on rocks'
];

const tasks = await Promise.all(
  prompts.map(prompt => 
    client.generateVideo({
      prompt,
      duration: 5,
      resolution: '720p'
    })
  )
);

// Wait for all to complete
const results = await Promise.all(
  tasks.map(task => client.waitForCompletion(task.taskId))
);
```

### Error Handling

```typescript
try {
  const task = await client.generateVideo({
    prompt: 'A beautiful landscape',
    duration: 5
  });
} catch (error) {
  if (error.code === 'QUOTA_EXCEEDED') {
    console.log('Please upgrade your plan');
  } else if (error.code === 'INVALID_PROMPT') {
    console.log('Please provide a valid prompt');
  } else {
    console.error('Generation failed:', error.message);
  }
}
```

## 📚 API Reference

### SeedanceClient

#### Methods

- `generateVideo(request)` - Generate a video from text/image
- `getTask(taskId)` - Get task status and details
- `listTasks(options)` - List user's video tasks
- `cancelTask(taskId)` - Cancel a pending task
- `deleteTask(taskId)` - Delete a completed task
- `uploadImage(image)` - Upload image for later use
- `getQuota()` - Get user quota information
- `waitForCompletion(taskId, options)` - Wait for task completion

### Types

```typescript
interface VideoGenerationRequest {
  prompt: string;
  image?: File | string | Buffer;
  duration?: number; // 1-30 seconds
  resolution?: '480p' | '720p' | '1080p' | '4K';
  style?: 'realistic' | 'anime' | 'cartoon' | 'cinematic' | 'artistic';
  aspectRatio?: '16:9' | '9:16' | '1:1' | '4:3' | '3:4';
  frameRate?: number; // 12-60 fps
  parameters?: GenerationParameters;
}
```

## 🎨 Examples

Check out our [examples directory](./examples) for complete implementation examples:

- [Basic Text-to-Video](./examples/basic-text-to-video)
- [Image-to-Video with React](./examples/react-image-to-video)
- [Batch Processing](./examples/batch-processing)
- [Webhook Integration](./examples/webhook-integration)
- [Next.js Integration](./examples/nextjs-integration)

## 🔗 Links

- **Website**: [https://seedance.studio](https://seedance.studio)
- **Documentation**: [https://docs.seedance.studio](https://docs.seedance.studio)
- **GitHub**: [https://github.com/saasfly/saasfly](https://github.com/saasfly/saasfly)
- **Support**: [contact@seedance.studio](mailto:contact@seedance.studio)

## 📄 License

MIT License - see the [LICENSE](LICENSE) file for details.

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 💬 Support

- 📧 Email: [contact@seedance.studio](mailto:contact@seedance.studio)
- 💬 Discord: [Join our community](https://discord.gg/seedance)
- 📖 Documentation: [docs.seedance.studio](https://docs.seedance.studio)

---

Made with ❤️ by [Seedance Studio](https://seedance.studio)