Open History to see the last commit
1/**
2 * BytePlus (ModelArk + Seed Speech) — SDK-generated specs, live models.
3 *
4 * BytePlus publishes no OpenAPI document: `/openapi.json`, `/swagger.json`
5 * and `/docs` on the Ark data plane all answer 200 with an EMPTY body (a
6 * catch-all, not a document — re-probed with a real key 2026-08-12), and the
7 * genuine per-action documents live behind the console's API Explorer, which
8 * needs an interactive login.
9 *
10 * It does, however, publish an official Go SDK whose model package declares
11 * the entire Ark data plane as `json:"…"`-tagged structs. Those are plain
12 * text, so `fetchSpec` pulls them from GitHub on the ordinary spec-sync cron
13 * and `byteplus-ark-build.ts` turns them into the Ark document — the spec
14 * tracks upstream SDK releases with no codegen step and no committed
15 * artifact. `byteplus-spec.ts` keeps the hand-ported document as the fallback
16 * for when GitHub is unreachable or the SDK is refactored past what the
17 * parser handles.
18 *
19 * Seed Speech appears in no BytePlus SDK in any language, so the voice
20 * document stays hand-written.
21 *
22 * The MODEL CATALOG is different: Ark's data-plane `GET /models` is a real,
23 * richly-typed source (created / task_type / token_limits / modalities /
24 * features / status), so `listModels` prefers it whenever `ARK_API_KEY` is
25 * set. Two things keep the curated catalog alive underneath it:
26 *
27 * 1. The listing is NOT exhaustive — `seedream-5-0-lite-260128` answers
28 * requests but is absent from it (confirmed live 2026-08-12).
29 * 2. Seed Speech (TTS/ASR) lives on a different host entirely and appears in
30 * no Ark listing.
31 *
32 * So the live rows win where they exist and the curated entries fill the
33 * gaps; with no key at all the provider still serves the curated catalog
34 * rather than reporting itself skipped.
35 */
36import type { Activity } from '#/db/schema.ts'
37import { errorMessage } from '#/server/errors.ts'
38import { contentHash } from '#/server/kv.ts'
39import {
40 ARK_GO_FILES,
41 ARK_GO_SOURCE_URL,
42 arkGoFileUrl,
43 buildArkSpecFromGo,
44} from './byteplus-ark-build.ts'
45import { byteplusModelPricing } from './byteplus-pricing.ts'
46import {
47 byteplusModelReasoning,
48 listsReasoning,
49 overlayModelFacts,
50} from './reasoning-config.ts'
51import { bearerConnect, headerApiKeyConnect } from './connect.ts'
52import {
53 BYTEPLUS_ARK_BASE_URL,
54 BYTEPLUS_ARK_DOCS_URL,
55 BYTEPLUS_VOICE_BASE_URL,
56 BYTEPLUS_VOICE_DOCS_URL,
57 bytePlusArkSpec,
58 bytePlusVoiceSpec,
59} from './byteplus-spec.ts'
60import { githubRequestInit } from './github.ts'
61import { byteplusGenerationEndpointId } from './model-meta.ts'
62import { byteplusIdSuffixDate } from './release-dates.ts'
63import { fetchJson, fetchText, sha256Text } from './types.ts'
64import type {
65 ListModelsResult,
66 ModelInfo,
67 OpenApiDocument,
68 ProviderConfig,
69 ProviderSecrets,
70 SpecFetchResult,
71 SpecSource,
72} from './types.ts'
73
74const ARK_MODELS_URL = 'https://ark.ap-southeast.bytepluses.com/api/v3/models'
75
76/**
77 * Both hosts' generation surfaces classify by exact path (the Ark and voice
78 * documents have no overlapping paths).
79 */
80function classify(path: string): Activity | null {
81 if (path === '/chat/completions') return 'chat'
82 if (path === '/images/generations') return 'image'
83 if (
84 path === '/contents/generations/tasks' ||
85 path === '/contents/generations/tasks/{id}'
86 ) {
87 return 'video'
88 }
89 if (path === '/tts/create' || path === '/auc/bigmodel/recognize/flash') {
90 return 'audio'
91 }
92 return null
93}
94
95/**
96 * Ark half: generated from BytePlus's Go SDK so it tracks upstream releases.
97 * Falls back to the embedded document — never to nothing — if GitHub is
98 * unreachable or the SDK is refactored beyond what the parser handles, so a
99 * bad upstream day degrades the spec's freshness rather than the service.
100 */
101async function fetchArkSpec(env: ProviderSecrets): Promise<{
102 spec: OpenApiDocument
103 source: SpecSource
104 warnings: Array<string>
105}> {
106 try {
107 const files = await Promise.all(
108 ARK_GO_FILES.map(async (name) => {
109 const url = arkGoFileUrl(name)
110 return {
111 name,
112 // Raw host: githubRequestInit leaves these unauthenticated.
113 text: await fetchText(url, githubRequestInit(url, env)),
114 }
115 }),
116 )
117 const { spec, warnings } = buildArkSpecFromGo(files)
118 return {
119 spec,
120 source: {
121 url: ARK_GO_SOURCE_URL,
122 // One document from many files: hash their concatenation in the
123 // fixed ARK_GO_FILES order so the digest is reproducible.
124 hash: await sha256Text(files.map((f) => f.text).join('')),
125 },
126 warnings,
127 }
128 } catch (error) {
129 const spec = bytePlusArkSpec()
130 return {
131 spec,
132 source: { url: BYTEPLUS_ARK_DOCS_URL, hash: await contentHash(spec) },
133 warnings: [
134 `byteplus: Go SDK spec generation failed (${errorMessage(error)}) — served the embedded Ark document instead`,
135 ],
136 }
137 }
138}
139
140async function fetchSpec(env: ProviderSecrets): Promise<SpecFetchResult> {
141 const ark = await fetchArkSpec(env)
142 // Seed Speech appears in no BytePlus SDK in any language, so the voice
143 // document stays hand-written; provenance hashes the document itself (the
144 // FAL embedded-spec precedent).
145 const voice = bytePlusVoiceSpec()
146 return {
147 specs: [ark.spec, voice],
148 sources: [
149 ark.source,
150 { url: BYTEPLUS_VOICE_DOCS_URL, hash: await contentHash(voice) },
151 ],
152 outputStrategy: 'post-200',
153 warnings: ark.warnings,
154 }
155}
156
157interface CuratedModel {
158 rawId: string
159 activity: Activity
160 contextWindow?: number
161 maxOutput?: number
162 input: Array<string>
163 output: Array<string>
164 capabilities?: unknown
165}
166
167const chat = (
168 rawId: string,
169 maxOutput: number,
170 capabilities: Array<string>,
171 input: Array<string> = ['text'],
172 contextWindow = 256_000,
173): CuratedModel => ({
174 rawId,
175 activity: 'chat',
176 contextWindow,
177 maxOutput,
178 input,
179 output: ['text'],
180 capabilities,
181})
182
183const TIV = ['text', 'image', 'video']
184const TIVA = ['text', 'image', 'video', 'audio']
185const REASON_TOOLS = ['reasoning', 'tools', 'tool_choice']
186const REASON_TOOLS_SO = [
187 ...REASON_TOOLS,
188 'response_format',
189 'structured_outputs',
190]
191
192const video = (
193 rawId: string,
194 input: Array<string>,
195 output: Array<string>,
196 resolutions: Array<string>,
197 duration: { min: number; max: number },
198): CuratedModel => ({
199 rawId,
200 activity: 'video',
201 input,
202 output,
203 capabilities: { resolutions, duration },
204})
205
206const image = (rawId: string, maxReferenceImages: number): CuratedModel => ({
207 rawId,
208 activity: 'image',
209 input: ['text', 'image'],
210 output: ['image'],
211 capabilities: { maxReferenceImages, sizeTokens: ['1K', '2K', '4K'] },
212})
213
214/**
215 * Ported from `@tanstack/ai-byteplus` `model-meta.ts` (context windows,
216 * max-output, modalities, and the probed structured-output verdicts — the
217 * BytePlus capability tables are wrong in both directions, so the probe
218 * results are authoritative).
219 */
220const BYTEPLUS_MODELS: Array<CuratedModel> = [
221 // Chat (Seed / GLM / DeepSeek / gpt-oss on Ark)
222 chat('dola-seed-2-1-turbo-260628', 256_000, REASON_TOOLS_SO, TIV),
223 chat('seed-2-0-lite-260428', 128_000, REASON_TOOLS, TIVA),
224 chat('seed-2-0-mini-260428', 128_000, REASON_TOOLS, TIVA),
225 chat('seed-2-0-pro-260328', 128_000, REASON_TOOLS_SO, TIV),
226 chat('seed-2-0-lite-260228', 128_000, REASON_TOOLS_SO, TIV),
227 chat('seed-2-0-mini-260215', 128_000, REASON_TOOLS_SO, TIV),
228 chat('seed-2-0-code-preview-260328', 128_000, REASON_TOOLS, TIV),
229 chat('seed-1-8-251228', 64_000, REASON_TOOLS_SO, TIV),
230 chat('seed-1-6-250915', 32_000, REASON_TOOLS_SO, TIV),
231 chat('seed-1-6-250615', 32_000, REASON_TOOLS_SO, TIV),
232 chat('seed-1-6-flash-250715', 32_000, REASON_TOOLS_SO, TIV),
233 chat('seed-1-6-flash-250615', 32_000, REASON_TOOLS_SO, TIV),
234 chat('glm-5-2-260617', 128_000, REASON_TOOLS_SO, ['text'], 1_024_000),
235 chat('glm-4-7-251222', 128_000, REASON_TOOLS),
236 chat('deepseek-v4-pro-260425', 384_000, REASON_TOOLS, ['text'], 1_024_000),
237 chat('deepseek-v4-flash-260425', 384_000, REASON_TOOLS, ['text'], 1_024_000),
238 chat('deepseek-v3-2-251201', 32_000, REASON_TOOLS, ['text'], 128_000),
239 chat('gpt-oss-120b-250805', 64_000, ['reasoning'], ['text'], 128_000),
240 // Video (Seedance, async task API)
241 video(
242 'dreamina-seedance-2-5-260628',
243 TIVA,
244 ['video', 'audio'],
245 ['480p', '720p'],
246 { min: 4, max: 30 },
247 ),
248 video(
249 'dreamina-seedance-2-0-260128',
250 TIVA,
251 ['video', 'audio'],
252 ['480p', '720p', '1080p', '4k'],
253 { min: 4, max: 15 },
254 ),
255 video(
256 'dreamina-seedance-2-0-fast-260128',
257 TIVA,
258 ['video', 'audio'],
259 ['480p', '720p'],
260 { min: 4, max: 15 },
261 ),
262 video(
263 'dreamina-seedance-2-0-mini-260615',
264 TIVA,
265 ['video', 'audio'],
266 ['480p', '720p'],
267 { min: 4, max: 15 },
268 ),
269 video(
270 'seedance-1-5-pro-251215',
271 ['text', 'image'],
272 ['video', 'audio'],
273 ['480p', '720p', '1080p'],
274 { min: 4, max: 12 },
275 ),
276 video(
277 'seedance-1-0-pro-250528',
278 ['text', 'image'],
279 ['video'],
280 ['480p', '720p', '1080p'],
281 { min: 2, max: 12 },
282 ),
283 video(
284 'seedance-1-0-pro-fast-251015',
285 ['text', 'image'],
286 ['video'],
287 ['480p', '720p', '1080p'],
288 { min: 2, max: 12 },
289 ),
290 // Image (Seedream)
291 image('dola-seedream-5-0-pro-260628', 10),
292 image('seedream-5-0-260128', 14),
293 image('seedream-5-0-lite-260128', 14),
294 image('seedream-4-5-251128', 14),
295 image('seedream-4-0-250828', 14),
296 // Seed Speech (voice host — separate product and API key)
297 {
298 rawId: 'seed-audio-1.0',
299 activity: 'audio',
300 input: ['text', 'audio'],
301 output: ['audio'],
302 },
303 {
304 rawId: 'seed-asr',
305 activity: 'audio',
306 input: ['audio'],
307 output: ['text'],
308 },
309]
310
311function curatedModels(): Array<ModelInfo> {
312 return BYTEPLUS_MODELS.map((m) => ({
313 rawId: m.rawId,
314 activity: m.activity,
315 contextWindow: m.contextWindow ?? null,
316 maxOutput: m.maxOutput ?? null,
317 modalities: { input: m.input, output: m.output },
318 // A chat row's list is flags; an image or video row's object is the
319 // provider's own description of the model.
320 ...(Array.isArray(m.capabilities)
321 ? { capabilities: m.capabilities }
322 : m.capabilities
323 ? { providerMetadata: m.capabilities as Record<string, unknown> }
324 : {}),
325 // Dated ids embed their release as a -YYMMDD suffix; the undated Seed
326 // Speech ids keep their poll-time firstSeenAt.
327 releasedAt: byteplusIdSuffixDate(m.rawId),
328 }))
329}
330
331/**
332 * Ark reports one or more `task_type`s per model. Highest-precedence match
333 * wins: a chat model that also accepts audio input carries `SpeechToText`
334 * alongside `TextGeneration` (e.g. seed-2-0-lite-260428) and must classify as
335 * `chat`, not `audio`, so the generation task types are checked first.
336 * 3D-generation models carry no task_type at all and fall through to null —
337 * the same treatment FAL's `text-to-3d` gets until the taxonomy grows.
338 */
339const ARK_TASK_ACTIVITIES: Array<[Activity, Array<string>]> = [
340 [
341 'video',
342 [
343 'TextToVideo',
344 'ImageToVideo',
345 'MultimodalToVideo',
346 'VideoEditing',
347 'VideoExtension',
348 ],
349 ],
350 ['image', ['TextToImage', 'ImageToImage']],
351 ['embeddings', ['TextEmbedding', 'ImageEmbedding', 'MultimodalEmbedding']],
352 ['chat', ['TextGeneration', 'VisualQuestionAnswering']],
353 ['audio', ['SpeechToText', 'TextToSpeech']],
354]
355
356export function arkTaskActivity(
357 taskTypes: Array<string> | undefined,
358): Activity | null {
359 if (!taskTypes?.length) return null
360 for (const [activity, types] of ARK_TASK_ACTIVITIES) {
361 if (taskTypes.some((t) => types.includes(t))) return activity
362 }
363 return null
364}
365
366interface ArkModel {
367 id: string
368 name?: string
369 created?: number
370 /** Absent for live models; 'Shutdown' / 'Retiring' once wound down. */
371 status?: string
372 domain?: string
373 task_type?: Array<string>
374 modalities?: {
375 input_modalities?: Array<string>
376 output_modalities?: Array<string>
377 }
378 token_limits?: {
379 context_window?: number
380 max_input_token_length?: number
381 max_output_token_length?: number
382 max_reasoning_token_length?: number
383 }
384 features?: Record<string, unknown>
385 version?: string
386}
387
388/**
389 * Ark's `features.structured_outputs.json_schema` is NOT reliable: probed
390 * 2026-08-12, `seed-2-0-lite-260428` advertises `json_schema: true` and then
391 * answers a schema-bearing request with
392 * `400 InvalidParameter … json_schema is not supported by this model`, while
393 * `seed-2-0-lite-260228` (same family) accepts one. Both outcomes match
394 * TanStack AI's 2026-07-31 sweep of all 18 chat models, so their probe
395 * verdicts are carried here as a separate, clearly-labelled capability rather
396 * than letting the upstream flag stand alone. Ids outside this set get no
397 * verdict (absence ≠ unsupported).
398 */
399const PROBED_STRUCTURED_OUTPUT: Record<string, boolean> = {
400 'dola-seed-2-1-turbo-260628': true,
401 'seed-2-0-pro-260328': true,
402 'seed-2-0-lite-260228': true,
403 'seed-2-0-mini-260215': true,
404 'seed-1-8-251228': true,
405 'seed-1-6-250915': true,
406 'seed-1-6-250615': true,
407 'seed-1-6-flash-250715': true,
408 'seed-1-6-flash-250615': true,
409 'glm-5-2-260617': true,
410 'seed-2-0-lite-260428': false,
411 'seed-2-0-mini-260428': false,
412 'seed-2-0-code-preview-260328': false,
413 'deepseek-v4-pro-260425': false,
414 'deepseek-v4-flash-260425': false,
415 'deepseek-v3-2-251201': false,
416 'gpt-oss-120b-250805': false,
417 // Accepts the request with 200 but ignores the schema and answers in prose
418 // — a status-code-only probe reads this as support.
419 'glm-4-7-251222': false,
420}
421
422interface ArkFeatures {
423 structured_outputs?: { json_object?: boolean; json_schema?: boolean }
424 tools?: { function_calling?: boolean }
425}
426
427/**
428 * Chat rows speak the shared OpenRouter parameter vocabulary (#53, #76).
429 * The probe verdict beats Ark's `json_schema` flag whenever one exists.
430 */
431export function arkChatCapabilities(m: ArkModel): Array<string> {
432 const features = (m.features ?? {}) as ArkFeatures
433 const caps: Array<string> = []
434 if (features.tools?.function_calling) caps.push('tools', 'tool_choice')
435 if ((m.token_limits?.max_reasoning_token_length ?? 0) > 0) {
436 caps.push('reasoning')
437 }
438 const structured =
439 PROBED_STRUCTURED_OUTPUT[m.id] ??
440 features.structured_outputs?.json_schema === true
441 if (structured || features.structured_outputs?.json_object) {
442 caps.push('response_format')
443 }
444 if (structured) caps.push('structured_outputs')
445 return caps
446}
447
448function toModelInfo(m: ArkModel): ModelInfo {
449 const probed = PROBED_STRUCTURED_OUTPUT[m.id]
450 const activity = arkTaskActivity(m.task_type)
451 return {
452 rawId: m.id,
453 displayName: m.name ?? null,
454 activity,
455 contextWindow: m.token_limits?.context_window ?? null,
456 maxOutput: m.token_limits?.max_output_token_length ?? null,
457 modalities: {
458 input: m.modalities?.input_modalities,
459 output: m.modalities?.output_modalities,
460 },
461 ...(activity === 'chat'
462 ? { capabilities: arkChatCapabilities(m) }
463 : {
464 providerMetadata: {
465 ...m.features,
466 taskType: m.task_type,
467 domain: m.domain || undefined,
468 maxReasoningTokens: m.token_limits?.max_reasoning_token_length,
469 // Distinct key from the upstream `structured_outputs` block
470 // above so the disagreement stays visible.
471 ...(probed === undefined ? {} : { structuredOutputProbed: probed }),
472 },
473 }),
474 // 'Retiring' models still serve but are on the way out; both states are
475 // deprecation signals for consumers picking a model today.
476 deprecated: m.status === 'Shutdown' || m.status === 'Retiring',
477 releasedAt: m.created ?? byteplusIdSuffixDate(m.id),
478 }
479}
480
481async function listModels(
482 env: ProviderSecrets,
483 kv?: KVNamespace,
484): Promise<ListModelsResult> {
485 const [pricing, reasoning] = await Promise.all([
486 byteplusModelPricing(kv),
487 byteplusModelReasoning(kv),
488 ])
489 const withPricing = (models: Array<ModelInfo>): Array<ModelInfo> =>
490 models.map((model) =>
491 overlayModelFacts(
492 model,
493 pricing(model.rawId),
494 reasoning(model.rawId, listsReasoning(model.capabilities)),
495 ),
496 )
497 const key = env.ARK_API_KEY
498 // No key: the embedded catalog is still a real answer, so serve it rather
499 // than reporting the provider skipped.
500 if (!key) return { models: withPricing(curatedModels()) }
501
502 const body = (await fetchJson(ARK_MODELS_URL, {
503 headers: { Authorization: `Bearer ${key}` },
504 })) as { data?: Array<ArkModel> }
505 const live = (body.data ?? []).map(toModelInfo)
506
507 // Curated entries the listing omits: Seed Speech (different host) and ids
508 // Ark serves but does not enumerate.
509 const liveIds = new Set(live.map((m) => m.rawId))
510 const gapFillers = curatedModels().filter((m) => !liveIds.has(m.rawId))
511 return { models: withPricing([...live, ...gapFillers]) }
512}
513
514export const byteplusProvider: ProviderConfig = {
515 id: 'byteplus',
516 displayName: 'BytePlus',
517 // Optional, not required: it upgrades the model catalog from embedded to
518 // live. fetchSpec never needs it, and listModels degrades to the curated
519 // catalog without it.
520 authEnvVar: 'ARK_API_KEY',
521 // Overridden per operation: the generated Ark document stamps
522 // 'generated', and the Seed Speech document stamps its own verified
523 // status. This default only applies if a marker is ever missing.
524 defaultDerivation: 'probe-verified',
525 specGrain: 'provider',
526 // Default document is Ark. Seed Speech (`?activity=audio`) uses a
527 // different host and X-Api-Key — a combined profile would send Bearer
528 // to the voice host.
529 connect: bearerConnect(BYTEPLUS_ARK_BASE_URL, 'Ark'),
530 connectByActivity: {
531 audio: headerApiKeyConnect(BYTEPLUS_VOICE_BASE_URL, 'X-Api-Key'),
532 },
533 fetchSpec,
534 listModels,
535 classify,
536 classifyGets: true,
537 generationEndpointId: ({ rawId, activity }) =>
538 byteplusGenerationEndpointId(rawId, activity),
539}