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

  1. GET /v1/models: the models your key may use, their modes, settings and inputs.
  2. POST /v1/quote (optional): the price of a request, in VND.
  3. POST /v1/tasks: create the task. The price is held from your balance.
  4. GET /v1/tasks/{task_id}: ask every 10 to 30 seconds until status is succeeded or failed.
  5. 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" } }
HTTPcodemeaning
401AUTH_INVALIDmissing or wrong key
403KEY_PAUSED, KEY_EXPIRED, IP_NOT_ALLOWEDthe key cannot be used now or from here
403MODEL_NOT_ALLOWEDthe key cannot use this model or setting
400INVALID_INPUT, CONTENT_REFUSEDfix the request (field says where)
402INSUFFICIENT_FUNDStop up your balance
429RATE_LIMITED, QUOTA_EXCEEDEDslow down, or the daily/monthly limit is reached
409PRICE_CHANGED, CONFLICTsend again
404NOT_FOUNDno such task or path
503TEMPORARY_UNAVAILABLEretry later

A failed task carries error.code GENERATION_FAILED and is refunded.