DEVELOPER REFERENCE / VIDEO

Video API

Create video tasks with text or media references, then poll and download the result. Explore image-plus-audio reference mode on supported Seedance models.

Updated November 9, 2026Asynchronous tasks
POST/v1/videos
Replace placeholders and check model access before running requests. Live requests may incur usage charges.

1. Getting started

This reference applies to https://api.sinorouter.ai. It documents the site's JSON video interface. Upload, edit and remix operations outside this reference are not covered; full compatibility with every OpenAI Videos feature is not implied.

1.1 Endpoints and authentication

OperationEndpoint
SubmitPOST /v1/videos
PollGET /v1/videos/{task_id}
Download after completionGET /v1/videos/{task_id}/content

Create an API key in the SinoRouter console and select the Video All in One token group. Send Authorization: Bearer YOUR_API_KEY on submission, status and gateway-download requests. Keep the key on your server and out of public code or support messages.

Use the same site for every step. Reusing the same key is recommended.

1.2 Prepare the curl examples

Run the following in Bash before using the individual curl examples in §3 and §5. The complete script in §4 can instead prompt for its key and reference URL, without this setup.

BASH
BASE_URL="https://api.sinorouter.ai"
read -r -s -p "SinoRouter API key (hidden): " API_KEY; printf '\n'
: "${API_KEY:?API_KEY must not be empty}"
export BASE_URL API_KEY

The examples require Bash and curl; reference-image JSON construction also uses jq. The public reference-audio example in §3.4 uses concrete test-media URLs. --fail-with-body requires a curl version that supports it. BASE_URL is the site root because the paths below already include /v1; do not add /v1 twice.

1.3 Models, output resolutions and durations

Exact model IDOutput resolution tiersOutput duration
minimax-h3768P / 2K4–15 s
seedance-2-0480P / 720P / 1080P / 4K4–15 s
seedance-2-0-fast480P / 720P4–15 s
seedance-2-0-mini480P / 720P4–15 s
wan-3-0480P / 720P / 1080P2–30 s; -1 selects automatic duration
seedance-2-5480P / 720P / 1080P4–30 s

Use uppercase resolution labels. If resolution is omitted, the gateway uses the selected model's default. Explicitly selecting a supported tier is recommended. A tier does not guarantee one fixed width and height across aspect ratios or input modes.

These are SinoRouter gateway IDs. Use the exact listed IDs for new requests. The omni-reference mode in §2.3 is documented only for seedance-2-0, seedance-2-0-fast and seedance-2-5; do not infer support for other models from the general reference-media descriptions.

The output tiers follow the official sources listed in §8. Account and route availability still apply; listing a tier is not a claim that every combination has been generated and tested on this gateway.

2. Request parameters

All input modes use JSON submitted to POST /v1/videos. Use prompt for a non-empty scene description and model-specific reference fields where needed. A request being accepted does not establish support for every model and media combination.

2.1 Fields

FieldContract
modelRequired. Use an exact ID from §1.3.
promptNon-empty text. Explicitly provide it for each request. A non-empty string input is accepted as a fallback on this JSON route.
secondsRecommended duration field. Prefer a JSON string such as "5"; numbers are also accepted on the documented route. Choose an integer within the selected model's range in §1.3, or "-1" for Wan automatic duration.
durationCompatible alternative when seconds is absent. Use an integer, and do not send both fields.
resolutionUppercase output tier from §1.3. If omitted, the selected model's default applies. Set it explicitly to avoid depending on a default.
ratio / aspect_ratioTop-level aspect ratio. ratio takes precedence when both are supplied. Values include 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 and model-dependent adaptive. Apply the Seedance 2.5 exceptions in §2.2.
image / images / input_referenceURL strings, {url: ...} objects or arrays. Fields are merged; avoid duplicates. Legacy strings and objects without role use first_frame. For omni reference, every image must be an object with explicit role: "reference_image". See §2.3.
metadata.reference_videoRecommended reference-video field. Accepts a URL string, {url: ...} object or array, with one video maximum after merging. Top-level video_url and video are also accepted; do not duplicate the same reference. This release does not allow reference video together with explicit reference_image or metadata.reference_audio.
metadata.reference_audioOmni reference only, on the three Seedance models in §2.3. A public HTTP(S) URL string, {url: ...} object or array of these. Maximum 3 audio clips at this gateway; published generation acceptance used 1 clip. Explicit reference_image input is required. Audio objects contain only url.

Use complete public HTTP(S) reference URLs that remain valid during generation, preserving every signature query parameter. No source-video duration field is required from the client. Omni-reference images and audio must be directly downloadable URLs; local paths and Base64 data URIs are not supported inputs for this documented mode. Beyond the limits explicitly stated in §2.3, this guide does not promise unverified file sizes, codecs, durations or image counts, and does not describe multipart uploads.

Use reference video as a separate workflow. Do not combine it with the new omni-reference image/audio mode. References guide content; they do not guarantee exact motion, frame-by-frame appearance or inheritance of the original audio track.

2.2 Aspect ratio and Seedance 2.5 exceptions

For ordinary requests with a specific target orientation, explicitly set top-level ratio, such as "9:16" for portrait or "16:9" for landscape. A prompt containing “Vertical 9:16” does not set the API ratio, and resolution: "720P" does not mean portrait output. The gateway does not derive the ratio from size: "720x1280" or metadata.aspect_ratio. If no ratio is supplied, the gateway does not insert a target ratio.

Seedance 2.5 is an exception to the ordinary orientation advice:

  • First-frame image-to-video: omit both ratio and its aspect_ratio alias. The output follows the first-frame image's aspect ratio; prepare the first frame in the intended orientation.
  • Reference-video generation: set ratio: "adaptive". The output follows the reference video's aspect ratio, including extension-style requests. Prepare a reference video with the intended orientation.

Do not replace these exceptions with a fixed 9:16 or 16:9 merely because the prompt requests that shape. These exceptions apply to the first-frame and reference-video modes. The new omni-reference mode uses explicit reference_image roles, rather than a fixed first frame; set a top-level ratio when a specific orientation is required, as in §3.4.

2.3 Omni reference and reference audio

Documented as available on api.sinorouter.ai as of 9 November 2026. Supported models: seedance-2-0, seedance-2-0-fast and seedance-2-5. This release does not document this mode for seedance-2-0-mini, minimax-h3 or wan-3-0.

Character and product images use role: "reference_image" for appearance and content guidance, not as a fixed first frame. Each image must have this explicit role. URL strings and objects with no role retain the old first_frame behavior.

InputSupported form and boundary
Omni-reference imagesPrefer images: [{"url":"https://...","role":"reference_image"}]. The same object form is accepted under image or input_reference. All fields are merged; avoid duplicate images.
Reference audioPut reference_audio inside metadata. Accepts a public HTTP(S) URL string, a {"url":"https://..."} object, or an array of either. Do not add role or other keys to audio objects.
Audio countAt most 3 clips at this gateway. The supplied release notes report actual generation acceptance with 1 clip; they do not claim that every multi-clip combination has been tested.
Required visual inputReference audio requires at least one explicit reference_image. Audio-only generation is not open on this route, including Seedance 2.5.
Audio durationFor Seedance 2.0 / Fast, the upstream limit is a combined audio duration of at most 15 seconds. Start with audio no longer than 15 seconds. This release does not specify a separate Seedance 2.5 audio-duration limit. Output duration remains governed by §1.3.

Do not mix modes:

  • Do not mix first_frame and reference_image in the same request. Do not attach reference audio to a default first-frame image; mark every image explicitly as reference_image.
  • Do not combine reference_video with explicit reference_image or reference_audio in this release.
  • Unsupported combinations return HTTP 400 rather than silently dropping the fields.
  • Audio and video limits are separate upstream constraints; do not interpret them as one combined 15-second allowance. The current gateway mode still does not permit video-plus-audio input.

Validation boundary: The supplied release notes describe successful reference-image plus audio generation, using audio for background music. Voice cloning, melody fidelity and lip synchronization have not undergone dedicated acceptance testing. Do not treat this mode as a verified voice-cloning or lip-sync service. Character/product appearance is not guaranteed pixel for pixel, and the original audio track is not guaranteed to be copied unchanged.

2.4 Submission and duplicate requests

Successful submission returns a task object with an id. Save that ID before polling. Accepted submission does not mean generation has completed. The submission endpoint is not idempotent: another POST creates another task. Do not automatically repeat a POST after a timeout, lost response or unresolved task. Preserve local records and recover the existing ID or contact support.

3. Minimal request examples

Use the setup in §1.2 first. Replace placeholder media URLs with real public links. Each example writes submit.json; use a separate working directory for separate intended tasks. Every POST is a new task.

3.1 Text-to-video

BASH
curl --fail-with-body --silent --show-error --max-time 60 \
  -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "model": "seedance-2-0-fast",
  "prompt": "City night timelapse with traffic light trails",
  "seconds": "5",
  "resolution": "720P",
  "ratio": "16:9"
}' -o submit.json

3.2 Reference image

This example uses standard Seedance 2.0 at 1080P in portrait orientation. The reference URL is safely inserted into JSON with jq.

BASH
read -r -p "Complete public reference-image URL: " IMAGE_URL
jq -n --arg image "$IMAGE_URL" \
  '{model:"seedance-2-0",prompt:"The subject slowly turns toward the camera",seconds:"5",resolution:"1080P",ratio:"9:16",image:$image}' \
  > request-image.json
curl --fail-with-body --silent --show-error --max-time 60 \
  -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request-image.json -o submit.json

For Seedance 2.5 first-frame input, change the model and remove the ratio field from the request body. Follow §2.2 rather than carrying this example's fixed ratio over unchanged. For product/character appearance reference plus audio, use the distinct omni-reference mode in §3.4.

3.3 Reference video

This example requests MiniMax H3 at 768P. Add a supported top-level ratio when a specific orientation is needed; the Seedance 2.5 video-input rule requires adaptive instead of a fixed ratio.

BASH
read -r -p "Complete public reference-video URL: " REFERENCE_VIDEO_URL
jq -n --arg reference "$REFERENCE_VIDEO_URL" \
  '{model:"minimax-h3",prompt:"Use the reference visual style to guide a new scene",seconds:"5",resolution:"768P",metadata:{reference_video:$reference}}' \
  > request-video.json
curl --fail-with-body --silent --show-error --max-time 60 \
  -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request-video.json -o submit.json

3.4 Omni-reference images plus audio

Run the setup in §1.2 first. This example uses the public fruit-tea test assets from the supplied release notes. It references two images and uses the audio as background music; it is not a verified voice-cloning example. Replace the image URLs with your own public character/product images and the audio URL with your own public reference audio when adapting it.

BASH
curl --fail-with-body --silent --show-error --max-time 60 \
  -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "model": "seedance-2-0",
  "prompt": "Use the two images as fruit-tea product and visual-style references, not as a fixed first frame. Show an apple falling into tea, then the packaged drink. Use audio 1 as background music. No subtitles or extra logos.",
  "seconds": "5",
  "resolution": "720P",
  "ratio": "9:16",
  "images": [
    {
      "url": "https://arkdocs.tos-cn-beijing.volces.com/images/video-generation/r2v_tea_pic1.jpg",
      "role": "reference_image"
    },
    {
      "url": "https://arkdocs.tos-cn-beijing.volces.com/images/video-generation/r2v_tea_pic2.jpg",
      "role": "reference_image"
    }
  ],
  "metadata": {
    "reference_audio": "https://arkdocs.tos-cn-beijing.volces.com/files/video-generation/r2v_tea_audio1.mp3"
  }
}' -o submit.json

The example uses seedance-2-0. You can instead select seedance-2-0-fast or seedance-2-5, keeping this explicit reference_image mode. Set the top-level ratio for the desired orientation. Do not add a reference video or remove the image roles. Follow the mode and validation limits in §2.3.

Save the response's id, then use §5 and §6. Alternatively, use the complete script below for the separate reference-video workflow, with task recovery and download verification.

4. Complete Bash workflow

4.1 Requirements and configuration

Save the following script as reference-video.sh. Run it with Bash, not sh. It uses curl, jq, mktemp, ffprobe and ffmpeg. FFmpeg supplies ffprobe and ffmpeg; the script requires both to inspect and fully decode the download before finalizing it. Bash 4+ is recommended. On macOS, Homebrew can install bash curl jq ffmpeg; on Debian/Ubuntu install bash curl jq ffmpeg with your package manager. On Windows, run the script in WSL.

The new-task example explicitly requests MiniMax H3, 768P, 4 output seconds, one reference video. Four seconds refers to the requested output, not a required source-video length. The 768P setting is an explicit example choice, not a default for every model.

Run the script in a writable directory. It prompts for the API key and the complete public reference-video URL. Do not paste a bare URL as a shell command. Keep all &, % and signature parameters. Login pages, private-network addresses, expired links and example domains are not usable reference assets.

BASH
#!/usr/bin/env bash
# Run with Bash. Never enable bash -x or curl verbose tracing.
set -euo pipefail
umask 077
for tool in curl jq mktemp ffprobe ffmpeg; do
  command -v "$tool" >/dev/null || {
    printf 'Missing dependency: %s\n' "$tool" >&2; exit 2;
  }
done

BASE_URL="${BASE_URL:-https://api.sinorouter.ai}"
BASE_URL="${BASE_URL%/}"
[[ "$BASE_URL" == https://* ]] || {
  printf 'Use an HTTPS gateway URL.\n' >&2; exit 2;
}
WAIT_SECONDS="${WAIT_SECONDS:-900}"
POLL_SECONDS="${POLL_SECONDS:-5}"
[[ "$WAIT_SECONDS" =~ ^[1-9][0-9]*$ && "$POLL_SECONDS" =~ ^[1-9][0-9]*$ ]] || exit 2

# New run: a new private directory. Resume: set RUN_DIR to that directory.
RUN_DIR="${RUN_DIR:-$(mktemp -d "${PWD}/video-run.XXXXXX")}"
mkdir -p "$RUN_DIR"
printf 'Private task directory: %s\n' "$RUN_DIR"
if [[ -f "$RUN_DIR/base-url.txt" ]]; then
  [[ "$(cat "$RUN_DIR/base-url.txt")" == "$BASE_URL" ]] || {
    printf 'Resume on the original gateway site.\n' >&2; exit 2;
  }
else
  printf '%s\n' "$BASE_URL" > "$RUN_DIR/base-url.txt"
fi

if [[ -z "${API_KEY:-}" ]]; then
  read -r -s -p 'SinoRouter API key (hidden): ' API_KEY
  printf '\n'
fi
[[ -n "$API_KEY" && "$API_KEY" != *$'\r'* && "$API_KEY" != *$'\n'* ]] || exit 2
AUTH_FILE="$(mktemp "${RUN_DIR}/auth.XXXXXX")"
printf 'Authorization: Bearer %s\n' "$API_KEY" > "$AUTH_FILE"
unset API_KEY
trap 'rm -f "$AUTH_FILE"' EXIT

request_json() {
  local label="$1" method="$2" url="$3" http
  shift 3
  if ! http="$(curl --silent --show-error --connect-timeout 20 --max-time 90 \
    --proto '=https' --request "$method" --header "@$AUTH_FILE" \
    --output "$RUN_DIR/$label.json" --write-out '%{http_code}' "$@" "$url")"; then
    printf '%s transfer failed. Keep %s; do not resend POST.\n' "$label" "$RUN_DIR" >&2
    return 1
  fi
  printf '%s\n' "$http" > "$RUN_DIR/$label.http"
  [[ "$http" =~ ^2[0-9][0-9]$ ]] || {
    printf '%s HTTP %s. Inspect %s/%s.json privately.\n' "$label" "$http" "$RUN_DIR" "$label" >&2
    return 1
  }
  jq -e 'type == "object" and (.error == null or .status == "failed")' "$RUN_DIR/$label.json" >/dev/null || {
    printf 'Invalid or error JSON. Keep local records; redact before sharing.\n' >&2
    return 1
  }
}

TASK_ID="${TASK_ID:-}"
if [[ -s "$RUN_DIR/task-id.txt" ]]; then
  SAVED_TASK_ID="$(cat "$RUN_DIR/task-id.txt")"
  [[ -z "$TASK_ID" || "$TASK_ID" == "$SAVED_TASK_ID" ]] || {
    printf 'TASK_ID differs from this directory. Use the original task.\n' >&2; exit 2;
  }
  TASK_ID="$SAVED_TASK_ID"
fi
if [[ -z "$TASK_ID" ]]; then
  [[ ! -e "$RUN_DIR/submit-started" ]] || {
    printf 'Previous POST outcome is unresolved. Inspect submit.json or contact support; do not resubmit.\n' >&2
    exit 1
  }
  if [[ -z "${REFERENCE_VIDEO_URL:-}" ]]; then
    read -r -p 'Complete public reference-video URL: ' REFERENCE_VIDEO_URL
  fi
  [[ "$REFERENCE_VIDEO_URL" == https://* || "$REFERENCE_VIDEO_URL" == http://* ]] || {
    printf 'Provide a public HTTP(S) video URL with all signature parameters.\n' >&2; exit 2;
  }
  # This example explicitly requests MiniMax H3, 768P, 4 output seconds.
  jq -n --arg reference "$REFERENCE_VIDEO_URL" \
    --arg prompt 'Use the reference subject, scene and motion to guide a new, naturally moving shot; keep a steady camera, with no text or watermarks.' \
    '{model:"minimax-h3",prompt:$prompt,seconds:"4",resolution:"768P",metadata:{reference_video:$reference}}' \
    > "$RUN_DIR/request.json"
  unset REFERENCE_VIDEO_URL
  # An exclusive marker blocks another POST when this directory is reused.
  (set -o noclobber; : > "$RUN_DIR/submit-started") || {
    printf 'Submission already started in this directory.\n' >&2; exit 1;
  }
  request_json submit POST "$BASE_URL/v1/videos" \
    --header 'Content-Type: application/json' --data-binary "@$RUN_DIR/request.json"
  TASK_ID="$(jq -er '.id | select(type == "string" and length > 0)' "$RUN_DIR/submit.json")" || {
    printf 'No task ID saved. Inspect submit.json; do not repeat POST.\n' >&2; exit 1;
  }
fi
printf '%s\n' "$TASK_ID" > "$RUN_DIR/task-id.txt"
# Task IDs are opaque; encode the complete ID as one path segment.
TASK_PATH="$(jq -nr --arg id "$TASK_ID" '$id | @uri')"
printf 'TASK_ID=%s\n' "$TASK_ID"

deadline=$((SECONDS + WAIT_SECONDS))
while true; do
  if (( SECONDS >= deadline )); then
    printf 'Client wait ended. Resume this directory; do not submit again.\n' >&2
    exit 3
  fi
  request_json task GET "$BASE_URL/v1/videos/$TASK_PATH"
  status="$(jq -er '.status | select(type == "string")' "$RUN_DIR/task.json")" || exit 1
  printf 'status=%s\n' "$status"
  case "$status" in
    completed) break ;;
    queued|in_progress) sleep "$POLL_SECONDS" ;;
    failed|cancelled|canceled)
      printf 'Task terminated. Inspect task.json (error.message); redact before sharing.\n' >&2
      exit 1 ;;
    *) printf 'Unknown status. Keep the task ID and contact support.\n' >&2; exit 1 ;;
  esac
done

# Authentication is for the gateway. Never use --location-trusted.
if ! curl --fail --location --silent --show-error \
  --connect-timeout 20 --max-time 300 --proto '=https' --proto-redir '=https' \
  --max-redirs 5 --header "@$AUTH_FILE" --dump-header "$RUN_DIR/video.headers" \
  --output "$RUN_DIR/video.part" --write-out '%{http_code}\n%{content_type}\n' \
  "$BASE_URL/v1/videos/$TASK_PATH/content" > "$RUN_DIR/download.meta"; then
  printf 'Download failed. Resume the same task; do not generate again.\n' >&2; exit 1
fi
DOWNLOAD_HTTP="$(sed -n '1p' "$RUN_DIR/download.meta")"
DOWNLOAD_TYPE="$(sed -n '2p' "$RUN_DIR/download.meta")"
[[ "$DOWNLOAD_HTTP" =~ ^2[0-9][0-9]$ && "$DOWNLOAD_TYPE" == video/* && -s "$RUN_DIR/video.part" ]] || {
  printf 'Unexpected HTTP status, media type or empty file.\n' >&2; exit 1;
}
ffprobe -v error -show_entries format=duration:stream=codec_type,width,height \
  -of json "$RUN_DIR/video.part" > "$RUN_DIR/probe.json"
jq -e 'any(.streams[]?; .codec_type == "video")' "$RUN_DIR/probe.json" >/dev/null
ffmpeg -v error -xerror -i "$RUN_DIR/video.part" -f null - || {
  printf 'Video decoding failed. Preserve the temporary file for diagnosis.\n' >&2; exit 1;
}
mv "$RUN_DIR/video.part" "$RUN_DIR/video.mp4"
printf 'Saved and decoded: %s/video.mp4\n' "$RUN_DIR"
# Request files and response headers may contain signed URLs. Keep them private.

4.2 What the script preserves

  • A private task directory holds the request, HTTP responses, task ID, gateway URL and download diagnostics. Request files and response headers may contain signed URLs; do not publish the directory.
  • One POST is attempted for a new task. A saved submission marker blocks another POST when the same directory is reused after an uncertain outcome.
  • After an ID has been saved, resuming the directory skips submission and continues status checks and download for that ID.
  • A local wait limit exits with code 3. It does not change the task to failed. Transfer, HTTP, JSON, terminal-task and download errors also preserve records for diagnosis.
  • The API key is kept in a temporary private header file that is removed on exit. Never enable shell tracing, use curl verbose logs or forward the key to a different host.

4.3 Resume an existing task

Copy the exact task directory printed by the original run, set RUN_DIR, and run the same script. Use the original site and preferably the same key. No new reference URL is needed after the task ID has been saved.

BASH
read -r -p "Original task directory: " RUN_DIR
export RUN_DIR
bash reference-video.sh

If the original directory is unavailable but you retained a task ID, set TASK_ID explicitly. This creates a new local record directory and queries the existing task; it does not submit a new one.

BASH
read -r -p "Existing task ID: " TASK_ID
export TASK_ID
bash reference-video.sh

Starting again without either the original RUN_DIR or a TASK_ID creates a new task. If submission was interrupted before the ID was saved, reuse the original directory and inspect submit.json; the marker intentionally stops automatic resubmission. Contact support if the outcome cannot be resolved.

4.4 Adapt the input mode

To adapt this script to text-only input, edit the jq request construction to omit metadata.reference_video and remove the reference-URL reading step. Keep a non-empty prompt, valid model, supported resolution and valid output duration. For reference images, read a real image URL and insert it with jq --arg; do not put shell variable names inside single-quoted JSON expecting expansion.

For omni-reference images plus audio, use the exact field structure in §3.4 instead of adding audio to the reference-video request. Only the three listed Seedance models support this documented mode; remove the video field, mark every image reference_image, and supply metadata.reference_audio. The saved task ID, polling and content download flow remain the same.

Changing to another model requires reviewing its duration and resolution in §1.3 and the mode-specific ratio rules in §2.2–§2.3. Keep the same saved task ID for every later GET. The workflow does not require a client-provided source-video duration.

5. Query task status

5.1 Endpoint and safe polling

Query GET /v1/videos/{task_id}. Treat the ID as an opaque string and URL-encode it as a single path segment. Poll every 3–5 seconds as a client recommendation, with backoff for rate limits or temporary service errors. A polling interval is not a completion-time guarantee.

For a manual query after §1.2, set the actual task ID first:

BASH
read -r -p "Existing task ID: " TASK_ID
TASK_PATH=$(jq -nr --arg id "$TASK_ID" '$id | @uri')
curl --fail-with-body --silent --show-error --max-time 60 \
  "$BASE_URL/v1/videos/$TASK_PATH" \
  -H "Authorization: Bearer $API_KEY" -o task.json

5.2 Task object

Submission and polling use a task-object structure. The following is illustrative; optional fields and field values depend on the actual response.

JSON
{
  "id": "YOUR_TASK_ID",
  "object": "video",
  "model": "seedance-2-0",
  "status": "queued",
  "progress": 0,
  "created_at": 1793955305,
  "seconds": "5"
}
FieldMeaning
idTask ID to save after submission and reuse for status and download requests.
statusqueued, in_progress, completed or failed. Only completed means the video is ready to download.
objectWhen present, video.
modelCanonical public model name when present.
progressEstimated integer progress from 0 to 100 when present. It is not a completion-time promise.
created_atCreation timestamp in Unix seconds when present.
seconds / sizeOptional duration or size-tier echo. Do not require these fields to be present.
completed_atCurrently returned at successful completion on this site. Determine completion from status, not the presence of this timestamp.
error.messageFailure explanation for a failed task. Keep the full response privately and redact it before sharing.

The task object does not include a direct media URL. Only after status is completed, download through /v1/videos/{task_id}/content. Do not guess a URL from task fields or historical media links.

5.3 Status handling

StatusAction
queuedWait and continue polling the same ID.
in_progressGeneration is running; continue polling the same ID.
completedProceed to the content download endpoint.
failedStop; inspect error.message and preserve the response and task ID.
Unknown, unrecognized or cancelled stateDo not treat it as success. Stop and keep the response for support.

A network error or local wait limit does not establish generation failure. Save the task ID, stop active polling at your application's limit and resume later. Do not automatically submit another task while the original remains unresolved.

6. Download and verify the video

Use authenticated GET /v1/videos/{task_id}/content after completion. The endpoint returns video content, potentially through an HTTPS redirect; it is not a task-JSON endpoint.

The complete script downloads into a temporary file, checks the final HTTP status, requires a video/* content type and a non-empty file, verifies a video stream with ffprobe and fully decodes it with ffmpeg before naming it video.mp4. A filename extension or non-empty response alone does not establish a valid video.

Curl does not forward Authorization to a different host on redirects by default. Never add --location-trusted or manually send your SinoRouter key to an external media host. Response headers may contain signed redirect URLs and must be redacted before sharing. If the download host needs additional authorization, keep the task ID and contact support.

If a download reports that the task is not ready, return to polling rather than generating again. Download promptly and store the result yourself. No permanent media availability, retention period or guaranteed recovery is promised here.

7. Troubleshooting

SymptomCheck / action
401 / 403Check the site's key, its validity, account/token permissions and Authorization on submission, query and gateway download.
No available channelConfirm the exact model ID and Video All in One token group. Availability may change.
404 / HTML responseCheck the gateway domain, /v1/videos path, duplicate /v1 and invisible characters. Do not submit to /v1/videos/generations.
Task not foundCheck the original site, returned task ID and owning account. Do not attribute every 404 to a key change or a fixed retention period.
cannot unmarshal number ... seconds ... stringUse a JSON string such as "5" for seconds, which is the recommended form across clients.
Resolution or duration rejectedCheck uppercase labels and the selected model's tiers and duration range in §1.3. Do not rely on silent fallback.
Reference-media errorCheck the complete URL, public access and expiry. Merged reference videos must total no more than one.
HTTP 400 for omni reference or audioUse one of the three models in §2.3. Mark every image reference_image; put audio under metadata.reference_audio, with at most 3 clips and only url in audio objects. Do not mix first-frame, reference-video or audio-only modes.
Seedance 2.5 first-frame ratio rejectedOmit both ratio and aspect_ratio; the first frame determines the aspect ratio.
Seedance 2.5 video ratio rejectedSet ratio: "adaptive" and use a reference video with the desired shape.
Maximum concurrency reachedLimit active tasks and inspect the original result. Sequential POST calls alone do not limit the number of active tasks.
Download says task is not completedQuery the same ID and download only after status: "completed".
artifact_gone / download unavailableKeep the task ID and error and contact support. Permanent recovery is not guaranteed.
model_price_errorServer-side model configuration issue. Provide the task ID, model and redacted error; repeated submissions are not a remedy.

For support, provide the request time with timezone, gateway domain, model ID, task ID, HTTP status and redacted error body. Do not send API keys, complete signed media URLs or sensitive source assets. Use current console notices for model and feature changes.

8. Official output-resolution references

The output-resolution tiers retained in this reference were reviewed against the following official pages on 7 November 2026. The document was revised on 9 November 2026 using the latest supplied SinoRouter integration notes. This document revision does not claim a new live generation test; the new mode and its reported acceptance scope are described in §2.3. SinoRouter keeps uppercase labels in its JSON requests even where upstream documents use lowercase labels.

These sources concern upstream output tiers. SinoRouter authentication, endpoint paths, field mapping and account availability remain gateway-specific.