--- title: ByteDance description: Learn how to use ByteDance Seedance video and Seedream image models with the AI SDK. url: "https://ai-sdk.dev/providers/ai-sdk-providers/bytedance" docs_index: /llms.txt --- > For an index of all documentation, see [/llms.txt](/llms.txt). The [ByteDance](https://www.bytedance.com/) provider contains support for the Seedance family of video generation models and the Seedream family of image generation models through the [BytePlus ModelArk](https://docs.byteplus.com/en/docs/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](https://docs.byteplus.com/en/docs/ModelArk/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](https://docs.byteplus.com/en/docs/ModelArk/1824690)). ## Setup The ByteDance provider is available via the `@ai-sdk/bytedance` module. You can install it with **Packages:** `@ai-sdk/bytedance` ## Provider Instance You can import the default provider instance `byteDance` from `@ai-sdk/bytedance`: ```ts import { byteDance } from '@ai-sdk/bytedance'; ``` If you need a customized setup, you can import `createByteDance` and create a provider instance with your settings: ```ts import { createByteDance } from '@ai-sdk/bytedance'; const byteDance = createByteDance({ apiKey: 'your-api-key', // optional, defaults to ARK_API_KEY environment variable baseURL: 'custom-url', // optional headers: { /* custom headers */ }, // optional }); ``` 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](https://console.byteplus.com/ark/apiKey) from the BytePlus console. - **headers** *Record\* Custom headers to include in the requests. - **fetch** *(input: RequestInfo, init?: RequestInit) => Promise\* Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/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()](/docs/reference/ai-sdk-core/generate-image). ### Text-to-Image Generate images from text prompts: ```ts import { byteDance, type ByteDanceImageModelOptions } from '@ai-sdk/bytedance'; import { generateImage } from 'ai'; const { image } = await generateImage({ model: byteDance.image('seedream-5-0-260128'), prompt: 'A salamander in a forest pond at dusk surrounded by fireflies', size: '2048x2048', providerOptions: { bytedance: { watermark: false, } satisfies ByteDanceImageModelOptions, }, }); ``` ByteDance identifies Seedream models by their ModelArk model id (e.g. `seedream-5-0-260128`) or an account-specific endpoint id (e.g. `ep-...`). The `size` parameter accepts pixel dimensions (`{width}x{height}`); resolution levels such as `2K` can be passed via `providerOptions.bytedance.size`. ### Image Editing Pass input images via `prompt.images` to transform an existing image (image-to-image): ```ts import { readFileSync } from 'node:fs'; import { byteDance, type ByteDanceImageModelOptions } from '@ai-sdk/bytedance'; import { generateImage } from 'ai'; const inputImage = readFileSync('./input-image.png'); const { image } = await generateImage({ model: byteDance.image('seedream-5-0-260128'), prompt: { text: 'Change the salamander to a snow weasel', images: [inputImage], }, providerOptions: { bytedance: { watermark: false, } satisfies ByteDanceImageModelOptions, }, }); ``` 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: ```ts import { byteDance, type ByteDanceImageModelOptions } from '@ai-sdk/bytedance'; import { generateImage } from 'ai'; const { image } = await generateImage({ model: byteDance.image('seedream-5-0-260128'), prompt: { text: 'Replace the clothing in image 1 with the outfit from image 2', images: ['https://example.com/model.png', 'https://example.com/outfit.png'], }, providerOptions: { bytedance: { watermark: false, } satisfies ByteDanceImageModelOptions, }, }); ``` Seedream does not support mask-based inpainting. Describe the edit in the prompt, optionally with markers drawn on the input image (interactive editing, supported by `dola-seedream-5-0-pro-260628`). ### 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. Additional ModelArk fields can also be passed through `providerOptions.bytedance` and are validated by ModelArk. ### Image Model Capabilities | Model | Model ID | Capabilities | | ----------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | Seedream 5.0 Pro | `dola-seedream-5-0-pro-260628` | Text-to-image, single/multi image-to-image, interactive editing (markers). Sizes: 1K, 2K. Formats: png, jpeg. Up to 10 references. | | Seedream 5.0 Lite | `seedream-5-0-260128` (alias `seedream-5-0-lite-260128`) | Text-to-image, single/multi image-to-image, batch generation. Sizes: 2K, 3K, 4K. Formats: png, jpeg. Up to 14 references. | | Seedream 4.5 | `seedream-4-5-251128` | Text-to-image, single/multi image-to-image, batch generation. Sizes: 2K, 4K. Format: jpeg. Up to 14 references. | | Seedream 4.0 | `seedream-4-0-250828` | Text-to-image, single/multi image-to-image, batch generation, fast prompt mode. Sizes: 1K, 2K, 4K. Format: jpeg. Up to 14 references. | You can also pass any model or endpoint id string if needed, e.g. for future models not yet listed here. Streaming image output is not currently supported through the AI SDK integration. ## Video Models You can create ByteDance video models using the `.video()` factory method. For more on video generation with the AI SDK see [generateVideo()](/docs/reference/ai-sdk-core/generate-video). ### Text-to-Video Generate videos from text prompts: ```ts import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance'; import { experimental_generateVideo as generateVideo } from 'ai'; const { video } = await generateVideo({ model: byteDance.video('seedance-1-0-pro-250528'), prompt: '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.', aspectRatio: '16:9', duration: 5, providerOptions: { bytedance: { watermark: false, } satisfies ByteDanceVideoModelOptions, }, }); console.log(video.url); ``` ### Image-to-Video Generate videos from a first-frame image with an optional text prompt: ```ts import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance'; import { experimental_generateVideo as generateVideo } from 'ai'; const { video } = await generateVideo({ model: byteDance.video('seedance-1-5-pro-251215'), prompt: { image: 'https://example.com/first-frame.png', text: 'The cat slowly turns its head and blinks', }, duration: 5, providerOptions: { bytedance: { watermark: false, } satisfies ByteDanceVideoModelOptions, }, }); ``` When the output ratio is dictated by an input — first-frame or first-and-last-frame image-to-video, video editing, and video extension — pass `aspectRatio: 'adaptive'` or omit `aspectRatio` entirely. Newer Seedance models reject an explicit ratio on those paths, because the output inherits the ratio of the input media. ### Image-to-Video with Audio Seedance 1.5 Pro supports generating synchronized audio alongside the video: ```ts import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance'; import { experimental_generateVideo as generateVideo } from 'ai'; const { video } = await generateVideo({ model: byteDance.video('seedance-1-5-pro-251215'), prompt: { image: 'https://example.com/pianist.png', text: 'A young man sits at a piano, playing calmly. Gentle piano music plays in sync with his movements.', }, duration: 5, providerOptions: { bytedance: { generateAudio: true, watermark: false, } satisfies ByteDanceVideoModelOptions, }, }); ``` ### First-and-Last Frame Video Generate smooth transitions between a starting and ending keyframe image: ```ts import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance'; import { experimental_generateVideo as generateVideo } from 'ai'; const { video } = await generateVideo({ model: byteDance.video('seedance-1-5-pro-251215'), prompt: { image: 'https://example.com/first-frame.jpg', text: 'Create a 360-degree orbiting camera shot based on this photo', }, duration: 5, providerOptions: { bytedance: { lastFrameImage: 'https://example.com/last-frame.jpg', generateAudio: true, watermark: false, } satisfies ByteDanceVideoModelOptions, }, }); ``` ### 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: ```ts import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance'; import { experimental_generateVideo as generateVideo } from 'ai'; const { video } = await generateVideo({ model: byteDance.video('seedance-1-0-lite-i2v-250428'), prompt: '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', aspectRatio: '16:9', duration: 5, providerOptions: { bytedance: { referenceImages: [ 'https://example.com/boy.png', 'https://example.com/corgi.png', 'https://example.com/lawn.png', ], watermark: false, } satisfies ByteDanceVideoModelOptions, }, }); ``` ### Reference Video Seedance 2.0 supports reference videos that guide the style, motion, or composition of the generated video: ```ts import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance'; import { experimental_generateVideo as generateVideo } from 'ai'; const { video } = await generateVideo({ model: byteDance.video('dreamina-seedance-2-0-260128'), prompt: 'First-person perspective promotional ad, using the composition and camera movement from the reference video', aspectRatio: '16:9', duration: 4, providerOptions: { bytedance: { referenceVideos: ['https://example.com/reference-video.mp4'], watermark: false, } satisfies ByteDanceVideoModelOptions, }, }); ``` ### Reference Audio Seedance 2.0 supports reference audio that is used as background music or sound for the generated video: ```ts import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance'; import { experimental_generateVideo as generateVideo } from 'ai'; const { video } = await generateVideo({ model: byteDance.video('dreamina-seedance-2-0-260128'), prompt: 'A serene mountain landscape at sunrise with gentle camera movement', aspectRatio: '16:9', duration: 4, providerOptions: { bytedance: { referenceAudio: ['https://example.com/background-music.mp3'], generateAudio: true, watermark: false, } satisfies ByteDanceVideoModelOptions, }, }); ``` ### 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](https://docs.byteplus.com/en/docs/ModelArk/1520757) 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 })`](/docs/reference/ai-sdk-core/generate-video) 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()`](/docs/reference/ai-sdk-core/generate-video): The configured ByteDance API origin is trusted for the first status request, while every redirect to another origin is validated before it is followed. ```ts const { video } = await generateVideo({ model: byteDance.video('seedance-1-0-pro-250528'), prompt: 'A futuristic city with flying cars', poll: { intervalMs: 2000, // how often to check the task (default: 5000) timeoutMs: 900000, // give up after 15 minutes (default: 600000) }, }); ``` The `pollIntervalMs` and `pollTimeoutMs` provider options are deprecated and ignored. Passing either emits a warning. Video generation can take several minutes, so raise `poll.timeoutMs` above the 10 minute default for long jobs. ### Video Model Capabilities | Model | Model ID | Capabilities | | ----------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Seedance 2.0 | `dreamina-seedance-2-0-260128` | T2V, I2V, reference videos (up to 3), reference audio (up to 3), audio-video sync. Duration: 4-15s. Resolution: 480p, 720p. | | Seedance 2.0 Fast | `dreamina-seedance-2-0-fast-260128` | T2V, I2V, reference videos (up to 3), reference audio (up to 3), audio-video sync. Optimized for speed. Duration: 4-15s. Resolution: 480p, 720p. | | Seedance 1.5 Pro | `seedance-1-5-pro-251215` | T2V, I2V (first frame), I2V (first+last frame), audio-video sync, draft mode. Duration: 4-12s. Resolution: 480p, 720p, 1080p. | | Seedance 1.0 Pro | `seedance-1-0-pro-250528` | T2V, I2V (first frame), I2V (first+last frame). Duration: 2-12s. Resolution: 480p, 720p, 1080p. | | Seedance 1.0 Pro Fast | `seedance-1-0-pro-fast-251015` | T2V, I2V (first frame). Optimized for speed and cost. Duration: 2-12s. | | Seedance 1.0 Lite (T2V) | `seedance-1-0-lite-t2v-250428` | Text-to-video only. Duration: 2-12s. Resolution: 480p, 720p, 1080p. | | Seedance 1.0 Lite (I2V) | `seedance-1-0-lite-i2v-250428` | I2V (first frame), I2V (first+last frame), multi-reference images (1-4). Duration: 2-12s. Resolution: 480p, 720p. | 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. You can also pass any model ID string if needed, e.g. for future models not yet listed here. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)