Get a BytePlus ModelArk key

Who this is for: anyone with a BytePlus ModelArk account who wants Doubao and other ModelArk models through SpiderGate.

What this does: explains how BytePlus bills by host, then walks you through creating a ModelArk API key and adding it to your SpiderGate vault.

Before you begin

A BytePlus ModelArk account (international). China-region accounts use Volcengine Ark.
About 2 minutes.

Limits and terms to know first

BytePlus uses an ordinary ModelArk API key for its Coding Plan. The host decides what you pay: the plan host is https://ark.ap-southeast.bytepluses.com/api/coding/v3, and BytePlus warns: "Do not use the Base model URL (https://ark.ap-southeast.bytepluses.com/api/v3). Requests sent to this Base URL do not consume your Coding Plan quota and will instead incur additional charges."

Warning: SpiderGate's default BytePlus host is that pay-as-you-go /api/v3 host, even when Billing is Subscription. If you hold a Coding Plan and leave Base URL (optional) empty, your requests are billed pay-as-you-go.

BytePlus's plan pages disagree on the limits. The newer overview gives Lite about 1,900 requests per five hours and 12,000 per week, and Pro about 9,500 and 60,000.

Warning: BytePlus says the Coding Plan is "Not available for API calls", and that using its Base URL and API key outside AI coding tools "may be identified as abuse or a policy violation, which could result in subscription deactivation or account suspension". Do not run n8n flows, scripts or your own apps on it. For those, use ModelArk pay-as-you-go.

Steps

Step 1 — Create the key

Open the ModelArk console's API key page at ai.byteplus.com/ark/region:ap-southeast-1/apiKey, create a key and copy it.

Step 2 — Add it in SpiderGate

Open Gate → Vault (/dashboard/gate/vault) and click Add Provider. BytePlus ModelArk appears under Connect a subscription and under Pay-as-you-go. Paste the key into API Key and add a Label. Then:

Pay-as-you-go: Billing Paid, Base URL empty.
Coding Plan: Billing Subscription, pick your package, and put https://ark.ap-southeast.bytepluses.com/api/coding/v3 in Base URL (optional).
China (Volcengine Ark): put https://ark.cn-beijing.volces.com/api/coding/v3 (plan) or your region's Ark host in Base URL (optional).

Under Routing, turn Share with SpiderIQ key pool off. Click Add key.

Verify it worked

When you click Add key, SpiderGate sends one request to BytePlus with the key before it stores anything: it lists models on the host the key will use.

If BytePlus accepts the key, the dialog closes and the key appears in your vault list.

If it does not, the dialog stays open and shows:

The byteplus key did not pass its check: <reason>. Nothing was saved.

The reason is SpiderGate's own wording, never BytePlus's error text. The usual ones are Invalid API key (401 Unauthorized), Access denied (403 Forbidden) and The account behind this key has no credit left (402).

To see the key serve a request, give it a slot in one of your own routing aliases and send a request to that alias. The trace shows which provider answered.

Troubleshoot

Your Coding Plan quota does not move, but you are being charged. The key is using the /api/v3 host. Edit the key and set the Coding Plan Base URL from Step 2.

Too many keys checked for this workspace; try again in …s. SpiderGate runs at most 20 key checks per brand in any 10 minutes. Wait the number of seconds it gives, then click Add key again.

Request timed out (15s) or Could not reach … to check the key. Try again later. The provider did not answer in time. Nothing was saved. Try again in a minute.

The provider is rate-limiting us (429). Try again in a minute. The provider throttled the check itself. Wait a minute and retry.