How to Use the Seedance 2.5 API: A Beginner's Guide for Creators
Contents
You can run the Seedance 2.5 API from your computer without building an app or setting up a server.
This guide uses SeeGen AI, VS Code, and Node.js to create a five-second video. We will create an API key, send a text-to-video request, check the task status, and get the final video URL.
Every SeeGen AI plan includes both web and API access. New users can receive 200 credits after signing up and joining the SeeGen AI Discord community.
What to prepare before you start
You will need:
- A SeeGen AI account
- A SeeGen AI API key
- Node.js
- VS Code or another code editor
- Enough credits for one generation
To check whether Node.js is installed, open a terminal and run:
node -v
If you see a version number, Node.js is ready. If the terminal says the command cannot be found, install Node.js before moving on.
This tutorial generates a five-second, 480p video without video input. It currently costs 150 credits, so the 200 free credits are enough. The same video at 720p costs 300 credits.
Check the SeeGen AI API documentation for the full guide before generating.
Set up and run the Seedance 2.5 API
Step 1: Create an API key
Sign in to SeeGen AI and open the API key section in your account settings.
Create a key and give it a name you will recognize, such as "Seedance Test." Copy it when it appears. The full API key is shown only once.
Your API key gives access to your account credits, so treat it like a password. Do not place it directly in your code. Do not upload it to GitHub or show it in a public tutorial.
If you plan to record your screen, create a temporary key and delete it when the recording is finished.
Step 2: Create the project
Create a folder named:
seegen-seedance-api
Open it in VS Code. Then open the terminal and run:
npm init -y
Add three more files so the folder looks like this:
seegen-seedance-api/
├── .env
├── .gitignore
├── generate.mjs
└── package.json
Open .env and add:
SEEGEN_API_KEY=your_api_key_here
Replace the placeholder with your real key.
Replace your_api_key_here with your real SeeGen AI API key.
Next, add these lines to .gitignore:
.env
node_modules/
This prevents Git from including your .env file and installed packages in a commit.
Step 3: Add the generation request
Paste the following code into generate.mjs:
const API_KEY = process.env.SEEGEN_API_KEY;
const BASE_URL = "https://seegen.ai/api/v1";
if (!API_KEY) {
throw new Error("SEEGEN_API_KEY was not found in the .env file.");
}
const headers = {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
};
const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function fetchJson(url, options = {}, attempts = 3) {
for (let attempt = 1; attempt <= attempts; attempt++) {
try {
const response = await fetch(url, options);
const text = await response.text();
let data;
try {
data = JSON.parse(text);
} catch {
data = { message: text };
}
if (!response.ok) {
throw new Error(
`HTTP ${response.status}: ${data.message || "Request failed"}`
);
}
return data;
} catch (error) {
const isNetworkError = error.message.includes("fetch failed");
if (!isNetworkError || attempt === attempts) {
throw error;
}
console.log("Network request failed. Retrying...");
await delay(attempt * 2000);
}
}
}
async function createTask() {
console.log("Starting Seedance 2.5 request...");
const data = await fetchJson(`${BASE_URL}/jobs/createTask`, {
method: "POST",
headers,
body: JSON.stringify({
model: "sd2.5",
inputs: {
prompt:
"First-person POV flying beside a realistic pterosaur above a tropical coastline, powerful wing movement, clouds rushing past, cinematic daylight",
duration: "5s",
resolution: "1280x720",
outputResolution: "480p",
bitrateMode: "standard",
generateAudio: true,
seed: -1,
},
}),
});
if (!data.taskId) {
throw new Error("The API did not return a task ID.");
}
console.log(`Task created: ${data.taskId}`);
return data.taskId;
}
async function waitForResult(taskId) {
const maxChecks = 120;
for (let check = 1; check <= maxChecks; check++) {
const result = await fetchJson(
`${BASE_URL}/jobs/queryTask?taskId=${encodeURIComponent(taskId)}`,
{ headers }
);
console.log(`Status: ${result.status}`);
if (result.status === "COMPLETED") {
const videoUrl = result.output?.[0]?.url;
if (!videoUrl) {
throw new Error("The task completed without a video URL.");
}
console.log(`Video URL: ${videoUrl}`);
return;
}
if (result.status === "FAILED") {
throw new Error(result.error || "The generation task failed.");
}
await delay(5000);
}
throw new Error("The task did not finish within 10 minutes.");
}
async function main() {
const taskId = await createTask();
await waitForResult(taskId);
}
main().catch((error) => {
console.error("Generation failed:", error.message);
process.exitCode = 1;
});
The script sends the request to:
https://seegen.ai/api/v1/jobs/createTask
The model value sd2.5 selects Seedance 2.5. The resolution field controls the frame shape, while outputResolution controls the quality tier.
Here, 1280x720 creates a 16:9 frame, and 480p sets the output quality. You can switch to 720p or 1080p when you have enough credits.
Once SeeGen AI accepts the request, it returns a task ID. The script checks that task every five seconds until it finishes.
Step 4: Run the request
Run this command in the VS Code terminal:
node --env-file=.env generate.mjs
You should see:
Starting Seedance 2.5 request...
Task created: [task ID]
Status: PENDING
The status may change to PROCESSING. When the video is ready, the terminal displays:
Status: COMPLETED
Video URL: [final URL]
Open the URL in your browser to view or download the video.
Common Seedance 2.5 API problems
The API key or credit balance is rejected
A 401 response means the API key is missing or invalid. Check the variable name in .env, the --env-file=.env command, and the Bearer token in the request.
A 402 response means the account does not have enough credits. Try 480p for the first test or add more credits.
The task stays pending or the terminal reports fetch failed
Video generation may take several minutes. The script checks the task for up to ten minutes. Stopping the local script does not cancel a task that SeeGen AI has already accepted.
During my test, VS Code reported fetch failed, but the video still completed on the SeeGen AI website. A status request had lost its connection while the generation continued.
Keep the task ID and check your web history before sending the request again. Otherwise, you may create a duplicate task and spend more credits.
Multi-reference is classified as first-frame-to-video
When using Seedance 2.5 Omni or multi-reference mode, you may see:
The parameter inner_generation_options.pe_classification specified in the request is not valid: You requested the reference generation task type, but Seedance classified your task as first-frame-to-video based on your prompt and input.
This often happens when the prompt contains first frame or last frame. Seedance 2.5 reads those terms and may classify the request as a keyframe task instead of multi-reference generation.
Remove those terms and describe the role of each reference directly.
Instead of:
Use @Image1 as the first frame and @Image2 as the last frame. Use @Image3 as...
Write:
Keep the character from @Image1 and use the location and lighting from @Image2. The character walks across the scene and looks toward the camera.
If you need fixed opening and closing frames, use the first-and-last-frame workflow.
Multi-reference is classified as video editing
You may also see:
The parameter content[1].video_url specified in the request is not valid. Seedance identified your task as video editing based on your prompt. For this task type, the output ratio and duration follow the input video selected by the model for editing, and the video selected must satisfy the duration requirement of 4 to 30 seconds.
This can happen when a multi-reference prompt uses words such as edit or modify. Seedance 2.5 may treat the request as video editing. It then expects a source video between four and 30 seconds. The selected video's ratio and duration also control the output.
Instead of:
Edit Video 1 to add a red coat.
Write:
The character from Video 1 wears a red coat.
If your goal is to edit an existing clip, use the video editing workflow and provide a source video that meets the duration rule.
I have seen these prompt classification errors with Seedance 2.5 Omni and multi-reference generation. I did not get the same errors from Seedance 2.0 during my tests.
The API returns another parameter error
A 400 response usually explains which input is invalid. Check the duration, frame resolution, output quality, and reference files.
A 429 response means the account has reached its concurrency limit. Wait for an active task to finish before submitting another request.
Other Seedance 2.5 API workflows
The same Seedance 2.5 API also supports:
- Image-to-video
- First-and-last-frame generation
- Multi-reference generation
- Video editing
- Video extension
The API key and task process remain the same. You create a task, receive an ID, and check the status until the result is ready. Only the fields inside inputs change.
The Seedance 2.5 API Playground can help you test these modes. It shows the request as you change the settings and provides matching JavaScript, Python, and cURL examples.
Why choose SeeGen AI?
New users can receive 200 credits after signing up and joining the SeeGen AI Discord community. The credits work on both the website and the API.
That is enough for either:
- A five-second Seedance 2.0 video at 720p
- A six-second Seedance 2.5 video at 480p
You can use the free credits to send a real API request and check the result before paying for a larger pack.
SeeGen AI accepts real people in reference images and videos. This matters when a project needs to keep the same person across several shots, such as an ad, a short story, or a series of social videos.
All plans include web and API access. You can begin in the visual workspace, then use the same account and credits from your own code. There is no separate developer subscription to buy.
For larger projects, SeeGen AI supports more than 480 concurrent API tasks. Businesses can also ask for custom pricing, more capacity, and help with integration.
Pricing is credit based, with no subscription required. At the current lowest rate, Seedance 2.0 Mini at 480p costs $0.04 per second. This gives individual users a less expensive way to test prompts and workflows before moving to Seedance 2.0 or Seedance 2.5 for higher quality and more reference control.
Final thoughts
The easiest way to learn the Seedance 2.5 API is to begin with one short text-to-video request. A five-second video at 480p keeps the first test affordable and makes errors easier to trace.
Once you receive a completed task and a working video URL, change the prompt or raise the output quality. You can then move to image-to-video and multi-reference generation without changing the basic task process.
Related articles
Seedance 2.5 API: 7 Best Providers for Developers in 2026
Compare 7 Seedance 2.5 API providers by pricing, concurrency, video input billing, real human support, and free trials. 1.Byteplus; 2.SeeGen AI...
Seedance 2.0 API Guide: Pricing, Providers, Human References, and How to Choose
A complete Seedance 2.0 API guide covering pricing, providers, video input costs, human reference support, concurrency, and how to choose the right API for your project.