Skip to main content

BytePlus ModelArk Provider Guide

BytePlus ModelArk is a Tier-2 catalog provider: OpenAI-wire-compatible with no behavioural quirks, so its entire integration is one JSON file (src/lib/providers/catalog/byteplus-modelark.json) rather than hand-written code. That file is the source of truth for the data on this page.

Verification status: this entry is docs-verified only, not yet live-verified. The vendor's GET /models needs a key (an unauthenticated GET answers HTTP 401), so the model ids come from the vendor's public Model list page and the roster has not been checked. No account was created and no API key was used to build this entry. evidence.liveMatrix is null until someone runs the live capability matrix with a real key (see Verification status below).

Key Facts​

  • Provider id: byteplus-modelark (aliases byteplus, modelark)
  • Protocol: OpenAI-compatible (/chat/completions) — the vendor's Compatible with OpenAI API page says "ModelArk model APIs are largely compatible with the OpenAI SDK."
  • Base URL: https://ark.ap-southeast.bytepluses.com/api/v3. The Region availability page lists a second base URL, https://ark.eu-west.bytepluses.com/api/v3; set BYTEPLUS_MODELARK_BASE_URL to use it. On that page, the section "Models supported in the EU region" has the sentence "The EU region currently supports the following models:" followed by a one-item list, seed-2-0-lite. Separately, a tip on the Model list page says "The seed-2-0 and seedream-5-0-lite models are also supported in the eu-west-1 region." The Region availability page also says "Platform-level resources, such as API keys and model activation status, are isolated by region."
  • Default model: seed-2-0-pro-260328
  • Models in catalog: 12, taken from the Text generation table of the Model list page. That table has 22 rows: 8 are marked Retired and are not in the catalog, and 2 of the other 14 (deepseek-v4-pro-260425 and deepseek-v4-flash-260425) are left out to stay within the 12-model cap
  • Streaming: supported — the Chat API page documents a stream parameter that returns content "according to the SSE protocol" and ends with a data: [DONE] message
  • Tool calling: model-dependent — the Function call page documents tools and points to the Model list's Tool use table for the models that support it
  • Tools while streaming: supported — the Function call page has a Streaming output section whose example passes tools with stream=True
  • Structured output: structuredOutput is true for the entry, in beta — the Structured output (beta) page documents response_format with json_schema mode, and says "This capability is still in the beta phase. Proceed with caution when using it in the production environment." The Chat API page says of response_format "For models that support this parameter, see documentation." The Model list's Structured output (beta) section lists these non-retired model ids: dola-seed-2-1-turbo-260628, seed-2-0-lite-260428, seed-2-0-mini-260428, seed-2-0-lite-260228, seed-2-0-mini-260215, deepseek-v4-1-flash-260910, deepseek-v4-pro-ga-260813, deepseek-v4-flash-ga-260731. The NeuroLink default seed-2-0-pro-260328 is not in that section.
  • Structured output + tools together: not declared (false) — no combined probe was run without credentials
  • Embeddings: not declared — the Model list has a separate "Multimodal embedding" section with its own API, and this entry lists chat models
  • Thinking: not declared — the Deep reasoning page documents a thinking request field, and this entry sets no thinking-level request parameter
  • Billing: free-tier — the vendor's Inference free trial page states a free inference trial quota for new users, see Billing below
  • Key format: none declared

Quick Start​

1. Get an API key​

  1. Visit: https://console.byteplus.com/auth/signup and register as a BytePlus user — the Inference free trial page (https://docs.byteplus.com/en/docs/ModelArk/free-inference-quota) says "Register and authenticate as a BytePlus user."
  2. Activate the models you want to call on the Model activation page (https://ai.byteplus.com/ark/region:ap-southeast-1/openManagement) — the Quick start (https://docs.byteplus.com/en/docs/ModelArk/quick-start) says "Go to the Model activation page to activate the models you need to use."
  3. Create an API key at https://ai.byteplus.com/ark/region:ap-southeast-1/apiKey — the Quick start says to "create or obtain a ModelArk API key"; the API key page (https://docs.byteplus.com/en/docs/ModelArk/api-key) says "API Key is isolated by region. Select the appropriate region before creating and using the API Key for authentication."
  4. Free trial, as the vendor states it: "ModelArk offers new users a free inference trial quota, allowing them to get started at no cost." (https://docs.byteplus.com/en/docs/ModelArk/free-inference-quota); the Free Tokens Only mode page (https://docs.byteplus.com/en/docs/ModelArk/free-tokens-only-mode) says "In this mode, calls to the inference API consume only the 500k free tokens granted by the platform."
  5. Set BYTEPLUS_MODELARK_API_KEY in your .env file (the vendor's examples read ARK_API_KEY, which NeuroLink does not)

2. Configure​

export BYTEPLUS_MODELARK_API_KEY=your-api-key
export BYTEPLUS_MODELARK_MODEL=seed-2-0-pro-260328   # optional — overrides the default model
export BYTEPLUS_MODELARK_BASE_URL=https://ark.ap-southeast.bytepluses.com/api/v3   # optional

3. Use it​

import { NeuroLink } from "@juspay/neurolink";

const neurolink = new NeuroLink();

const result = await neurolink.generate({
  input: { text: "Explain context windows in one paragraph." },
  provider: "byteplus-modelark",
  model: "seed-2-0-pro-260328",
});

console.log(result.content);
# CLI
npx @juspay/neurolink generate "Hello" --provider byteplus-modelark

Per-request credentials are passed like this:

await neurolink.generate({
  input: { text: "Hello" },
  provider: "byteplus-modelark",
  credentials: {
    byteplusModelark: { apiKey: process.env.BYTEPLUS_MODELARK_API_KEY },
  },
});

The Chat API page describes the model parameter as the "ID of the called model" and says "For scenarios with multiple applications and fine-grained management, we recommend calling by inference endpoint ID."

Billing​

The vendor's pages state:

  • Free trial: "ModelArk offers new users a free inference trial quota, allowing them to get started at no cost." (Inference free trial)
  • Free Tokens Only mode: "In this mode, calls to the inference API consume only the 500k free tokens granted by the platform." (Free Tokens Only mode)
  • With Free Tokens Only mode disabled: "When disabled: Online inference calls first consume the free quota. After the free quota is used up, usage is billed based on actual token consumption." (same page)
  • Pricing: the Pricing page says "Pay-as-you-go by token."

The entry records free-tier, the schema value closest to the stated free inference trial quota.

Models​

ModelContextVision$/M in · out (cache hit)Notes
seed-2-0-pro-260328 ⭐256Kyes$0.50 / $3.00 ($0.10)NeuroLink default. The Model list card that links to its detail page is captioned "Flagship general-purpose agentic model". Tools are listed as "Tool Calling". It is not in the Model list's Structured output (beta) section.
dola-seed-2-1-turbo-260628256Kyes$0.5 / $2.5 ($0.1)Fallback. Capabilities include Structured output.
seed-2-0-lite-260428256Kyes$0.25 / $2.00 ($0.05)Fallback. Structured output is listed as "Structured output (Recommended: json_schema mode)".
seed-2-0-mini-260428256Kyes$0.10 / $0.40 ($0.02)Fallback. Structured output is listed with "(Recommended: json_schema mode)".
seed-2-0-lite-260228256Kyes$0.25 / $2.00 ($0.05)Fallback and models.fallbackModelName. The id in the vendor's OpenAI-compatibility quickstart, its function-calling streaming example and its chat/completions curl.
seed-2-0-mini-260215256Kyes$0.10 / $0.40 ($0.02)Catalog entry.
seed-2-0-code-preview-260328256Kyes$0.50 / $3.00 ($0.10)Catalog entry; status preview follows the word in the id.
glm-5-3-flash-2608281024Kyes$0.15 / $0.5 ($0.03)Catalog entry.
glm-5-2-2606171024Kno$1.4 / $4.4 ($0.26)Catalog entry; no is a schema placeholder, not a vendor statement.
deepseek-v4-1-flash-2609101024Kyes$0.30 / $1.20 ($0.006)Catalog entry. Structured output is listed as "Structured output (json_object mode only)". Price shown is the "Peak hours" tier.
deepseek-v4-pro-ga-2608131024Kno$1.32 / $3.96 ($0.044)Fallback; no is a schema placeholder, not a vendor statement.
deepseek-v4-flash-ga-2607311024Kno$0.44 / $1.32 ($0.014)Fallback; no is a schema placeholder, not a vendor statement.

Model ids, capabilities and context lengths come from the Text generation table on the Model list page (retrieved 2026-09-29); prices come from the "Online inference (standard)" table on the Pricing page (retrieved 2026-09-29), in USD per million non-audio tokens.

  • Tiered prices. The Pricing page lists two "Prompt length" tiers for the Seed 2.0 rows, [0, 128] and (128, 256] (K tokens). The catalog stores the [0, 128] tier. For seed-2-0-pro-260328 the (128, 256] tier is $1.00 in, $6.00 out and $0.20 cache-hit; the other Seed 2.0 rows' second tiers are in each model's description in the JSON. The dola-seed-2-1-turbo-260628 row has one tier, [0, 256], which is stored; the Pricing page's Model ID cell for that row reads dola-seed-2-1-turbo.
  • Context. The Model list writes lengths as 256K and 1024K; the catalog stores 256000 and 1024000 (K read as 1,000). models.defaultContextWindow (128,000) and models.defaultMaxOutputTokens (4,096) are placeholders for model ids outside the catalog; 4,096 is the max_tokens default on the Chat API page. No per-model maxOutputTokens is set.
  • Vision. yes means the Model list's Visual understanding table lists the model. no, for glm-5-2-260617, deepseek-v4-pro-ga-260813 and deepseek-v4-flash-ga-260731, is a schema placeholder for a boolean the catalog requires; it is not a vendor statement.
  • Status. The status field holds production (preview for the model id containing "preview"); that is a schema placeholder, not a vendor statement.

Fallback order when the default is unavailable: seed-2-0-lite-260228 → seed-2-0-lite-260428 → seed-2-0-mini-260428 → dola-seed-2-1-turbo-260628 → deepseek-v4-pro-ga-260813 → deepseek-v4-flash-ga-260731. The runtime fallback model name is set explicitly to seed-2-0-lite-260228.

Verification status​

Tier-2 onboarding requires evidence before a provider is accepted, and pnpm run verify:provider-onboarding gates it in CI. This is what the catalog currently records for BytePlus ModelArk — docs-verified only, not live-verified:

ProbeResult
Rosterunauthenticated GET https://ark.ap-southeast.bytepluses.com/api/v3/models answered HTTP 401 on 2026-09-29; model ids are taken from the Model list page and the roster has not been checked
Auth-failure shapeunauthenticated GET of /models and of /chat/completions each answered HTTP 401 on 2026-09-29 with a JSON body whose error.code is AuthenticationError and error.type is Unauthorized; no POST was sent
Billingpublic pages state a free inference trial quota for new users and pay-as-you-go pricing by token, 2026-09-29 — see Billing; no signup was performed
Tools / structured outputdocumented on the Function call and Structured output (beta) pages; neither was exercised live, and no combined tools+schema request was sent — structuredOutputWithTools stays false
Live capability sweepnot run. evidence.liveMatrix is null. Before treating this provider as production-ready, run npx tsx test/continuous-test-suite-provider-matrix.ts --provider=byteplus-modelark with a real key and record the result.

Do not treat this entry as equivalent to a live-verified Tier-2 provider (e.g. FriendliAI, Novita AI) until that live matrix has been run and evidence.liveMatrix is filled in.

Troubleshooting​

The first six rows quote the vendor's Error codes page (rows 1 to 4 and 6) or Free Tokens Only mode page (row 5); the last row describes NeuroLink's own behaviour.

SymptomCauseFix
HTTP 401 AuthenticationError"The API key or AK/SK in the request is missing or invalid.""Please check the authentication credentials or troubleshoot based on the API document."
HTTP 404 ModelNotOpen"Your account %s has not activated the model %s.""Please activate the model service in the Ark Console."
HTTP 404 InvalidEndpointOrModel.NotFound"The model or inference endpoint %s does not exist or you do not have access to it."—
HTTP 429 QuotaExceeded"The account (%s) has exhausted the free trial quota of the model (%s).""To continue using the service, go to the ModelArk console and activate the corresponding model service on the Activation page."
HTTP 429 SetLimitExceeded"Your account [%s] has reached the set inference limit for the [%s] model, and the model service has been paused.""To continue using this model, please visit the Model Activation page to adjust or close the "Free Tokens Only Mode"."
HTTP 403 AccountOverdueError"The request failed because your account has an overdue balance.""To continue using the service, please go to the BytePlus Billing Center to recharge."
Structured output ignored with tools attachedstructuredOutputWithTools is false on this entryNeuroLink omits response_format automatically when tools are present, before sending

See also​