@tanstack/ai-byteplus weekly downloads statistics

@tanstack/ai-byteplus

BytePlus ModelArk adapter for TanStack AI — Seed chat models, Seedance video generation, Seedream image generation, and Seed Speech text-to-speech and transcription.

Installation

Setup

BytePlus splits its models across two products with two different API keys:

Ark keys are region-isolated. The default base URL is the Asia-Pacific south-east endpoint (https://ark.ap-southeast.bytepluses.com/api/v3); per the BytePlus docs the EU endpoint serves chat and image only (docs-derived — only the ap-southeast host was exercised live).

Why there's no Volcengine SDK dependency

This package does not depend on @volcengine/ark-runtime (or any other first-party BytePlus/Volcengine SDK). That is deliberate:

• Chat doesn't need one. Ark's /chat/completions is OpenAI-compatible, so the chat adapter rides the openai SDK through @tanstack/openai-base — the same path @tanstack/ai-grok and @tanstack/ai-groq take, with identical dependencies. That reuses the shared streaming, tool-calling and structured-output machinery instead of forking it per provider. • Nothing else is OpenAI-shaped anyway. Seedance video, Seedream image and Seed Speech are bespoke endpoints on two different hosts with two different auth headers. An SDK would not spare us the wire types; it would add a second dependency that still had to be translated at the boundary.

The cost is that the non-chat wire types are hand-written and pinned by tests rather than generated. That is a considered trade, not an oversight — see src/video/wire-types.ts, src/image/wire-types.ts and src/audio/wire-types.ts, each of which records how its shape was verified.

Usage

Chat

Drop stream: false to get the default streaming form, which yields StreamChunks you can iterate with for await.

Seed models reason by default. Reasoning arrives as a separate stream of reasoning_content deltas and is surfaced as reasoning content, not answer text. Pass reasoning: 'off' to chat() to turn it off, on a model that can stop thinking (for example glm-5-2-260617).

Video (Seedance)

Seedance is an async task API, so generateVideo() only opens the job and returns its jobId. Poll getVideoJobStatus() until the job settles — the video URL arrives with the terminal status.

To let the core drive the whole lifecycle instead, pass stream: true and hand the resulting chunk stream to your transport:

Generated video URLs expire after 24 hours (the task record itself is kept for 7 days), so download anything you need to keep.

Image (Seedream)

size takes either a token (1K, 2K, 4K) or explicit pixels (2048x2048) — never a mix. Pass image parts in the prompt array to edit or condition on existing images (up to 14 references, 10 on dola-seedream-5-0-pro-260628).

Two behaviors surprise people:

• watermark defaults to true. BytePlus stamps "AI generated" into the bottom-right corner unless you pass watermark: false. The adapter never sets it implicitly, so the provider default applies. • numberOfImages is an upper bound, not a count. Seedream has no n parameter; asking for more than one image maps to its group-image mode (sequential_image_generation: 'auto' with max_images), where the model decides how many images the prompt actually warrants. A request for four can return fewer, and the adapter logs a warning when it does.

Result URLs expire after 24 hours; pass response_format: 'b64_json' in modelOptions to get bytes inline instead.

Supported models

• Chat — dola-seed-2-1-turbo-260628, the seed-2-0-* family, seed-1-8-251228, the seed-1-6-* family, plus glm-*, deepseek-* and gpt-oss-120b-250805. • Video — dreamina-seedance-2-5-260628, dreamina-seedance-2-0-260128 (and -fast-/-mini-), seedance-1-5-pro-251215, seedance-1-0-pro-250528, seedance-1-0-pro-fast-251015. • Image — dola-seedream-5-0-pro-260628, seedream-5-0-260128, seedream-5-0-lite-260128, seedream-4-5-251128, seedream-4-0-250828. • Speech — seed-audio-1.0 (TTS) and seed-asr (transcription).

BytePlus retires model ids aggressively, so only dated ids that were verified live against the API are exported. (The two Seed Speech ids are the exception: seed-audio-1.0 is undated, seed-asr is a synthetic id for an endpoint-addressed API that takes no model field, and neither could be verified live pending a Seed Speech key.) BYTEPLUS_CHAT_MODELS, BYTEPLUS_VIDEO_MODELS, BYTEPLUS_IMAGE_MODELS, BYTEPLUS_TTS_MODELS and BYTEPLUS_TRANSCRIPTION_MODELS are the authoritative lists.

Seedance: direct vs. via fal

Seedance is also reachable through @tanstack/ai-fal, which proxies it along with hundreds of other models. This package talks to BytePlus directly, which means BytePlus billing and rate limits, the first-class Seedance request fields (camera_fixed, generate_audio, watermark, reference-image roles, …), and model ids in BytePlus's own naming. Use whichever fits your account; there is no reason to install both for Seedance alone.

Seed Speech needs its own key

The TTS and transcription adapters do not talk to Ark. They use voice.ap-southeast-1.bytepluses.com with an X-Api-Key header and the Seed Speech product key (BYTEPLUS_VOICE_API_KEY). Passing an Ark key there fails with 45000010 Invalid X-Api-Key.

License

MIT

Description from the npm listing.