Volcengine Ark (Doubao)

Volcengine Ark is ByteDance's platform for serving Doubao and other models. AISIX lets applications call those models through the gateway's OpenAI-compatible API while managing the Ark credential, caller access, rate limits, and usage accounting.

One Ark provider key can serve both OpenAI-compatible Doubao chat traffic and Seedance video tasks. This guide verifies a chat model first, then reuses the provider key for video generation.

Prerequisites

Before starting, prepare the following:

• One AISIX setup:
  • For AISIX Cloud, an environment with an attached gateway and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
  • For the open-source AISIX gateway, prepare either a local AISIX installation or the Docker setup from the Open-Source AISIX Gateway Quickstart. Configure the gateway to load a declarative resources file.
• An Ark API key from the Volcengine Ark console.
• curl and jq.

Configure with AISIX Cloud

Export the AISIX Cloud connection details:

# Replace with your values
export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Create a provider key, model alias, and caller API key for the Doubao-backed chat-completions route.

Create a Provider Key

Create the provider key that stores the Ark credential and API root:

# Replace with your value
export ARK_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "volcengine-prod",
    "provider": "volcengine",
    "api_key": "'"${ARK_API_KEY}"'",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider is volcengine, the provider ID the gateway's video route dispatches on. Volcengine Ark is not listed on models.dev, but this is not a community catalog entry: the gateway implements the Ark video wire natively, and the AISIX Cloud Admin API accepts the ID directly and derives the openai adapter for chat traffic. The adapter field is only accepted on BYO provider keys.

❷ api_key stores the Ark API key and is sent as a bearer token on upstream calls. It follows the credential-handling behavior in Provider Keys.

❸ api_base is Ark's OpenAI-compatible base, whose version segment is /api/v3. AISIX appends the endpoint path to api_base verbatim, so this value produces https://ark.cn-beijing.volces.com/api/v3/chat/completions. The field is optional for this provider — when it is omitted, the AISIX Cloud Admin API fills in the same canonical value — but the examples set it explicitly so the upstream root each key targets stays visible in the configuration.

The command captures the returned provider key ID in PROVIDER_KEY_ID.

The examples use the CN Beijing host https://ark.cn-beijing.volces.com/api/v3. ByteDance operates the platform's international counterpart, BytePlus ModelArk, whose default base is https://ark.ap-southeast.bytepluses.com/api/v3. API keys and model provisioning are per platform and per region, so set api_base to the host your account is provisioned on. Any Ark base ending in /api/v3 works unchanged on the video routes, because the gateway derives the vendor root from that suffix.

Create a Model

Ark model IDs combine a family name, version digits, and a release-date suffix, all separated by dashes: doubao-seed-2-0-pro-260215 is the February 2026 release of the flagship Doubao Seed 2.0 Pro model, and lite and mini variants mark lighter, cheaper lanes of the same generation. Ark also provisions custom inference endpoints whose IDs start with ep-. model_name accepts either form, because the gateway forwards the value verbatim as the upstream model. Check the Ark model list for the current catalog before creating a model alias.

Create the model alias callers will send in requests:

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "doubao-flagship-prod",
    "model_name": "doubao-seed-2-0-pro-260215",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name is the alias callers send in model.

❷ model_name is the Ark model ID, or the ID of an inference endpoint you provisioned in the Ark console, which starts with ep-.

❸ provider_key_id attaches the alias to the Ark provider key.

Create a Caller API Key

Create the caller API key that can access the model alias. The plaintext key is server-generated and returned once in the response, so capture it now:

CALLER_KEY_RESPONSE=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "volcengine-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }')

export AISIX_API_KEY=$(printf '%s' "$CALLER_KEY_RESPONSE" | jq -r '.plaintext')
CALLER_API_KEY_ID=$(printf '%s' "$CALLER_KEY_RESPONSE" | jq -r '.api_key.id')

The allowed_models value must reference the model ID captured in the previous step, so the key can only access the alias you created. The commands also retain the caller key's resource ID so you can add the video model later. After the write, the configuration projects to attached gateways automatically.

Configure with the Open-Source AISIX Gateway

Export the upstream credential and choose the caller API key that applications will send to the gateway:

export ARK_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

Create a complete declarative resources file for this provider:

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: "volcengine-prod"
    provider: "volcengine"
    adapter: "openai"
    api_key: ${ARK_API_KEY}
    api_base: "https://ark.cn-beijing.volces.com/api/v3"

models:
  - display_name: "doubao-flagship-prod"
    provider: "volcengine"
    model_name: "doubao-seed-2-0-pro-260215"
    provider_key: "volcengine-prod"

api_keys:
  - display_name: "volcengine-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "doubao-flagship-prod"

If AISIX is installed locally, validate the file before loading it:

aisix validate --resources resources.yaml

After validation, start the gateway with the referenced environment variables in its process environment. Reload an existing gateway only if those variables are already available to the process; otherwise, restart it with the updated environment.

If you use Docker, adapt the validation and startup commands in the Open-Source AISIX Gateway Quickstart. Mount this resources.yaml file and pass every environment variable it references with -e in both commands. After the resources load, prepare the shared verification request below:

export AISIX_PROXY="http://127.0.0.1:3000"
export AISIX_API_KEY="$CALLER_API_KEY"

Verify the Provider Connection

Send a chat-completions request through the AISIX proxy:

curl -sS -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-flagship-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Doubao."
      }
    ]
  }'

The gateway returns an OpenAI-compatible response that echoes the caller-facing alias doubao-flagship-prod. If the request fails, check the provider key api_key, api_base, and the Ark model ID in model_name. Ark serves models per platform and per region, so a model-not-found error from the upstream can also mean the model is not available to your account on the host api_base points at.

Supply Cost Metadata

models.dev does not price Volcengine Ark models, so the AISIX Cloud pricing catalog carries no per-token rates for the volcengine provider, and the dashboard suggests no model IDs when you create an alias for it. Cost metadata for budgets and usage reports is operator-supplied on the model alias — the same posture as BYO endpoints. Until you set rates, usage from these aliases carries no cost signal, so spend-based controls do not see this traffic.

Set the rates through Model Pricing in an AISIX Cloud deployment, or with the cost field on the model in the open-source AISIX gateway's resources.yaml — see Cost Metadata. Video submissions are additionally recorded with zero tokens, and duration-based cost accounting for video tasks is not yet applied to AISIX Cloud budgets.

Generate Videos with Seedance

The same provider key drives the gateway's modeled video routes. Create a second alias that points at an Ark video model, for example Doubao-Seedance-1.0-pro; newer Seedance generations appear on the same model list:

In AISIX Cloud, create the video alias:

VIDEO_MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "doubao-video-prod",
    "model_name": "doubao-seedance-1-0-pro-250528",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$VIDEO_MODEL_ID"

Add the new model ID to the caller key's allowed_models. This field is a replacement list, so include the existing chat model ID:

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/api_keys/$CALLER_API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_models": ["'"${MODEL_ID}"'", "'"${VIDEO_MODEL_ID}"'"]
  }'

For the open-source AISIX gateway, add the video model to the existing models collection and allow the existing caller key to use both aliases:

resources.yaml

models:
  - display_name: "doubao-flagship-prod"
    provider: "volcengine"
    model_name: "doubao-seed-2-0-pro-260215"
    provider_key: "volcengine-prod"
  - display_name: "doubao-video-prod"
    provider: "volcengine"
    model_name: "doubao-seedance-1-0-pro-250528"
    provider_key: "volcengine-prod"

api_keys:
  - display_name: "volcengine-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "doubao-flagship-prod"
      - "doubao-video-prod"

Validate and reload or restart the declarative resources file as described above.

Submit a video task:

curl -sS -X POST "http://127.0.0.1:3000/v1/videos" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-video-prod",
    "prompt": "A paper boat drifts down a rain-soaked street at dusk.",
    "seconds": 5
  }'

Four provider-specific behaviors are worth knowing before you script around this route:

• The chat api_base is reused as-is. AISIX recognizes the /api/v3 suffix, derives the vendor root from it, and composes Ark's native task paths underneath: tasks are submitted to POST {root}/api/v3/contents/generations/tasks and polled at GET {root}/api/v3/contents/generations/tasks/{id}. A provider key already configured for Doubao chat traffic works on the video routes without change.
• seconds maps to duration; size is not forwarded. seconds is forwarded as the provider's integer duration. Ark expresses output dimensions as resolution and ratio quality tiers rather than pixel WIDTHxHEIGHT values, so a supplied size is validated for shape — a malformed value fails with 400 before the provider is contacted — but omitted from the upstream request, and the provider's default output setting applies.
• The full four-status lifecycle is reported. AISIX maps Ark's task states onto the unified enum: queued reports as queued, running as in_progress, and succeeded as completed, while failed, cancelled, and expired all report as failed with the provider's error code and message when available. Once the task completes, the poll response also reports the actual video duration in seconds.
• Finished videos are delivered by redirect. GET /v1/videos/{id}/content returns 302 with a Location header pointing at the provider's signed download URL. The bytes travel from Ark storage to the client and do not pass through the gateway, so use curl -L when downloading.

For the full submit, poll, and download workflow, including status semantics and rate-limit behavior on polling, see Video Generation.

Endpoint Coverage

A Volcengine Ark provider key resolves the openai adapter, so route support follows that adapter plus each route's own provider rules:

Route	Behavior with a volcengine model alias
/v1/chat/completions	Supported, buffered and streaming.
/v1/embeddings	Supported when the alias names an Ark embedding model, such as doubao-embedding-text-240515. AISIX appends /embeddings to api_base, reaching the provider's text-vectorization endpoint.
/v1/responses	Supported through the Responses bridge for request features the OpenAI adapter can express.
/v1/videos and its status and content routes	Supported. See Generate Videos with Seedance.
/v1/images/generations	Not supported. This route accepts only models whose configured provider is openai.
/v1/rerank	Not supported. This route accepts only the openai, cohere, and jina provider values.
/passthrough/volcengine/*rest	Supported for provider-native APIs that AISIX has not modeled, with limited gateway normalization.

See Provider Compatibility for the full endpoint and provider matrix.

Next Steps

You have now connected AISIX to Volcengine Ark and verified the model alias. Continue with these guides:

• Model Aliases: configure routing, retry behavior, or cost metadata for this alias.
• Model Pricing: set the operator-supplied per-token rates that budgets and usage reports need for this provider.
• Video Generation: follow the full submit, poll, and download workflow for Seedance tasks.
• Provider Compatibility: review supported proxy endpoints and provider-specific boundaries.