HiAPI Seedance 2.0 Video

intent

generate videos using HiAPI's seedance-2-0 model through their unified async task API. use this skill when a user asks to create a video with seedance 2.0, either from text alone (text-to-video), from a single image (image-to-video), from paired first and last frames, or from multimodal references (images, videos, audio). the skill handles task creation, polling for completion, downloading the result, and reporting status or errors.

inputs

• HIAPI_API_KEY (required, environment variable): your HiAPI authentication token. obtain from https://www.hiapi.ai/en/register.
• HIAPI_BASE_URL (optional, environment variable): defaults to https://api.hiapi.ai. override only if using a custom HiAPI endpoint.
• Node.js 18+: required runtime for the generation script.
• prompt (required string): text description of the video you want. be specific and cinematic.
• seconds (integer, 4 to 15): video duration. defaults to 5 if omitted.
• resolution (string): one of 480p, 720p, 1080p. defaults to 720p.
• ratio (string): aspect ratio. one of 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, adaptive. defaults to 16:9.
• media mode inputs (all optional, mutually exclusive groups):
  • text-to-video: no media fields.
  • image-to-video (first frame): --first-frame-url or --input-reference (legacy alias).
  • image-to-video (first + last frame): both --first-frame-url and --last-frame-url.
  • multimodal reference: any combination of --reference-image-url, --reference-video-url, --reference-audio-url.
• reference material (optional):
  • reference images: max 9 total (including first/last frames). public URLs or data URIs.
  • reference videos: max 3, each 2-15 seconds, total duration max 15 seconds. requires --reference-video-duration per video.
  • reference audio: max 3 clips, each 2-15 seconds, total duration max 15 seconds. requires --reference-audio-duration per clip.
• generate-audio (optional boolean flag): pass --generate-audio to force audio generation on, or --no-audio/--no-generate-audio to disable. API default is on.
• seed (optional integer, 0 to 2147483647): for reproducible generation. omit for random.
• return-last-frame (optional boolean): request the last frame as a separate image. defaults to false.
• web-search (optional boolean): enable web search for reference. defaults to false.
• nsfw-checker (optional boolean): enable NSFW content filtering. defaults to false.

procedure

1. verify configuration: run node scripts/check-config.mjs. this validates that HIAPI_API_KEY is set and (with --live) confirms the key can reach HiAPI's pricing endpoint. if missing, stop and direct user to https://www.hiapi.ai/en/register.

2. construct the command: build a node script call with the user's prompt and optional parameters. example for text-to-video:

   node scripts/hiapi-seedance-2-video.mjs \
     --prompt "A cinematic ocean cliff shot at golden hour" \
     --seconds 5 \
     --resolution 720p \
     --ratio 16:9
   

   for image-to-video:

   node scripts/hiapi-seedance-2-video.mjs \
     --prompt "The product photo comes alive with soft camera movement" \
     --first-frame-url "https://example.com/product.jpg"
   

3. submit the task: the script POSTs to POST /v1/tasks with model seedance-2-0 and the input object. the request body includes prompt, duration, resolution, aspect_ratio, and any media fields. omit generate_audio unless explicitly set; omit seed unless provided.

4. poll for completion: the script calls GET /v1/tasks/{taskId} repeatedly (with backoff) until the task status is succeeded or failed. typical generation takes 1-5 minutes depending on video length and complexity.

5. download the result: if the task succeeds and a downloadable URL is present, the script saves the video to outputs/ with an auto-generated filename. if download fails or is unavailable, the script returns the remote URL instead.

6. report output: the script prints a JSON object containing the file path (local) or remote URL, task ID, and status. on failure, it prints the HTTP status code, error message, and guidance from the error section below.

decision points

• if media mode is ambiguous (e.g., user passes both first-frame-url and reference-image-url): reject with a clear message. first/last-frame fields and multimodal reference fields are mutually exclusive. the API will return HTTP 400 if both are present.

• if HIAPI_API_KEY is missing: tell the user to create or copy a key from https://www.hiapi.ai/en/register and export HIAPI_API_KEY=<key>.

• if HTTP 401 or 403 (auth error): tell the user to verify their HiAPI API key is correct and not expired.

• if HTTP 402 or 403 with quota/credit language: tell the user to add credits or check billing at https://www.hiapi.ai/en/dashboard and review pricing at https://www.hiapi.ai/en/pricing.

• if HTTP 400 (bad request): tell the user to check duration (4-15), resolution (480p/720p/1080p), ratio, media mode exclusivity, and reference counts (max 9 images, max 3 videos/audio each, max 15s total per type).

• if HTTP 429 (rate limit): tell the user to wait and retry or reduce concurrent video generations.

• if task status is failed: ask the user to try a clearer or more specific prompt, use a different image, or report the error details to HiAPI support.

• if polling times out (no completion after ~30 minutes): explain that video generation may still be running. the user can retry the task ID later or submit a new request.

• if download fails but the video exists on HiAPI: return the remote URL and tell the user they can download it manually.

• if skill update is required: print a required update notice and ask the user to run the printed update command before using the skill again.

output contract

success is a JSON object printed to stdout with the structure:

{
  "task_id": "abc123...",
  "status": "succeeded",
  "video_url": "https://...",
  "local_path": "outputs/seedance-2-0-abc123-uuid.mp4",
  "duration_seconds": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "model": "seedance-2-0"
}

• task_id: the HiAPI task ID for reference or retry.
• status: must be succeeded.
• video_url: remote URL where the video is stored. always present on success.
• local_path: file path in outputs/ where the video was saved. present only if local download succeeded; otherwise omitted.
• duration_seconds, resolution, aspect_ratio, model: echo the request parameters for confirmation.

on failure, the JSON includes status, task_id, http_status, and error_message, e.g.:

{
  "task_id": "abc123...",
  "status": "failed",
  "http_status": 400,
  "error_message": "Invalid aspect ratio"
}

outcome signal

the user knows the skill worked when:

• the script prints a JSON object with "status": "succeeded".
• the video file is present in outputs/ (if local_path is set).
• the user can play or download the video from the provided video_url.
• the printed task_id can be used to track the generation in the HiAPI dashboard.

the user knows the skill failed when:

• the script prints a JSON object with "status": "failed" or "error".
• the error message and http_status guide the next action (see decision points above).
• no video file appears in outputs/ and no valid video_url is returned.