@byte_fluffy/nexra-sdk 0.1.0-alpha.5 → 0.1.0-alpha.50

package/README.md

@@ -9,18 +9,14 @@ npm install @byte_fluffy/nexra-sdk@next
 ```
 
 ```ts
-import { createNexra, getModelSpec, projectMediaGeometry } from "@byte_fluffy/nexra-sdk";
+import { createNexra, getModelSpec, type NexraImageGenerateInput } from "@byte_fluffy/nexra-sdk";
 
 const nexra = createNexra({ apiKey: process.env.NEXRA_API_KEY });
 const spec = getModelSpec("openai/gpt-image-2");
-const geometry = projectMediaGeometry(spec!.operations[0]!.inputSchema);
-// geometry.resolution.options → ["1K","2K","4K"]; geometry.ratio.options → ["1:1", ...]
-
-const input = {
-  model: spec!.id,
-  prompt: "A paper boat on a blue table",
-  resolution: "1K",
-  ratio: "1:1",
+const input: NexraImageGenerateInput = {
+  content: [{ type: "text", text: "A paper boat on a blue table", role: "prompt" }],
+  resolution: "1k",
+  aspect_ratio: "1:1",
   quality: "medium",
 };
 const quote = await nexra.catalog.quote({
@@ -28,18 +24,531 @@ const quote = await nexra.catalog.quote({
   operation: "image.generate",
   input,
 });
-const result = await nexra.run(spec!.id, { input, quoteToken: quote.quoteToken });
+const result = await nexra.run(spec!.id, input, { quoteToken: quote.quoteToken });
 ```
 
-Apps should send the unified geometry (`resolution` + `ratio` + `quality`). Quote and `run`/`create` map those fields onto the model's native catalog parameters (GPT Image `size: 1024x1024`, Seedream `size: 2K`, Grok `resolution: 1k` + `aspect_ratio`, …). `encodeMediaGeometry` / `decodeMediaGeometry` expose the same mapping without making a request. Native `size` already in the body is left unchanged.
+Media apps send the versioned Nexra category contract: ordered `content` parts plus
+the common parameters for `image.generate`, `video.generate`, `audio.generate` or
+`image.upscale` or `video.upscale`. The server resolves the selected model component and explicitly
+adapts that input to the channel Provider. The SDK does not expose or emulate
+Provider-native endpoints. Protocol constants, schemas and types are also
+available from `@byte_fluffy/nexra-sdk/media`.
 
 The default API base URL is `https://api.nexra-ai.com/v1`. When overriding
 `baseUrl`, include the `/v1` API prefix.
 
+## Image and video upscale
+
+`0.1.0-alpha.42` adds `bytedance/image-enhancement` and
+`bytedance/video-super-resolution`. Both use the Task API and the existing
+asset delivery lifecycle. Read the stored result from `result.assets`; wait for
+delivery to finish before treating an output URL as permanent.
+
+```ts
+const image = await nexra.run("bytedance/image-enhancement", {
+  content: [{ type: "image", role: "source", source: "https://example.com/input.png" }],
+  resolution: "2k",
+});
+const video = await nexra.run("bytedance/video-super-resolution", {
+  content: [{ type: "video", role: "source", source: "https://example.com/input.mp4" }],
+  source_duration: 5, // Upper bound in seconds; checked before enhancement.
+  resolution: "1080p",
+});
+```
+
+Image upscale supports `144p`, `240p`, `360p`, `480p`, `540p`, `720p`,
+`1080p`, and `2k` (default). Video upscale supports `720p`, `1080p` (default),
+`2k`, and `4k`.
+
+The migrated task input also accepts the existing image fields
+`image_url`, `resolution_boundary`, `enable_hdr`, and `enable_wb`, or the video
+fields `video_url`/`vid`, `config`, and `target.res`. Use one input contract per
+request. Credentials, VOD space, and playback signing belong to the server channel.
+
+## Image layer decomposition
+
+Seedream Pro accepts one source image in `output_mode: "layers"`. Resolution is
+`1K`, `1.5K`, or `2K`; `prompt_optimization` selects `standard` or `fast`.
+Layers retain the source aspect ratio and use PNG for transparency.
+
+```ts
+import type { NexraImageLayerDecompositionOutput } from "@byte_fluffy/nexra-sdk";
+
+const result = await nexra.tasks.run<NexraImageLayerDecompositionOutput>(
+  "bytedance/doubao-seedream-5-0-pro-260628",
+  {
+    content: [{ type: "image", source: "https://example.com/poster.png", role: "source" }],
+    output_mode: "layers",
+    resolution: "2K",
+    prompt_optimization: "standard",
+    output_format: "png",
+  },
+  { idempotencyKey: "poster-layers-1" },
+);
+for (const layer of result.output.layer_decomposition.layers) {
+  const url = result.output.images[layer.image_index];
+  console.log(layer.z_index, layer.name, layer.bounding_box, url);
+}
+```
+
+`image_index` associates metadata with the image array; `z_index` defines stacking
+order, with zero for the background. Use `tasks.wait` when recovering an accepted
+task. A background-delivery task is usable only when `deliveryStatus` is `ready`;
+the stored image URLs can be reused without uploading them again. The provider's
+Native request format remains available on its existing endpoint.
+
+## Dolphin Seedance
+
+`0.1.0-alpha.41` adds the independently addressable models
+`dolphin/seedance-2-0` and `dolphin/seedance-2-5`. Each model has its own
+availability, channel routes and prices. Select its public ID when submitting a task.
+
+```ts
+const nexra = createNexra({
+  apiKey: process.env.NEXRA_API_KEY,
+  baseUrl: "https://test-api.nexra-ai.com/v1",
+});
+const task = await nexra.tasks.create("dolphin/seedance-2-0", {
+  content: [{ type: "text", role: "prompt", text: "A paper boat on calm water" }],
+  duration: 4,
+  resolution: "480p",
+  generate_audio: false,
+});
+const result = await nexra.tasks.wait(task.id);
+```
+
+Seedance 2.0 supports 4–15 seconds and Seedance 2.5 supports 4–30 seconds.
+The existing ByteDance model IDs retain their own supplies and prices.
+
+## MiniMax H3 Max
+
+`0.1.0-alpha.49` adds the official `minimax/MiniMax-H3-Max` model. It supports
+480P/768P output, 5–15 seconds, and image, video and audio references.
+
+```ts
+const model = "minimax/MiniMax-H3-Max";
+const state = await nexra.catalog.model(model, "video.generate");
+// The selected environment owns availability and current sale prices.
+console.log(state.available, state.prices);
+
+const task = await nexra.tasks.create(model, {
+  content: [{ type: "text", role: "prompt", text: "A paper boat drifts across a rain puddle." }],
+  duration: 5,
+  resolution: "480P",
+  aspect_ratio: "16:9",
+});
+const result = await nexra.tasks.wait(task.id);
+```
+
+Use the selected environment's published prices for estimates. The SDK's bundled
+catalog describes the model contract; channel costs and sale prices remain in
+the live catalog.
+
+## Banana 2.1
+
+Use `google/gemini-nano-banana-2.1` for Banana 2.1. The model supports
+`1K` (default), `2K`, and `4K`, fifteen aspect ratios, and up to fourteen
+source/reference images. It does not support `512`, `count`, or `seed`.
+
+```ts
+const modelId = "google/gemini-nano-banana-2.1";
+const input: NexraImageGenerateInput = {
+  content: [{ type: "text", text: "A paper boat on a blue table", role: "prompt" }],
+  resolution: "2K",
+  aspect_ratio: "16:9",
+};
+const quote = await nexra.catalog.quote({ modelId, operation: "image.generate", input });
+const result = await nexra.run(modelId, input, { quoteToken: quote.quoteToken });
+```
+
+The server also exposes the Google Native `generateContent` endpoint at
+`/v1/projects/{project}/locations/global/publishers/google/models/gemini-nano-banana-2.1:generateContent`.
+Use the Native `contents` and `generationConfig` payload for direct HTTP calls;
+SDK media calls use the Nexra contract shown above.
+
+## DeepSeek model identity correction
+
+`0.1.0-alpha.36` replaces `ctyun/deepseek-v4-1-flash` with
+`deepseek/deepseek-v4-1-flash`. Update model IDs in SDK calls, direct HTTP
+requests, persisted selections and catalog caches. Upgrading the SDK does not
+rewrite a hardcoded model ID. The previous public ID and `deepseek-v4.1-flash`
+alias are retired; neither resolves in the new catalog.
+
+The server rollout must apply migration `0056_deepseek_model_identity` before
+syncing the new model definition. The model UUID, channel-specific upstream IDs,
+routes, prices and original request history remain attached to the same model.
+The API paths and native payload shapes remain unchanged.
+
+## Error contract migration
+
+`0.1.0-alpha.30` introduces the flat public error response and matching SDK
+types and exception getters. Existing HTTP envelopes and historical Task
+objects remain supported as described below.
+
+New Nexra responses keep one platform request context at the root:
+`nexraRequestId` and `nexraHttpStatus`. Platform classification is
+`nexraError: { code, message, param? }`. Provider context uses the independent
+root fields `upstreamHttpStatus`, `upstreamRequestId` and `upstreamError`.
+Successful Task receipts and results can carry the platform context without
+an error. New Task results do not duplicate the old `requestId` or `error`
+wrapper. The SDK's exported `Task` and `TaskPage` types describe these public
+results, not the server's internal Task read model.
+
+`NexraApiError.status` remains the actual fetch response status. Its read-only
+`code` getter and inherited `message` expose the server's platform classification;
+`nexraError` retains that classification object. Both exception types expose
+`nexraHttpStatus`, `nexraRequestId`, `upstreamHttpStatus`, `upstreamRequestId` and
+`upstreamError`. `NexraTaskError` derives these fields and `taskId` from its
+retained `task`, and has no fetch `status`.
+
+Platform HTTP status and request ID describe the same originating request.
+A failed Task can retain its original creation HTTP 202 while a later GET
+returns HTTP 200; its provider might separately return HTTP 400. Missing origin
+evidence is omitted, not inferred from Task failure or a later query. The
+SDK preserves server messages and unknown code strings without localizing or
+reclassifying them. Set `Accept-Language: zh-CN` or `en` through existing client
+`headers` when needed.
+
+The SDK accepts old HTTP envelopes and Task error fields internally. Deprecated
+`requestId` and `details` exception getters return `nexraRequestId` and the
+parameter context, without adding serialized aliases. Use `nexraError.param`
+for new parameter handling. Public retry/category hints are removed; the SDK
+no longer exposes `NexraApiError.retryable`.
+
+`upstreamErrorMessage` is the original provider error text, preserving its
+language and line breaks. It is independent of the platform classification and
+is omitted when captured diagnostics contain no supported error text. Both SDK
+exception types expose this field. For older stored diagnostic bodies,
+`extractUpstreamErrorMessage(body)` uses the same extraction rules as the server.
+
+`upstreamError` contains captured provider error content. When an older captured
+body has its own `error` member, input normalization selects that member once;
+otherwise it retains the complete captured error body. An already canonical
+`upstreamError` is not unwrapped again. Provider fields named `requestId`,
+`httpStatus`, `retryable` or `category` remain unchanged. Diagnostic flags such
+as `upstreamRedacted`, `upstreamTruncated`, `upstreamUnavailableReason`,
+`upstreamFormat` and `upstreamEvent` remain available when supplied by the server.
+This diagnostic projection does not rewrite original Native HTTP responses or
+Task outputs.
+
+Against older servers, `tasks.get`, `list`, `watch`, `wait` and
+`NexraTaskError.task` retain original Task/Event objects and their historical
+fields. Only exception getters adapt the input shape; the SDK does not clean
+returned objects or manufacture context for old successful responses.
+
+HTTP retry behavior is unchanged: eligible HTTP 503 requests make at most three
+attempts by default, and `maxRetries: 0` makes one attempt. Retry decisions use
+the actual fetch status rather than platform or provider payload metadata.
+Retried Task creation keeps the same idempotency key and payload; failed Tasks
+throw `NexraTaskError` without submitting another generation.
+`NexraWaitTimeoutError` remains a local wait timeout with the original `taskId`
+and does not mean generation failed.
+
+## Model display names
+
+`getModelSpec`, `listModelSpecs`, `nexra.models.search`, `nexra.models.get`, and
+`nexra.catalog.model` use the existing VibePaper product labels for known model
+IDs, such as `Banana Pro`, `Grok Imagine`, `GPT-5.4`, and `MiniMax H3 Local`.
+Spelling and punctuation follow the Superegg/global VibePaper catalogs rather
+than upstream manufacturer labels. Model detail family versions follow the same
+mapping. Models without an existing product label retain generic word spacing
+and capitalization.
+
+Use `formatModelDisplayName(name, { modelId })` to apply the same mapping to other
+display labels. The one-argument form preserves known product labels and formats
+other labels generically; it does not guess model identity from an upstream name.
+It is available from the package root and `/catalog`. Formatting affects only
+`displayName`: use the static catalog's `id`, model discovery's `slug`, or the
+live catalog's `modelId` for requests, never the formatted display name.
+
+## Live model catalog
+
+`getModelSpec` and `listModelSpecs` read the catalog bundled with this SDK release.
+Use `catalog.model(publicId, operation)` to read the currently published database
+input schema, display name, sale prices and actual model revision. A successful
+`available: false` response authoritatively confirms an unavailable or retired
+public identity; HTTP failures throw and must preserve the last successful value.
+An unknown identity returns 404. Model IDs are URL-encoded by the SDK.
+
+`catalog.changes` lists lightweight public model/operation identities and their
+latest revisions. Start with `after: "0"` for initial alignment. Keep the first
+page's `revision` as `upper` for every remaining page and pass its opaque
+`nextCursor`. The cursor is bound to that `after`/`upper` window. Revisions are
+64-bit decimal strings; compare them with `BigInt`, not JavaScript numbers.
+
+```ts
+let after = "0";
+let cursor: string | undefined;
+let upper: string | undefined;
+do {
+  const page = await nexra.catalog.changes({ after, upper, cursor });
+  upper ??= page.revision;
+  // Record changed identities for independent background model reads.
+  enqueueChanges(page.data);
+  cursor = page.nextCursor;
+} while (cursor);
+after = upper!;
+
+for await (const event of nexra.catalog.events({ after, signal })) {
+  enqueueChanges(event.data);
+  after = event.revision;
+}
+```
+
+`enqueueChanges` is application code that records the affected identities before
+advancing the receiving cursor; it does not block on all model reads. Each model
+response carries its own actual revision. Do not label an older response with the
+requested target revision or let it overwrite newer state. An identity updated
+beyond a page window's fixed upper bound appears in the next window, including
+when its index row was replaced during pagination.
+
+`catalog.events` opens one authenticated SSE stream, ignores heartbeats, and
+emits complete `catalog.quote-context.changed` windows with `{ revision,
+changedAt, data }`. Notifications wake the API instance immediately; a per-instance
+60-second revision check recovers silent notification loss. When a stream ends or
+throws, the application reconnects using its retained `after` cursor; the SDK
+does not reconnect automatically. Abort the supplied signal to stop an active
+read. Leaving the iterator cancels and releases the response stream. Keep cached
+values and cursors separate for different API sources and authorization identities.
+No credentials, channel costs or user discounts are included in the public events.
+
+## Private ElevenLabs voices
+
+Voice design uses `elevenlabs/eleven_multilingual_ttv_v2`, with exactly one prompt
+and one script content part. Preview IDs remain in `task.output.previews`; the
+corresponding audio is returned in the ordered persisted `task.assets` list.
+
+```ts
+const design = await nexra.run("elevenlabs/eleven_multilingual_ttv_v2", {
+  content: [
+    { type: "text", role: "prompt", text: "A warm, clear and natural narrator voice." },
+    { type: "text", role: "script", text: previewScript },
+  ],
+}, { idempotencyKey: designKey });
+const creation = await nexra.voices.create({
+  name: "Narrator",
+  source: { kind: "design", taskId: design.task.id, previewId: selectedPreviewId },
+}, { idempotencyKey: saveKey });
+await nexra.tasks.wait(creation.taskId);
+const voice = await nexra.voices.get(creation.voice.id);
+```
+
+Cloning is a voice-resource operation, not a separate vendor model. Upload owned
+audio through `nexra.assets.upload`, then call `nexra.voices.create` with
+`source: { kind: "clone", samples: [sample.id] }`. The service accepts one to five
+stored audio samples totaling at most 25 MiB. Retain the sample IDs and the same
+idempotency key when retrying a creation.
+
+`nexra.voices.list` and `get` read current authenticated resource state. Only an
+active voice can be used for `elevenlabs/eleven_multilingual_v2` speech, using its
+public `voice_` ID. Creation and synthesis settle separately; creation does not
+imply verification or support for renewal, deletion, or voice conversion.
+
+Applications using a shared API key must enforce their own end-user ownership
+before reading or consuming a resource; API-key ownership covers the Nexra
+account, not an application's individual users. Published model choices are
+available through `nexra.models.resources(modelId, resource)`.
+
 Static catalog APIs are also available from `@byte_fluffy/nexra-sdk/catalog`.
 Exact non-negative decimal helpers are available from
 `@byte_fluffy/nexra-sdk/decimal`.
 
+The static catalog includes 14 Agnes and CTYun image/video model
+contracts. A catalog entry describes parameters; it does not grant access to a
+private model or publish a sale price. Check the selected environment's model
+listing and current prices before submitting a task.
+
+Agnes Video 2.5 Flash uses the same video Task input format as Seedance, with
+model-specific limits: `resolution: "720P"`, integer `duration` from 4 to 12,
+up to 5 reference images and 3 reference audio clips, and no video references.
+Keyframes use image content parts with `role: "first_frame"` or `"last_frame"`;
+they cannot be combined with reference media in the same request.
+
+```ts
+const flashInput = {
+  content: [{ type: "text", text: "A paper boat floats across a sunlit pond", role: "prompt" }],
+  duration: 4,
+  resolution: "720P",
+  aspect_ratio: "16:9",
+};
+const flashQuote = await nexra.catalog.quote({
+  modelId: "agnes/agnes-video-2-5-flash",
+  operation: "video.generate",
+  input: flashInput,
+});
+const flashResult = await nexra.run("agnes/agnes-video-2-5-flash", flashInput, {
+  quoteToken: flashQuote.quoteToken,
+});
+```
+
+## Native language models
+
+The optional `@byte_fluffy/nexra-sdk/language` entrypoint returns AI SDK
+`LanguageModelV4` models. Install its optional provider peers when using this
+entrypoint; the core SDK and media entrypoints do not load them. These provider
+versions require Node.js 22 or a supported Bun runtime:
+
+```sh
+npm install @ai-sdk/provider@^4.0.2 @ai-sdk/provider-utils@^5.0.21 \
+  @ai-sdk/openai@^4.0.11 @ai-sdk/anthropic@^4.0.30 @ai-sdk/google@^4.0.12 ai@^7
+```
+
+```ts
+import { generateText, streamText } from "ai";
+import { getLanguageModelBinding } from "@byte_fluffy/nexra-sdk/catalog";
+import { createNexraLanguageModel } from "@byte_fluffy/nexra-sdk/language";
+
+const modelId = "openai/gpt-6-sol";
+const binding = getLanguageModelBinding(modelId);
+const model = createNexraLanguageModel(modelId, {
+  apiKey: process.env.NEXRA_API_KEY!,
+});
+
+if (binding.supportsStreaming) {
+  const result = streamText({ model, prompt: "Explain a paper boat", maxRetries: 0 });
+  for await (const text of result.textStream) process.stdout.write(text);
+} else {
+  const result = await generateText({ model, prompt: "Explain a paper boat", maxRetries: 0 });
+  console.log(result.text);
+}
+```
+
+The binding selects a declared native endpoint, preferring Gemini, Responses,
+Chat Completions, then Messages. Pass `protocol` to choose another endpoint
+declared by that model. Native endpoint `inputSchema` and `outputSchema` describe
+wire parameters; language operation schemas may describe Playground inputs.
+`binding.maxOutputTokens` is the lower of the model capability and selected
+native endpoint limit. Messages requests validate the combined visible and
+thinking token budget before sending; explicit budgets are never clamped.
+The SDK does not wrap text requests in media Tasks or retry generations.
+
+Messages, tool history and ordered content parts use the AI SDK prompt contract.
+Chat Completions supports declared image/video/audio URLs and inline MP3, WAV,
+AAC and M4A audio without downloading URLs or changing codecs. Native model results and stream finish events retain `usage.raw`, including
+cache and modality details. With AI SDK 7, read `result.finalStep.usage.raw`
+or each step callback's usage. Aggregate `result.usage` and `totalUsage` do not
+retain raw records.
+
+Chat native extension fields are passed under `providerOptions.nexra`;
+Responses uses `openai`, Messages uses `anthropic`, and Gemini uses `google`.
+Explicit provider options are preserved. Model identity and prompt/stream
+fields stay owned by the SDK. Kimi K2.5 currently declares synchronous Chat
+Completions only, so use `generateText` for that model.
+
+Responses defaults to `store: false` in this SDK so each request replays the full
+conversation and encrypted reasoning instead of relying on stored item IDs.
+Pass `providerOptions.openai.store: true` explicitly for a stored conversation.
+The current Responses provider cannot preserve sampling parameters alongside
+reasoning for canonical Nexra IDs. Explicit `temperature` or `topP` therefore
+fails before sending instead of being silently discarded. A caller may select
+`forceReasoning: false` for sampling without explicit reasoning controls.
+The documented provider version floors are tested; Anthropic budget validation
+uses its exported capability helper and the shared provider budget mapper.
+
+Use `resolveNexraLanguageReasoning(modelId, { enabled: false })` from `/catalog`
+for a quiet generation policy. Its `providerOptions` select a declared off mode
+or the model's minimum reasoning effort; `canDisable` distinguishes those cases.
+An explicit AI SDK `reasoning: "none"` is rejected when the native model requires
+reasoning, rather than being changed silently. Explicit provider options take
+precedence over shared reasoning defaults.
+
+GPT-6 Sol and GPT-6 Luna are included in the language model catalog. Sale prices
+are not bundled into the SDK; use the current prices published by the selected
+Nexra environment:
+
+```ts
+const { prices } = await nexra.catalog.listPrices();
+const gpt6Prices = prices.filter(({ modelId }) =>
+  modelId === "openai/gpt-6-sol" || modelId === "openai/gpt-6-luna"
+);
+```
+
+## Ark web search (Responses)
+
+Available since SDK `0.1.0-alpha.47` (`npm install @byte_fluffy/nexra-sdk@next`).
+
+DeepSeek V4.1 Flash (`deepseek/deepseek-v4-1-flash`), GLM 5.3 Flash
+(`z-ai/glm-5-3-flash`), Doubao Seed 2.1 Lite
+(`bytedance/doubao-seed-2-1-lite-260915`), and Kimi K3.1 Pro
+(`moonshot-ai/kimi-k3-1-pro`) support the Ark online content plugin through
+`/v1/responses`. The default SDK binding selects this endpoint. All four retain
+explicit Chat Completions bindings; DeepSeek also retains Messages.
+Search is a provider-executed tool, rather than a Chat `web_search_options` flag.
+
+```ts
+import { generateText } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { createNexraLanguageModel } from "@byte_fluffy/nexra-sdk/language";
+
+const result = await generateText({
+  model: createNexraLanguageModel("deepseek/deepseek-v4-1-flash", {
+    apiKey: process.env.NEXRA_API_KEY!,
+    baseUrl: "https://vip-api.nexra-ai.com/v1",
+  }),
+  prompt: "Search for the official DeepSeek website and cite its URL.",
+  tools: { web_search: openai.tools.webSearch() },
+  providerOptions: {
+    openai: { maxToolCalls: 1 },
+    nexra: { web_search: { sources: ["search_engine"], max_keyword: 1, limit: 3 } },
+  },
+  maxOutputTokens: 512,
+  maxRetries: 0,
+});
+console.log(result.text, result.sources);
+```
+
+`providerOptions.nexra.web_search` preserves native tool fields such as `sources`,
+`max_keyword`, `limit`, and `user_location`; it requires the `web_search` tool.
+The same options work with `streamText`. Unpositioned native citations become
+URL sources; original Native bodies, raw stream events, and
+`finalStep.usage.raw.tool_usage_details.web_search` remain available.
+
+VIP configured search prices (CNY, checked 2026-11-01):
+
+| Content source | Channel cost / 1,000 uses | Nexra sale / 1,000 uses |
+| --- | ---: | ---: |
+| `search_engine` (default) | ¥4 | **¥4.4** |
+| `toutiao`, `douyin`, `moji` (each additional source) | ¥6 | ¥6.6 |
+
+A use is an actual upstream content-source search, **not an HTTP request or a
+returned result**. Multiple rounds, keywords, or content sources can incur
+multiple uses. Token charges are additional, including retrieved context.
+Declaring a tool does not itself incur a search fee if the model does not use
+it. Preauthorization reserves the configured search ceiling and settles the
+actual evidenced usage; set `maxToolCalls` and `max_keyword` to control that
+ceiling. Missing search evidence is not treated as free search.
+
+Current VIP token sale prices per million tokens:
+
+| Model | Input | Cached input | Output |
+| --- | ---: | ---: | ---: |
+| DeepSeek V4.1 Flash | ¥2.2 | ¥0.044 | ¥8.8 |
+| GLM 5.3 Flash | ¥0.88 | ¥0.253 | ¥3.08 |
+| Kimi K3.1 Pro | ¥14.3 | ¥1.43 | ¥74.8 |
+| Doubao Seed 2.1 Lite (non-audio input) | ¥0.88 | ¥0.176 | ¥2.97 |
+
+Seed audio input is ¥13.2/million tokens; cached audio input is ¥2.64/million.
+For Ark audio/video prompts in the AI SDK adapter, select
+`protocol: "openai-chat-completions"`; its native media parts retain their order. Kimi media requires bytes or Base64
+data URLs; the Chat binding derives URL support from the Native schema.
+The Responses search example above uses text. Native Responses media fields
+remain documented by each model's selected endpoint schema.
+
+GLM and Kimi K3.1 Pro thinking is always on. Use `reasoning: "low"` for minimum effort;
+`reasoning: "none"` fails locally. Native `none`/`minimal` effort aliases do not
+mean that these models can turn thinking off. Kimi does not use a `thinking`
+parameter. Its Responses endpoint permits `toolChoice: "auto"` (default) or
+`"none"`; forcing a particular tool or requiring a tool is rejected before
+fetch. With auto selection, search is billed only when actually used.
+
+These are the configured channel prices;
+the SDK does not dynamically apply upstream off-peak discounts. Provider account
+free quotas do not automatically make Nexra requests free. The selected plugin
+is separate from Doubao Search Custom; no Custom search service is used here.
+Always read the selected environment's live catalog prices before estimating
+charges. Official references: [online content plugin pricing](https://ark.volcengine.com/region:cn-beijing/docs/online-content-plugin-pricing)
+and [model pricing](https://console.volcengine.com/ark/region:cn-beijing/docs/model-pricing).
+
 ## Directory layout
 
 ```
@@ -48,7 +557,8 @@ src/
   catalog/
     index.ts                CatalogClient, getModelSpec, listModelSpecs
     generated/              Generated artifacts (committed; required to publish)
-      image.generated.json  One file per model kind (image, video, audio, ...)
+      image.generated.json  Image model specs
+      language.generated.json  Text/language model specs
       index.ts              Imports every kind JSON and exports the merged array
   generated/
     version.generated.ts    SDK_VERSION used by the transport
@@ -58,12 +568,11 @@ scripts/
                               src/catalog/generated/*
 ```
 
-### Adding a new public model
+### Adding a model spec
 
-1. Add its ID to `PUBLIC_MODEL_IDS` in `scripts/generate-public-catalog.ts`.
+1. Add its ID to `SDK_MODEL_IDS` in `scripts/generate-public-catalog.ts`.
 2. Run `bun run generate` (from `packages/sdk`).
 3. The script groups projected models by `model.kind`, writes one
    `src/catalog/generated/<kind>.generated.json` per kind (new kinds appear
    automatically), regenerates the merging `index.ts`, and bumps
    `src/generated/version.generated.ts`. No hand-written code changes.
-

package/dist/catalog.d.ts

@@ -1 +1,47 @@
-export { d as CatalogClient, h as CreateNexraQuoteRequest, j as MediaGeometryField, k as MediaGeometryProjection, w as NexraBillingCurrency, x as NexraModelOperation, y as NexraModelSpec, z as NexraModelSpecFilter, A as NexraQuote, D as NexraSalePrice, N as NexraSettlement, U as UnifiedMediaGeometry, S as applyMediaGeometry, W as decodeMediaGeometry, X as encodeMediaGeometry, Z as getModelSpec, $ as listModelSpecs, a0 as projectMediaGeometry } from './index-FyUOK0F-.js';
+import { a as JsonObject } from './json-Cz0MkWQn.js';
+import { H as HttpTransport, N as NexraCatalogChangeParams, a as NexraCatalogChangePage, b as NexraCatalogModelState, c as NexraSalePriceList, C as CreateNexraQuoteRequest, d as NexraQuote, e as CreateNexraDisplayQuoteBatchRequest, f as NexraDisplayQuoteBatch, g as NexraCatalogRevision, h as NexraModelSpec, i as NexraModelEndpointSpec, j as NexraModelSpecFilter } from './media-geometry-COln1N_2.js';
+export { M as MediaGeometryField, k as MediaGeometryProjection, l as NexraBillingCurrency, m as NexraCatalogModelIdentity, n as NexraModelOperation, o as NexraSalePrice, p as NexraSettlement, U as UnifiedMediaGeometry, q as applyMediaGeometry, r as decodeMediaGeometry, s as encodeMediaGeometry, t as projectMediaGeometry } from './media-geometry-COln1N_2.js';
+
+declare function formatModelDisplayName(displayName: string, identity?: {
+    modelId: string;
+}): string;
+
+declare class CatalogClient {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    changes(params?: NexraCatalogChangeParams, signal?: AbortSignal): Promise<NexraCatalogChangePage>;
+    model(modelId: string, operation: string, signal?: AbortSignal): Promise<NexraCatalogModelState>;
+    events(options?: {
+        after?: string;
+        signal?: AbortSignal;
+    }): AsyncGenerator<NexraCatalogChangePage>;
+    listPrices(signal?: AbortSignal): Promise<NexraSalePriceList>;
+    quote(request: CreateNexraQuoteRequest, signal?: AbortSignal): Promise<NexraQuote>;
+    quoteBatch(request: CreateNexraDisplayQuoteBatchRequest, signal?: AbortSignal): Promise<NexraDisplayQuoteBatch>;
+    revision(signal?: AbortSignal): Promise<NexraCatalogRevision>;
+}
+declare function getModelSpec(modelId: string): NexraModelSpec | undefined;
+declare function listModelSpecs(filter?: NexraModelSpecFilter): readonly NexraModelSpec[];
+type NexraLanguageProtocol = "gemini-generate-content" | "openai-responses" | "openai-chat-completions" | "anthropic-messages";
+type NexraLanguageModelBinding = Readonly<{
+    spec: NexraModelSpec;
+    endpoint: NexraModelEndpointSpec & {
+        protocol: NexraLanguageProtocol;
+    };
+    supportsStreaming: boolean;
+    maxOutputTokens?: number;
+}>;
+declare function getLanguageModelBinding(modelId: string, options?: {
+    protocol?: NexraLanguageProtocol;
+    stream?: boolean;
+}): NexraLanguageModelBinding;
+type NexraLanguageReasoning = Readonly<{
+    providerOptions: Record<string, JsonObject>;
+    canDisable: boolean;
+}>;
+declare function resolveNexraLanguageReasoning(modelId: string, options: {
+    enabled: boolean;
+    protocol?: NexraLanguageProtocol;
+}): NexraLanguageReasoning;
+
+export { CatalogClient, CreateNexraDisplayQuoteBatchRequest, CreateNexraQuoteRequest, NexraCatalogChangePage, NexraCatalogChangeParams, NexraCatalogModelState, NexraCatalogRevision, NexraDisplayQuoteBatch, type NexraLanguageModelBinding, type NexraLanguageProtocol, type NexraLanguageReasoning, NexraModelEndpointSpec, NexraModelSpec, NexraModelSpecFilter, NexraQuote, NexraSalePriceList, formatModelDisplayName, getLanguageModelBinding, getModelSpec, listModelSpecs, resolveNexraLanguageReasoning };

package/dist/catalog.js

@@ -3,16 +3,23 @@ import {
   applyMediaGeometry,
   decodeMediaGeometry,
   encodeMediaGeometry,
+  formatModelDisplayName,
+  getLanguageModelBinding,
   getModelSpec,
   listModelSpecs,
-  projectMediaGeometry
-} from "./chunk-2C2ZZKUC.js";
+  projectMediaGeometry,
+  resolveNexraLanguageReasoning
+} from "./chunk-WXPCZYOK.js";
+import "./chunk-BS3B6F7W.js";
 export {
   CatalogClient,
   applyMediaGeometry,
   decodeMediaGeometry,
   encodeMediaGeometry,
+  formatModelDisplayName,
+  getLanguageModelBinding,
   getModelSpec,
   listModelSpecs,
-  projectMediaGeometry
+  projectMediaGeometry,
+  resolveNexraLanguageReasoning
 };