ModelArk from zero: account, key, model, endpoint

Chapter 1 of 9. From no account to an authenticated shell that is one command away from its first render. Every console step is named, and every billing trap is flagged before it rejects your payment.

The whole course runs on one HTTP API. By chapter 9 you will be rendering the beats of a short film in parallel for a few dollars a pass. Today you make one request that costs nothing and returns 200. Get this chapter exactly right. Both live incidents in my own setup logs happened in the very first console session, before a single render: one a key pasted into a chat window, the other a payment order rejected at pre-verification because of a single checkbox.

BytePlus ModelArk Seedance API setup: the map before the steps

ModelArk is BytePlus's model-hosting platform, and it is where the Seedance video models are served over an API. Four facts define the entire setup, and every one of them is a place people get stuck.

The console lives at console.byteplus.com/ark.

The region is ap-southeast-1 (Johor). The ModelArk overview states it plainly: "Currently, all the models listed in Model list are supported in the ap-southeast-1 region." A couple of models have reached eu-west-1, but the Seedance video family has not. If your console is pointed anywhere else, nothing in this course will be visible to you.

The base URL, exact, for every request in all nine chapters:

https://ark.ap-southeast.bytepluses.com/api/v3

That URL comes straight from the overview page. Note the host: ark.ap-southeast.bytepluses.com, with an s in bytepluses. Typo the host and you get DNS failures that look like an outage.

The auth scheme is a bearer token, one header on every call, per the official API key guide:

Authorization: Bearer $ARK_API_KEY

The done-state for this chapter, concretely:

• An account signed in at console.byteplus.com/ark, region ap-southeast-1.
• ARK_API_KEY exported in your shell and nowhere else.
• The free-quota Seedance models activated individually, the 2.0 series left untouched: chapter 4 is where you first need it, and the full cost model lives in chapter 9.
• A curl against the tasks endpoint returning HTTP 200 for zero spend.

Account and region: step by step

1. Create the BytePlus account

   Sign up at byteplus.com with an email you control and verify it. Then open console.byteplus.com/ark directly. That path drops you into the ModelArk console rather than the general BytePlus product landscape, and it is the URL worth bookmarking.

2. Pin the region to ap-southeast-1

   Check the region selector in the console chrome before touching anything else. It must read ap-southeast-1 (Johor). Per the overview, that region carries the full model list; the Model list page notes only a small subset reaches eu-west-1. Every base URL, activation and quota in this course assumes Johor.

3. Confirm you are in ModelArk, not a sibling product

   BytePlus ships several AI consoles and they look alike. The check is simple: you should see a model list with Seedance entries in it. If you cannot, you are in the wrong product; go back to console.byteplus.com/ark.

The API key: environment only

The official guide, Obtain and configure an API key, is explicit about both halves of the job: "To invoke models on the ModelArk platform, you must authenticate using an API Key. This guide provides step-by-step instructions on how to obtain an API Key from the console and configure it securely as an environment variable." Environment variable. Follow that instruction to the letter.

1. Create the key in the console

   Open the API key management page in the ModelArk console and create a key. The creation flow lets you set the key's name; name it after the machine it will live on, so a future revocation is surgical rather than a full rotation. Copy the key into the shell export in the next step, and let it live nowhere else.

2. Export it, and put it nowhere else

   export ARK_API_KEY='<paste from the console>'
   

   Not in code. Not in a committed .env. Not in git history. Not in a chat window. That last one is a lived rule: during the production arc this course is built on, a key was pasted into a chat window and the account password was shared the same way in the same session. Both had to be treated as burned, the key regenerated and the password rotated. The cleanup is contained only because the key never touched code or git: nothing to scrub from history, nothing to redeploy.

3. Guard every script with a one-liner

   : "${ARK_API_KEY:?ARK_API_KEY is not set. Run: export ARK_API_KEY='...'}"
   

   The :? parameter expansion kills the script with that exact message when the variable is missing or empty, before any request fires. The Python CLI you meet in chapter 3 does the same check and dies with the string ARK_API_KEY is not set. Run: export ARK_API_KEY='your-key'. A render pipeline that discovers a missing key at submit time has already wasted a tunnel, a prompt and your patience; discover it at line one.

Model activation: the free tier and the select-all trap

Models on ModelArk are off until you activate them per account. The Model list is the canonical catalogue; these are the Seedance entries that matter for this course, with their exact dated IDs:

The Seedance 1.0 model page describes what the free tier buys: "breakthroughs in semantic understanding and prompt following" and "1080p videos with smooth motion, rich details, and cinematic aesthetics". The 1.5 Pro page adds native audio generation coordinated with the visuals. That free quota is real money's worth: a 5s 720p clip on 1.0 Pro measured at roughly 110K tokens in my logs (the docs' 5s 1080p reference point is about 247K), so 2,000,000 free tokens is roughly 18 clips at 720p, about 40 at 480p, about 8 at 1080p. Off the free quota, 1.0 Pro bills 0.0025 USD per thousand tokens, which works out near $0.28 per 720p clip-equivalent.

1. Activate the free models individually

   Open the model activation page. The console will offer a bulk modal that authorises around 40 models in one order. Do not use it (see the warning below). Tick the individual free models you actually want: seedance-1-0-pro-250528 and seedance-1-0-pro-fast-251015 are the minimum for chapters 2 and 3.

2. Know that Seedance 1.5 Pro has its own activation path

   seedance-1-5-pro-251215 is absent from the bulk modal entirely; activating it is a separate path I had to go hunting for in the console, starting from its entry on the official Model list and its model-card page. It carries its own 2,000,000 free tokens and is the cheapest way to hear native audio before you ever pay for 2.0, so it is worth the hunt, but the course does not depend on it until the audio work later on.

3. Set the billing guardrails

   Enable Free Credits Only Mode account-wide; the console asks for a typed acknowledgement before it takes effect. Once on, every model auto-pauses the moment its free quota is exhausted, which means the worst possible bill while you learn is zero. Leave Auto-activate new models off, so a new model appearing in the catalogue can never opt itself into your account.

Seedance 2.0: zero free quota and a one-way billing door

The 2.0 series is the reason this course exists. The official launch announcement describes it as "built with a unified multimodal audio-video joint generation architecture" supporting "four input modalities: text, image, audio, and video". Motion transfer, registered character assets and scene plates (chapters 4 to 6) all live there. It also has zero free quota, and the console tells you so in a very specific way.

Attempt to activate dreamina-seedance-2-0-260128 on a fresh account and activation fails with this exact message:

"No available resource packs. Please purchase a resource pack first."

That is not an error state; it is the price list talking. The 2.0 series bills against purchased token packs, per the official Pricing page, which documents the billing formulas and unit prices per model. Buying the pack is not the whole story either. On my account, with the pack bought and Free Credits Only Mode still on, a 2.0 run failed with SetLimitExceeded: "Safe Experience Mode" had paused the model at its zero free quota, and it stayed paused until the mode came off. That was a billing block, not a code bug, and the failed task incurred no charge.

Here is the door you should walk through deliberately, once, with the confirm dialog read twice. Letting 2.0 draw on a purchased pack requires turning Free Credits Only Mode off, and the console's confirm dialog warns that it "cannot be turned on again". That is exact: the mode is irreversible. After you flip it, every model on the account bills pay-as-you-go past its free quota, and the auto-pause safety net is gone for good.

Rate limits: what one account can run

An individual account gets 180 requests per minute and 3 concurrent generation tasks for non-4K work, dropping to 15 requests per minute and 1 concurrent task at 4K. BytePlus documents the enforcement mechanics in Best practices for handling burst traffic: "The ModelArk API enforces rate limits on requests per time window, token usage, usage growth rate, and concurrent requests", and a request that trips a limit receives a 429.

The 3-concurrent ceiling matters more than it looks. Chapter 3 teaches the parallel pattern this course is built around, submitting every beat of a film simultaneously, and the reason that works on a 3-slot account is that excess submissions queue server-side (status: "queued") rather than fail. You will see that status with your own eyes in chapter 2.

Verify the environment: two commands, zero spend

No renders yet. Two commands prove the whole chapter.

First, the guard. Run it in a shell where you have deliberately not exported the key, and watch it die with the exact message; then run it in your real shell and watch it pass silently:

: "${ARK_API_KEY:?ARK_API_KEY is not set. Run: export ARK_API_KEY='...'}"

Second, an authenticated read against the tasks collection, the same resource the task-creation API posts to. Listing tasks generates nothing and costs nothing:

curl -sS -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ARK_API_KEY" \
  "https://ark.ap-southeast.bytepluses.com/api/v3/contents/generations/tasks?filter.status=succeeded"

200 means the endpoint resolved, the key authenticated and the account is live. On a fresh account the task list is empty, which is correct: you have not created anything yet. Any other status code, work backwards through this chapter in order: host typo first, then key export, then region.

What's next

Chapter 2 makes the API do work: POST a generation task to the endpoint you just authenticated against, poll it through queued and running to succeeded, and download the MP4, exactly as the official Create a video generation task and Retrieve a video generation task references describe, with the video generation tutorial as the official companion. Your first clip will cost exactly zero, because you activated the free-quota models and left the billing door shut.