API Docs
Getting started
Base URL: https://api.spiderhub.app. Every call carries your key:
Authorization: Bearer ak_your_key
Your key is tied to your own models, prices, limits and balance. Keep it secret: anyone with it spends your balance.
How a task runs
GET /v1/models: the models your key may use, their modes, settings and inputs.POST /v1/quote(optional): the price of a request, in VND.POST /v1/tasks: create the task. The price is held from your balance.GET /v1/tasks/{task_id}: ask every 10 to 30 seconds untilstatusissucceededorfailed.GET /v1/tasks/{task_id}/result: download the file (kept 7 days).
A task that fails is refunded in full. Tasks above your concurrent limit wait in your own queue and start in order (up to 24 hours).
Create a task
curl -X POST https://api.spiderhub.app/v1/tasks \
-H "Authorization: Bearer ak_your_key" -H "Content-Type: application/json" \
-d '{
"request_id": "order-2026-0001",
"model": "seedance-2.5",
"mode": "prompt-to-video",
"options": { "prompt": "A red fox running through snow", "duration_seconds": 10, "resolution": "720p", "aspect_ratio": "16:9" }
}'
request_id (8 to 128 characters of letters, digits and . _ : -) is yours: sending the same one again returns the same task and is never charged twice.
{ "task_id": "…", "status": "processing", "amount_vnd": 15000, "created_at": "…" }
Reference files
Put files in inputs, by the input name of the mode: either public https links, or the upload_id of a file you uploaded.
curl -X POST https://api.spiderhub.app/v1/uploads \ -H "Authorization: Bearer ak_your_key" -H "Content-Type: image/png" --data-binary @frame.png
"inputs": { "images": ["https://example.com/a.jpg", "UPLOAD_ID"] }
Uploads are kept 24 hours. Formats, sizes and lengths are listed per input in GET /v1/models.
Read a task
{ "task_id": "…", "model": "seedance-2.5", "mode": "prompt-to-video", "status": "succeeded", "amount_vnd": 15000,
"created_at": "…", "finished_at": "…",
"result": { "url": "https://api.spiderhub.app/v1/tasks/…/result", "expires_at": "…" } }
status is processing (waiting or running), succeeded or failed (with error.code and refunded: true). The result link needs your key.
Balance and usage
GET /v1/balance: your balance, the amount held for running tasks, and your daily and monthly task counts against their limits.
GET /v1/usage?from=2026-11-01&to=2026-11-30: tasks made, succeeded, failed and charged per day (Vietnam time, 31 days at most).
Prices
prices_vnd in GET /v1/models is your price of the longest clip at each resolution (or of one image). A shorter clip costs its share; reference videos and some settings add to it. POST /v1/quote gives the exact amount.
Limits
Your key has a number of tasks that run at once, a number of create calls and of read calls per minute, and daily and monthly task limits. A call over the per-minute limit is answered 429 RATE_LIMITED with Retry-After (seconds).
Errors
{ "error": { "code": "INVALID_INPUT", "message": "The request is not valid.", "field": "options.duration_seconds" } }
| HTTP | code | meaning |
|---|---|---|
| 401 | AUTH_INVALID | missing or wrong key |
| 403 | KEY_PAUSED, KEY_EXPIRED, IP_NOT_ALLOWED | the key cannot be used now or from here |
| 403 | MODEL_NOT_ALLOWED | the key cannot use this model or setting |
| 400 | INVALID_INPUT, CONTENT_REFUSED | fix the request (field says where) |
| 402 | INSUFFICIENT_FUNDS | top up your balance |
| 429 | RATE_LIMITED, QUOTA_EXCEEDED | slow down, or the daily/monthly limit is reached |
| 409 | PRICE_CHANGED, CONFLICT | send again |
| 404 | NOT_FOUND | no such task or path |
| 503 | TEMPORARY_UNAVAILABLE | retry later |
A failed task carries error.code GENERATION_FAILED and is refunded.
Bắt đầu
Địa chỉ: https://api.spiderhub.app. Mọi lệnh gửi kèm khóa:
Authorization: Bearer ak_khoa_cua_ban
Khóa gắn với model, giá, giới hạn và số dư riêng của bạn. Giữ kín khóa: ai có khóa đều tiêu được số dư của bạn.
Một việc chạy thế nào
GET /v1/models: các model khóa được dùng, chế độ, thông số và đầu vào.POST /v1/quote(tùy chọn): giá của một yêu cầu, tính bằng VND.POST /v1/tasks: tạo việc. Giá được giữ từ số dư.GET /v1/tasks/{task_id}: hỏi mỗi 10 đến 30 giây cho tới khistatuslàsucceededhoặcfailed.GET /v1/tasks/{task_id}/result: tải file (giữ 7 ngày).
Việc lỗi được hoàn tiền đủ. Việc vượt số luồng cùng lúc nằm trong hàng chờ riêng của bạn và chạy lần lượt (tối đa 24 giờ).
Tạo việc
Xem ví dụ curl ở bản tiếng Anh. request_id (8 đến 128 ký tự chữ, số và . _ : -) do bạn đặt: gửi lại cùng một mã thì nhận lại đúng việc đó, không bao giờ bị tính tiền 2 lần.
File tham chiếu
Đặt file vào inputs theo tên đầu vào của chế độ: link https công khai, hoặc upload_id của file đã tải lên bằng POST /v1/uploads. File tải lên giữ 24 giờ. Định dạng, dung lượng và độ dài cho phép ghi trong GET /v1/models.
Xem việc
status là processing (đang chờ hoặc đang chạy), succeeded (kèm result.url) hoặc failed (kèm error.code, refunded: true). Tải file cũng cần khóa.
Số dư và số liệu
GET /v1/balance: số dư, số tiền đang giữ cho việc đang chạy, và số việc trong ngày, trong tháng so với giới hạn.
GET /v1/usage?from=2026-11-01&to=2026-11-30: số việc tạo, xong, lỗi và tiền đã trừ theo từng ngày (giờ Việt Nam, tối đa 31 ngày).
Giá
prices_vnd trong GET /v1/models là giá clip dài nhất ở mỗi độ phân giải (hoặc giá một ảnh). Clip ngắn hơn tính theo phần tương ứng; video tham chiếu và một số thông số cộng thêm. POST /v1/quote cho số tiền chính xác.
Giới hạn
Khóa có số việc chạy cùng lúc, số lệnh tạo và số lệnh đọc mỗi phút, và giới hạn số việc theo ngày, theo tháng. Gọi quá số lệnh mỗi phút sẽ nhận 429 RATE_LIMITED kèm Retry-After (giây).
Lỗi
Mã lỗi giống bản tiếng Anh. Việc lỗi có error.code là GENERATION_FAILED và được hoàn tiền.