ByteDance Provider

The ByteDance provider contains support for the Seedance family of video generation models and the Seedream family of image generation models through the BytePlus ModelArk platform. Seedance provides high-quality text-to-video and image-to-video generation capabilities, including audio-video synchronization, first-and-last frame control, and multi-reference image generation (see the video generation API). Seedream provides text-to-image and image-to-image generation, including multi-image blending and batch image generation (see the image generation API).

Setup

The ByteDance provider is available via the @ai-sdk/bytedance module. You can install it with

pnpm add @ai-sdk/bytedance

Provider Instance

You can import the default provider instance byteDance from @ai-sdk/bytedance:

1
import { byteDance } from '@ai-sdk/bytedance';

If you need a customized setup, you can import createByteDance and create a provider instance with your settings:

1
import { createByteDance } from '@ai-sdk/bytedance';
2

3
const byteDance = createByteDance({
4
  apiKey: 'your-api-key', // optional, defaults to ARK_API_KEY environment variable
5
  baseURL: 'custom-url', // optional
6
  headers: {
7
    /* custom headers */
8
  }, // optional
9
});

You can use the following optional settings to customize the ByteDance provider instance:

• baseURL string

  Use a different URL prefix for API calls, e.g. to use proxy servers. The default prefix is https://ark.ap-southeast.bytepluses.com/api/v3.

• apiKey string

  API key that is being sent using the Authorization header. It defaults to the ARK_API_KEY environment variable. You can obtain an API key from the BytePlus console.

• headers Record<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom fetch implementation. You can use it as a middleware to intercept requests, or to provide a custom fetch implementation for e.g. testing.

Image Models

You can create ByteDance Seedream image models using the .image() factory method. For more on image generation with the AI SDK see generateImage().

Text-to-Image

Generate images from text prompts:

1
import { byteDance, type ByteDanceImageModelOptions } from '@ai-sdk/bytedance';
2
import { generateImage } from 'ai';
3

4
const { image } = await generateImage({
5
  model: byteDance.image('seedream-5-0-260128'),
6
  prompt: 'A salamander in a forest pond at dusk surrounded by fireflies',
7
  size: '2048x2048',
8
  providerOptions: {
9
    bytedance: {
10
      watermark: false,
11
    } satisfies ByteDanceImageModelOptions,
12
  },
13
});

Image Editing

Pass input images via prompt.images to transform an existing image (image-to-image):

1
import { readFileSync } from 'node:fs';
2
import { byteDance, type ByteDanceImageModelOptions } from '@ai-sdk/bytedance';
3
import { generateImage } from 'ai';
4

5
const inputImage = readFileSync('./input-image.png');
6

7
const { image } = await generateImage({
8
  model: byteDance.image('seedream-5-0-260128'),
9
  prompt: {
10
    text: 'Change the salamander to a snow weasel',
11
    images: [inputImage],
12
  },
13
  providerOptions: {
14
    bytedance: {
15
      watermark: false,
16
    } satisfies ByteDanceImageModelOptions,
17
  },
18
});

You can also pass multiple images to blend styles and elements from several references into a single output (multi-image blending). Images may be provided as binary data, base64 strings, or URLs:

1
import { byteDance, type ByteDanceImageModelOptions } from '@ai-sdk/bytedance';
2
import { generateImage } from 'ai';
3

4
const { image } = await generateImage({
5
  model: byteDance.image('seedream-5-0-260128'),
6
  prompt: {
7
    text: 'Replace the clothing in image 1 with the outfit from image 2',
8
    images: ['https://example.com/model.png', 'https://example.com/outfit.png'],
9
  },
10
  providerOptions: {
11
    bytedance: {
12
      watermark: false,
13
    } satisfies ByteDanceImageModelOptions,
14
  },
15
});

Image Model Options

The following options are available via providerOptions.bytedance. You can type them with ByteDanceImageModelOptions.

• watermark boolean

  Whether to add an "AI generated" watermark to the bottom-right corner of the output image.

• outputFormat 'png' | 'jpeg'

  Format of the generated image file. Supported by seedream-5-0 and dola-seedream-5-0-pro; seedream-4-5 / seedream-4-0 always return jpeg.

• size string

  A resolution level (e.g. 1K, 2K, 3K, 4K) as an alternative to passing pixel dimensions via the top-level size parameter. When set, this overrides the top-level size. Available levels vary by model.

• sequentialImageGeneration 'auto' | 'disabled'

  Set to 'auto' to generate a batch of related images (e.g. storyboards or brand visuals). Defaults to 'disabled' (single image).

• maxImages number

  Maximum number of images to generate when sequentialImageGeneration is 'auto'. The number of input reference images plus generated images must not exceed the model's limit.

• optimizePromptMode 'standard' | 'fast'

  Prompt optimization mode. seedream-4-0 supports both standard and fast; other models support standard only.

Image Model Capabilities

Video Models

You can create ByteDance video models using the .video() factory method. For more on video generation with the AI SDK see generateVideo().

Text-to-Video

Generate videos from text prompts:

1
import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance';
2
import { experimental_generateVideo as generateVideo } from 'ai';
3

4
const { video } = await generateVideo({
5
  model: byteDance.video('seedance-1-0-pro-250528'),
6
  prompt:
7
    'Photorealistic style: Under a clear blue sky, a vast expanse of white daisy fields stretches out. The camera gradually zooms in and fixates on a close-up of a single daisy.',
8
  aspectRatio: '16:9',
9
  duration: 5,
10
  providerOptions: {
11
    bytedance: {
12
      watermark: false,
13
    } satisfies ByteDanceVideoModelOptions,
14
  },
15
});
16

17
console.log(video.url);

Image-to-Video

Generate videos from a first-frame image with an optional text prompt:

1
import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance';
2
import { experimental_generateVideo as generateVideo } from 'ai';
3

4
const { video } = await generateVideo({
5
  model: byteDance.video('seedance-1-5-pro-251215'),
6
  prompt: {
7
    image: 'https://example.com/first-frame.png',
8
    text: 'The cat slowly turns its head and blinks',
9
  },
10
  duration: 5,
11
  providerOptions: {
12
    bytedance: {
13
      watermark: false,
14
    } satisfies ByteDanceVideoModelOptions,
15
  },
16
});

Image-to-Video with Audio

Seedance 1.5 Pro supports generating synchronized audio alongside the video:

1
import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance';
2
import { experimental_generateVideo as generateVideo } from 'ai';
3

4
const { video } = await generateVideo({
5
  model: byteDance.video('seedance-1-5-pro-251215'),
6
  prompt: {
7
    image: 'https://example.com/pianist.png',
8
    text: 'A young man sits at a piano, playing calmly. Gentle piano music plays in sync with his movements.',
9
  },
10
  duration: 5,
11
  providerOptions: {
12
    bytedance: {
13
      generateAudio: true,
14
      watermark: false,
15
    } satisfies ByteDanceVideoModelOptions,
16
  },
17
});

First-and-Last Frame Video

Generate smooth transitions between a starting and ending keyframe image:

1
import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance';
2
import { experimental_generateVideo as generateVideo } from 'ai';
3

4
const { video } = await generateVideo({
5
  model: byteDance.video('seedance-1-5-pro-251215'),
6
  prompt: {
7
    image: 'https://example.com/first-frame.jpg',
8
    text: 'Create a 360-degree orbiting camera shot based on this photo',
9
  },
10
  duration: 5,
11
  providerOptions: {
12
    bytedance: {
13
      lastFrameImage: 'https://example.com/last-frame.jpg',
14
      generateAudio: true,
15
      watermark: false,
16
    } satisfies ByteDanceVideoModelOptions,
17
  },
18
});

Multi-Reference Image-to-Video

Using the Seedance 1.0 Lite I2V model, you can provide multiple reference images (1-4) that the model uses to faithfully reproduce object shapes, colors, and textures:

1
import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance';
2
import { experimental_generateVideo as generateVideo } from 'ai';
3

4
const { video } = await generateVideo({
5
  model: byteDance.video('seedance-1-0-lite-i2v-250428'),
6
  prompt:
7
    'A boy wearing glasses and a blue T-shirt from [Image 1] and a corgi dog from [Image 2], sitting on the lawn from [Image 3], in 3D cartoon style',
8
  aspectRatio: '16:9',
9
  duration: 5,
10
  providerOptions: {
11
    bytedance: {
12
      referenceImages: [
13
        'https://example.com/boy.png',
14
        'https://example.com/corgi.png',
15
        'https://example.com/lawn.png',
16
      ],
17
      watermark: false,
18
    } satisfies ByteDanceVideoModelOptions,
19
  },
20
});

Reference Video

Seedance 2.0 supports reference videos that guide the style, motion, or composition of the generated video:

1
import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance';
2
import { experimental_generateVideo as generateVideo } from 'ai';
3

4
const { video } = await generateVideo({
5
  model: byteDance.video('dreamina-seedance-2-0-260128'),
6
  prompt:
7
    'First-person perspective promotional ad, using the composition and camera movement from the reference video',
8
  aspectRatio: '16:9',
9
  duration: 4,
10
  providerOptions: {
11
    bytedance: {
12
      referenceVideos: ['https://example.com/reference-video.mp4'],
13
      watermark: false,
14
    } satisfies ByteDanceVideoModelOptions,
15
  },
16
});

Reference Audio

Seedance 2.0 supports reference audio that is used as background music or sound for the generated video:

1
import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance';
2
import { experimental_generateVideo as generateVideo } from 'ai';
3

4
const { video } = await generateVideo({
5
  model: byteDance.video('dreamina-seedance-2-0-260128'),
6
  prompt: 'A serene mountain landscape at sunrise with gentle camera movement',
7
  aspectRatio: '16:9',
8
  duration: 4,
9
  providerOptions: {
10
    bytedance: {
11
      referenceAudio: ['https://example.com/background-music.mp3'],
12
      generateAudio: true,
13
      watermark: false,
14
    } satisfies ByteDanceVideoModelOptions,
15
  },
16
});

Caller-Managed Callbacks

Use experimental_startVideo({ model, prompt, webhookUrl }) to register an application-owned callback receiver. The SDK forwards webhookUrl as callback_url, taking precedence over providerOptions.bytedance.callback_url. When webhookUrl is omitted, a raw callback_url is passed through unchanged.

The BytePlus callback protocol sends progress notifications ('queued' or 'running') as well as terminal notifications ('succeeded', 'failed', or 'expired'). Your receiver must filter progress notifications and correlate callbacks with the task. Use experimental_getVideoStatus(model, { operation }) with the operation returned by experimental_startVideo to check status and retrieve the result after a terminal notification. Expired tasks return an error status with the provider's diagnostic details.

These models deliberately do not expose handleWebhookOption because their callback protocol requires a progress-aware receiver. Core generateVideo({ webhook }) falls back to polling without calling the webhook factory. Plain generateVideo() also polls. Workflow's existing native webhook capability check rejects these direct provider models for webhook-based generation; use the explicit start/status flow for caller-managed callbacks.

Video Model Options

The following options are available via providerOptions.bytedance. You can type them with ByteDanceVideoModelOptions.

Generation Options

• watermark boolean

  Whether to add a watermark to the generated video.

• generateAudio boolean

  Whether to generate synchronized audio for the video. Supported by Seedance 1.5 Pro and Seedance 2.0.

• cameraFixed boolean

  Whether to fix the camera during generation.

• returnLastFrame boolean

  Whether to return the last frame of the generated video. Useful for chaining consecutive videos.

• serviceTier 'default' | 'flex'

  Inference tier. 'default' for online inference. 'flex' for offline inference at 50% of the price, with higher latency (response times on the order of hours).

• draft boolean

  Enable draft sample mode for low-cost preview generation. Only supported by Seedance 1.5 Pro. Generates a 480p preview video for rapid iteration before committing to a full-quality generation.

Image Input Options

• lastFrameImage string

  URL of the last frame image for first-and-last frame video generation. The model generates smooth transitions between the first frame (provided via the image prompt) and this last frame. Supported by Seedance 1.5 Pro, 1.0 Pro, and 1.0 Lite I2V.

• referenceImages string[]

  Array of reference image URLs for multi-reference image-to-video generation. The model extracts key features from each image and reproduces them in the video. Use [Image 1], [Image 2], etc. in your prompt to reference specific images.

Media Reference Options

• referenceVideos string[]

  Array of reference video URLs (up to 3 videos, max 15 seconds each) for reference-guided video generation. The model uses the referenced videos to guide style, motion, or composition. Supported by Seedance 2.0.

• referenceAudio string[]

  Array of reference audio URLs (up to 3, max 15 seconds each) for audio-guided video generation. The model uses the referenced audio as background music or synchronized sound. Supports data URIs (e.g., data:audio/wav;base64,...). Supported by Seedance 2.0.

Polling Options

ByteDance video generation is task-based: the provider creates a task and the AI SDK polls it until it completes. Configure polling with the top-level poll option of generateVideo():

The configured ByteDance API origin is trusted for the first status request, while every redirect to another origin is validated before it is followed.

1
const { video } = await generateVideo({
2
  model: byteDance.video('seedance-1-0-pro-250528'),
3
  prompt: 'A futuristic city with flying cars',
4
  poll: {
5
    intervalMs: 2000, // how often to check the task (default: 5000)
6
    timeoutMs: 900000, // give up after 15 minutes (default: 600000)
7
  },
8
});

Video Model Capabilities

Supported aspect ratios: 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive (image-to-video only).

All models output MP4 video at 24 fps.