ByteDance 프로바이더

프로바이더 인스턴스 (Provider Instance)

@ai-sdk/bytedance에서 기본 프로바이더 인스턴스 byteDance를 불러올 수 있어요:

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

커스터마이즈가 필요하다면 createByteDance를 불러와 원하는 설정으로 프로바이더 인스턴스를 만들 수 있어요:

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

const byteDance = createByteDance({
  apiKey: *** // optional, defaults to ARK_API_KEY environment variable
  baseURL: 'custom-url', // optional
  headers: {
    /* custom headers */
  }, // optional
});

ByteDance 프로바이더 인스턴스를 커스터마이즈할 때 사용할 수 있는 선택적 설정은 다음과 같아요:

• baseURL string

  API 호출에 다른 URL 접두사를 사용해요. 예를 들어 프록시 서버를 쓸 때 유용해요. 기본 접두사는 https://ark.ap-southeast.bytepluses.com/api/v3이에요.

• apiKey string

  Authorization 헤더로 보내는 API 키예요. 기본값은 ARK_API_KEY 환경 변수예요. API 키를 얻을 수 있어요 BytePlus 콘솔에서.

• headers Record<string,string>

  요청에 포함할 커스텀 헤더예요.

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

  커스텀 fetch 구현이에요. 요청을 가로채는 미들웨어로 쓸 수도 있고, 예를 들어 테스트용으로 커스텀 fetch 구현을 제공할 수도 있어요.

이미지 모델 (Image Models)

.image() 팩토리 메서드로 ByteDance Seedream 이미지 모델을 만들 수 있어요. AI SDK에서 이미지 생성에 대해 더 알고 싶다면 generateImage()를 참고하세요.

텍스트-이미지 (Text-to-Image)

텍스트 프롬프트로 이미지를 생성해요:

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,
  },
});

이미지 편집 (Image Editing)

prompt.images로 입력 이미지를 전달해 기존 이미지를 변형(이미지-이미지)할 수 있어요:

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,
  },
});

여러 참조의 스타일과 요소를 하나의 출력으로 혼합하려면 여러 이미지를 전달할 수도 있어요(다중 이미지 블렌딩). 이미지는 바이너리 데이터, base64 문자열 또는 URL로 제공할 수 있어요:

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,
  },
});

이미지 모델 옵션 (Image Model Options)

providerOptions.bytedance를 통해 다음 옵션을 사용할 수 있어요. ByteDanceImageModelOptions로 타입을 지정할 수 있어요.

• watermark boolean

  출력 이미지의 오른쪽 아래 모서리에 "AI generated" 워터마크를 추가할지 여부예요.

• outputFormat 'png' | 'jpeg'

  생성된 이미지 파일의 형식이에요. seedream-5-0과 dola-seedream-5-0-pro에서 지원. seedream-4-5 / seedream-4-0은 항상 jpeg를 반환해요.

• size string

  최상위 size 파라미터로 픽셀 크기를 전달하는 대신 사용하는 해상도 수준(예: 1K, 2K, 3K, 4K)이에요. 설정하면 최상위 size를 재정의해요. 사용 가능한 수준은 모델에 따라 달라요.

• sequentialImageGeneration 'auto' | 'disabled'

  'auto'로 설정하면 관련 이미지 배치를 생성해요(예: 스토리보드나 브랜드 비주얼). 기본값은 'disabled'(단일 이미지).

• maxImages number

  sequentialImageGeneration이 'auto'일 때 생성할 최대 이미지 수예요. 입력 참조 이미지 수와 생성 이미지 수의 합은 모델의 한도를 초과할 수 없어요.

• optimizePromptMode 'standard' | 'fast'

  프롬프트 최적화 모드예요. seedream-4-0은 standard와 fast를 모두 지원하며, 다른 모델은 standard만 지원해요.

이미지 모델 기능 (Image Model Capabilities)

비디오 모델 (Video Models)

.video() 팩토리 메서드로 ByteDance 비디오 모델을 만들 수 있어요. AI SDK에서 비디오 생성에 대해 더 알고 싶다면 generateVideo()를 참고하세요.

텍스트-영상 (Text-to-Video)

텍스트 프롬프트로 비디오를 생성해요:

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)

첫 프레임 이미지와 선택적 텍스트 프롬프트로 비디오를 생성해요:

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,
  },
});

오디오가 있는 이미지-영상 (Image-to-Video with Audio)

Seedance 1.5 Pro는 비디오와 함께 동기화된 오디오 생성을 지원해요:

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)

시작 및 끝 키프레임 이미지 사이의 부드러운 전환을 생성해요:

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)

Seedance 1.0 Lite I2V 모델을 사용하면 모델이 객체 모양, 색상, 질감을 충실히 재현하는 데 사용하는 여러 참조 이미지(1-4)를 제공할 수 있어요:

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은 생성된 비디오의 스타일, 움직임 또는 구성을 안내하는 참조 비디오를 지원해요:

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은 생성된 비디오의 배경 음악이나 사운드로 사용되는 참조 오디오를 지원해요:

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)

experimental_startVideo({ model, prompt, webhookUrl })를 사용해 애플리케이션 소유 콜백 수신기를 등록해요. SDK는 webhookUrl을 callback_url로 전달하며, 이는 providerOptions.bytedance.callback_url보다 우선해요. webhookUrl을 생략하면 원래 callback_url이 변경 없이 전달돼요.

BytePlus 콜백 프로토콜은 진행 알림('queued' 또는 'running')과 종료 알림('succeeded', 'failed' 또는 'expired')을 보내요. 수신기는 진행 알림을 필터링하고 콜백을 작업과 연관시켜야 해요. experimental_startVideo가 반환한 작업과 함께 experimental_getVideoStatus(model, { operation })를 사용해 상태를 확인하고 종료 알림 후 결과를 검색하세요. 만료된 작업은 프로바이더의 진단 세부 정보와 함께 오류 상태를 반환해요.

이 모델들은 콜백 프로토콜에 진행 인식 수신기가 필요하므로 의도적으로 handleWebhookOption을 노출하지 않아요. Core generateVideo({ webhook })는 웹훅 팩토리를 호출하지 않고 폴링으로 폴백해요. 일반 generateVideo()도 폴링해요. Workflow의 기존 네이티브 웹훅 기능 확인은 이 직접 프로바이더 모델을 웹훅 기반 생성에 거부해요. 호출자 관리 콜백에는 명시적 start/status 흐름을 사용하세요.

비디오 모델 옵션 (Video Model Options)

providerOptions.bytedance를 통해 다음 옵션을 사용할 수 있어요. ByteDanceVideoModelOptions로 타입을 지정할 수 있어요.

생성 옵션 (Generation Options)

• watermark boolean

  생성된 비디오에 워터마크를 추가할지 여부예요.

• generateAudio boolean

  비디오에 동기화된 오디오를 생성할지 여부예요. Seedance 1.5 Pro와 Seedance 2.0에서 지원.

• cameraFixed boolean

  생성 중 카메라를 고정할지 여부예요.

• returnLastFrame boolean

  생성된 비디오의 마지막 프레임을 반환할지 여부예요. 연속 비디오를 이어 붙이는 데 유용.

• serviceTier 'default' | 'flex'

  추론 티어예요. 'default'는 온라인 추론. 'flex'는 가격의 50%인 오프라인 추론으로, 지연 시간이 더 길어요(응답 시간이 몇 시간 수준).

• draft boolean

  저비용 미리보기 생성을 위한 드래프트 샘플 모드를 활성화해요. Seedance 1.5 Pro에서만 지원. 전체 품질 생성에 투입하기 전에 빠른 반복을 위한 480p 미리보기 비디오를 생성해요.

이미지 입력 옵션 (Image Input Options)

• lastFrameImage string

  첫·마지막 프레임 비디오 생성을 위한 마지막 프레임 이미지 URL이에요. 모델은 (image 프롬프트로 제공된) 첫 프레임과 이 마지막 프레임 사이의 부드러운 전환을 생성해요. Seedance 1.5 Pro, 1.0 Pro, 1.0 Lite I2V에서 지원.

• referenceImages string[]

  다중 참조 이미지-영상 생성을 위한 참조 이미지 URL 배열이에요. 모델이 각 이미지의 핵심 특징을 추출해 비디오에 재현해요. 프롬프트에서 [Image 1], [Image 2] 등을 사용해 특정 이미지를 참조하세요.

미디어 참조 옵션 (Media Reference Options)

• referenceVideos string[]

  참조 안내 비디오 생성을 위한 참조 비디오 URL 배열(최대 3개, 각각 최대 15초)이에요. 모델이 참조 비디오를 사용해 스타일, 움직임 또는 구성을 안내해요. Seedance 2.0에서 지원.

• referenceAudio string[]

  오디오 안내 비디오 생성을 위한 참조 오디오 URL 배열(최대 3개, 각각 최대 15초)이에요. 모델이 참조 오디오를 배경 음악이나 동기화된 사운드로 사용해요. data URI(예: data:audio/wav;base64,...)를 지원해요. Seedance 2.0에서 지원.

폴링 옵션 (Polling Options)

ByteDance 비디오 생성은 작업 기반이에요. 프로바이더가 작업을 만들고 AI SDK가 완료될 때까지 폴링해요. generateVideo()의 최상위 poll 옵션으로 폴링을 구성하세요:

구성된 ByteDance API 원본은 첫 번째 상태 요청에 대해 신뢰되며, 다른 원본으로의 모든 리다이렉트는 따르기 전에 검증돼요.

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)
  },
});

비디오 모델 기능 (Video Model Capabilities)

지원되는 종횡비: 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive (이미지-영상만).

모든 모델은 24fps의 MP4 비디오를 출력해요.

더 알아보기 (Learn more)

• AI Gateway
• xAI Grok
• OpenAI
• Azure OpenAI
• Anthropic
• Open Responses
• Claude Platform on AWS
• Amazon Bedrock
• Groq
• Fal
• AssemblyAI
• GMI Cloud
• TypeSafe
• DeepInfra
• Deepgram
• Black Forest Labs
• Gladia
• Google
• Hume
• Google Vertex AI
• Rev.ai
• Baseten
• Hugging Face
• QuiverAI
• Fish Audio
• Mistral AI
• Z.AI
• Together.ai
• Cohere
• Fireworks
• Voyage AI
• DeepSeek
• Moonshot AI
• Alibaba
• MiniMax
• Cerebras
• Replicate
• Prodia
• Perplexity
• Luma
• ByteDance
• Kling AI
• ElevenLabs
• Cartesia

전체 사이트맵