HiAPIAI/hiapi-seedance-2-5-video-skill
hiapi-seedance-2-5-video
VerifiedPlan, generate, recover, download, and quality-check Seedance 2.5 videos through HiAPI. Use for Seedance 2.5 text-to-video, first/last-frame image-to-video, multimodal reference-to-video, or a complete brief-to-delivery video workflow.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.8 KB |
| agents/openai.yaml | config | 361 B |
| assets/social-preview-seedance-2-5.png | binary | 1.6 MB |
| references/api.md | markdown | 4.8 KB |
| references/output.md | markdown | 2.0 KB |
| references/upgrade-policy.md | markdown | 1.7 KB |
| references/workflow.md | markdown | 5.1 KB |
| scripts/check-config.mjsexecutable | script | 812 B |
| scripts/hiapi-seedance-2-video.mjsexecutable | script | 1.4 KB |
| scripts/install.mjsexecutable | script | 5.7 KB |
| scripts/lib/seedance-2-video.mjs | script | 39.0 KB |
scripts/lib/seedance-2-video.mjs
View on GitHubimport { randomUUID } from "node:crypto";
import { mkdir, writeFile } from "node:fs/promises";
import { extname, join, resolve } from "node:path";
export const SKILL_ID = "hiapi-seedance-2-5-video";
export const SKILL_VERSION = "1.2.1";
export const DEFAULT_BASE_URL = "https://api.hiapi.ai";
export const DEFAULT_SITE_URL = "https://api.hiapi.ai";
export const DEFAULT_SKILLS_MANIFEST_URL = "https://raw.githubusercontent.com/HiAPIAI/hiapi-skills/main/skills.json";
export const DEFAULT_REPOSITORY_POLICY_URL = "https://raw.githubusercontent.com/HiAPIAI/hiapi-seedance-2-5-video-skill/main/update-policy.json";
export const UPDATE_COMMAND = "npx -y github:HiAPIAI/hiapi-seedance-2-5-video-skill -y";
export const MODELS = Object.freeze({
text: "seedance-2.5/text-to-video",
image: "seedance-2.5/image-to-video",
reference: "seedance-2.5/reference-to-video",
});
export const DEFAULT_SECONDS = 5;
export const MIN_SECONDS = 4;
export const MAX_SECONDS = 30;
export const DEFAULT_RESOLUTION = "720p";
export const DEFAULT_RESOLUTIONS = Object.freeze({
text: "720p",
image: "720p",
reference: "480p",
});
export const SUPPORTED_RESOLUTIONS = new Set(["720p", "1080p"]);
export const SUPPORTED_RESOLUTIONS_BY_MODE = Object.freeze({
text: new Set(["720p", "1080p"]),
image: new Set(["720p", "1080p"]),
reference: new Set(["480p", "720p", "1080p"]),
});
export const DEFAULT_RATIO = "adaptive";
export const SUPPORTED_RATIOS = new Set(["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "adaptive"]);
export const SUPPORTED_OUTPUT_FORMATS = new Set(["mp4", "mov"]);
export const MAX_REFERENCE_IMAGES = 30;
export const MAX_REFERENCE_VIDEOS = 10;
export const MAX_REFERENCE_AUDIO = 10;
export const MIN_REFERENCE_MEDIA_SECONDS = 2;
export const MAX_REFERENCE_MEDIA_SECONDS = 30;
export const MAX_REFERENCE_MEDIA_TOTAL_SECONDS = 30;
export const DEFAULT_TIMEOUT_MINUTES = 120;
export const MIN_TIMEOUT_MINUTES = 1;
export const MAX_TIMEOUT_MINUTES = 180;
export const POLL_INTERVAL_MS = 5_000;
export const DEFAULT_OUTPUT_DIR = "outputs";
export const DEFAULT_STORAGE = "temp";
export const SUPPORTED_STORAGE = new Set(["temp", "persistent"]);
export const HIAPI_API_KEYS_URL = "https://www.hiapi.ai/en/dashboard/api-keys";
export const HIAPI_DASHBOARD_URL = "https://www.hiapi.ai/en/dashboard";
export const HIAPI_PRICING_URL = "https://www.hiapi.ai/en/pricing";
const TERMINAL_FAILURES = new Set(["fail", "failed", "error", "cancelled", "canceled"]);
export function resolveConfig(env = process.env) {
const apiKey = env.HIAPI_API_KEY?.trim();
if (!apiKey) {
throw new Error(
`HIAPI_API_KEY is required for task creation or recovery. Get one at ${HIAPI_API_KEYS_URL}, then export it in your shell.`,
);
}
return {
apiKey,
baseUrl: (env.HIAPI_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, ""),
};
}
export function normalizeMode(value) {
const mode = String(value || "").trim().toLowerCase();
const aliases = new Map([
["text", "text"], ["text-to-video", "text"], ["t2v", "text"],
["image", "image"], ["image-to-video", "image"], ["i2v", "image"],
["reference", "reference"], ["reference-to-video", "reference"], ["r2v", "reference"],
]);
if (!aliases.has(mode)) {
throw new Error('Unsupported mode. Use "text", "image", or "reference".');
}
return aliases.get(mode);
}
export function resolveMode(options = {}) {
const videoRefs = normalizeList(options.referenceVideoUrls);
const imageRefs = normalizeList(options.referenceImageUrls);
const audioRefs = normalizeList(options.referenceAudioUrls);
const hasFrames = Boolean(cleanMedia(options.firstFrameUrl || options.inputReference) || cleanMedia(options.lastFrameUrl));
const inferred = videoRefs.length > 0 ? "reference" : (hasFrames || imageRefs.length > 0 || audioRefs.length > 0 ? "image" : "text");
const modelMode = options.model ? Object.keys(MODELS).find((mode) => MODELS[mode] === options.model) : null;
if (options.model && !modelMode) throw new Error(`Unsupported model ID: ${options.model}`);
if (modelMode && options.mode && normalizeMode(options.mode) !== modelMode) throw new Error("--model and --mode disagree.");
const explicit = options.mode ? normalizeMode(options.mode) : (modelMode || inferred);
if (explicit === "text" && (hasFrames || imageRefs.length || videoRefs.length || audioRefs.length)) {
throw new Error("Text-to-video cannot include frame or reference media.");
}
if (explicit === "image" && videoRefs.length) {
throw new Error("Reference videos require --mode reference (or omit --mode and let the skill select it).");
}
if (explicit === "reference" && videoRefs.length === 0) {
throw new Error("Reference-to-video requires at least one --reference-video-url.");
}
return explicit;
}
export function normalizeSeconds(value = DEFAULT_SECONDS, mode = "text") {
const seconds = Number(value);
if (seconds === -1 && mode === "reference") return seconds;
if (!Number.isInteger(seconds) || seconds < MIN_SECONDS || seconds > MAX_SECONDS) {
throw new Error(`Unsupported duration "${value}". Use an integer from ${MIN_SECONDS} to ${MAX_SECONDS}.`);
}
return seconds;
}
export function normalizeResolution(value, mode = "text") {
const supported = SUPPORTED_RESOLUTIONS_BY_MODE[mode];
if (!supported) throw new Error(`Unsupported mode "${mode}" for resolution validation.`);
const fallback = DEFAULT_RESOLUTIONS[mode];
const resolution = String(value ?? fallback).trim().toLowerCase();
if (!supported.has(resolution)) {
throw new Error(`Unsupported resolution "${value}" for ${mode} mode. Use one of: ${Array.from(supported).join(", ")}.`);
}
return resolution;
}
export function normalizeRatio(value = DEFAULT_RATIO, mode = "text") {
const ratio = String(value ?? DEFAULT_RATIO).trim();
if (!SUPPORTED_RATIOS.has(ratio)) {
throw new Error(`Unsupported ratio "${value}". Use one of: ${Array.from(SUPPORTED_RATIOS).join(", ")}.`);
}
if (mode === "image" && ratio !== "adaptive") {
throw new Error('Seedance 2.5 image-to-video follows the first frame. Use --ratio adaptive.');
}
return ratio;
}
export function normalizeOutputFormat(value = "mp4") {
const format = String(value ?? "mp4").trim().toLowerCase();
if (!SUPPORTED_OUTPUT_FORMATS.has(format)) {
throw new Error(`Unsupported output format "${value}". Use mp4 or mov.`);
}
return format;
}
export function normalizeTimeoutMinutes(value = DEFAULT_TIMEOUT_MINUTES) {
const minutes = Number(value);
if (!Number.isInteger(minutes) || minutes < MIN_TIMEOUT_MINUTES || minutes > MAX_TIMEOUT_MINUTES) {
throw new Error(`Unsupported timeout "${value}". Use ${MIN_TIMEOUT_MINUTES}-${MAX_TIMEOUT_MINUTES} minutes.`);
}
return minutes;
}
export function normalizeStorage(value = DEFAULT_STORAGE) {
const storage = String(value ?? "").trim().toLowerCase();
if (!SUPPORTED_STORAGE.has(storage)) {
throw new Error(`Unsupported storage "${value}". Use temp or persistent.`);
}
return storage;
}
export function normalizeBoolean(value, name) {
if (typeof value === "boolean") return value;
if (value === "true" || value === "1") return true;
if (value === "false" || value === "0") return false;
throw new Error(`${name} must be true or false.`);
}
export function normalizeList(value) {
if (value === undefined || value === null || value === "") return [];
const list = Array.isArray(value) ? value : [value];
return list.map(cleanMedia).filter(Boolean);
}
function cleanMedia(value) {
return String(value ?? "").trim();
}
function validateTimedReferences(label, urls, durations) {
if (urls.length === 0) {
if (normalizeList(durations).length) throw new Error(`${label} durations were provided without ${label} URLs.`);
return;
}
const rawDurations = Array.isArray(durations) ? durations : (durations === undefined ? [] : [durations]);
if (rawDurations.length === 0) return;
if (rawDurations.length !== urls.length) {
throw new Error(`Provide one --${label.replaceAll(" ", "-")}-duration for each --${label.replaceAll(" ", "-")}-url.`);
}
const normalized = rawDurations.map(Number);
if (normalized.some((duration) => !Number.isFinite(duration) || duration < MIN_REFERENCE_MEDIA_SECONDS || duration > MAX_REFERENCE_MEDIA_SECONDS)) {
throw new Error(`Each ${label} must be ${MIN_REFERENCE_MEDIA_SECONDS}-${MAX_REFERENCE_MEDIA_SECONDS} seconds.`);
}
const total = normalized.reduce((sum, duration) => sum + duration, 0);
if (total > MAX_REFERENCE_MEDIA_TOTAL_SECONDS) {
throw new Error(`${label} total duration must not exceed ${MAX_REFERENCE_MEDIA_TOTAL_SECONDS} seconds.`);
}
}
export function normalizeMediaOptions(options = {}, mode = resolveMode(options)) {
const firstFrameUrl = cleanMedia(options.firstFrameUrl || options.inputReference);
const lastFrameUrl = cleanMedia(options.lastFrameUrl);
const referenceImageUrls = normalizeList(options.referenceImageUrls);
const referenceVideoUrls = normalizeList(options.referenceVideoUrls);
const referenceAudioUrls = normalizeList(options.referenceAudioUrls);
if (lastFrameUrl && !firstFrameUrl) {
throw new Error("Seedance 2.5 last-frame mode requires --first-frame-url.");
}
if (referenceImageUrls.length > MAX_REFERENCE_IMAGES) {
throw new Error(`Seedance 2.5 accepts at most ${MAX_REFERENCE_IMAGES} reference images.`);
}
if (referenceVideoUrls.length > MAX_REFERENCE_VIDEOS) {
throw new Error(`Seedance 2.5 accepts at most ${MAX_REFERENCE_VIDEOS} reference videos.`);
}
if (referenceAudioUrls.length > MAX_REFERENCE_AUDIO) {
throw new Error(`Seedance 2.5 accepts at most ${MAX_REFERENCE_AUDIO} reference audio clips.`);
}
if (mode === "reference" && referenceVideoUrls.length === 0) {
throw new Error("Reference-to-video requires at least one reference video.");
}
if (mode === "reference" && (firstFrameUrl || lastFrameUrl)) {
throw new Error("Reference-to-video does not accept first/last-frame fields.");
}
if (mode === "reference" && referenceAudioUrls.length > 0 && referenceVideoUrls.length === 0) {
throw new Error("Reference audio must be provided together with at least one reference video.");
}
if (firstFrameUrl) validateMediaUrl(firstFrameUrl, "first_frame_url", "image", true);
if (lastFrameUrl) validateMediaUrl(lastFrameUrl, "last_frame_url", "image");
for (const url of referenceImageUrls) validateMediaUrl(url, "reference_image_urls", "image");
for (const url of referenceVideoUrls) validateMediaUrl(url, "reference_video_urls", "video");
for (const url of referenceAudioUrls) validateMediaUrl(url, "reference_audio_urls", "audio");
validateTimedReferences("reference video", referenceVideoUrls, options.referenceVideoDurations);
validateTimedReferences("reference audio", referenceAudioUrls, options.referenceAudioDurations);
return { firstFrameUrl, lastFrameUrl, referenceImageUrls, referenceVideoUrls, referenceAudioUrls };
}
function validateMediaUrl(value, field, kind, allowAsset = false) {
if (allowAsset && /^asset:\/\/[A-Za-z0-9][A-Za-z0-9._:/-]{0,511}$/.test(value)) return;
if (kind === "image" && value.startsWith("data:")) {
if (!/^data:image\/(?:jpeg|png|webp|bmp|tiff|gif);base64,/i.test(value)) throw new Error(`${field} supports JPEG, PNG, WebP, BMP, TIFF and GIF data URLs only.`);
return;
}
let url;
try { url = new URL(value); } catch { throw new Error(`${field} must be a media URL.`); }
if (!(kind === "video" ? ["https:"] : ["http:", "https:"]).includes(url.protocol) || url.username || url.password || (kind === "video" && url.port)) {
throw new Error(`${field} requires a ${kind === "video" ? "public HTTPS" : "HTTP(S)"} URL; asset IDs are supported only for first_frame_url.`);
}
if (kind === "image" && /\.(svg|heic|heif)$/i.test(url.pathname)) throw new Error(`${field} does not support SVG, HEIC or HEIF.`);
}
export function buildVideoPayload(options = {}) {
const prompt = String(options.prompt || "").trim();
if (!prompt) throw new Error("A prompt is required for a new Seedance 2.5 task.");
const mode = resolveMode(options);
const media = normalizeMediaOptions(options, mode);
const input = {
prompt,
duration: normalizeSeconds(options.seconds, mode),
resolution: normalizeResolution(options.resolution, mode),
aspect_ratio: normalizeRatio(options.ratio, mode),
output_format: normalizeOutputFormat(options.outputFormat),
};
if (options.generateAudio !== undefined) input.generate_audio = normalizeBoolean(options.generateAudio, "generate_audio");
if (options.webSearch !== undefined) input.web_search = normalizeBoolean(options.webSearch, "web_search");
if (options.watermark !== undefined) {
if (mode === "reference") throw new Error("The current reference-to-video contract does not accept watermark.");
input.watermark = normalizeBoolean(options.watermark, "watermark");
}
if (media.firstFrameUrl) input.first_frame_url = media.firstFrameUrl;
if (media.lastFrameUrl) input.last_frame_url = media.lastFrameUrl;
if (media.referenceImageUrls.length) input.reference_image_urls = media.referenceImageUrls;
if (media.referenceVideoUrls.length) input.reference_video_urls = media.referenceVideoUrls;
if (media.referenceAudioUrls.length) input.reference_audio_urls = media.referenceAudioUrls;
const payload = { model: MODELS[mode], input };
const storage = normalizeStorage(options.storage);
if (storage === "persistent") {
if (!options.acceptStorageCost) {
throw new Error('Persistent storage is billed. Re-run with --accept-storage-cost after reviewing https://docs.hiapi.ai/storage/.');
}
payload.storage = "persistent";
}
if (options.callbackUrl) {
let callbackUrl;
try { callbackUrl = new URL(String(options.callbackUrl).trim()); } catch { throw new Error("callback.url must be a valid HTTPS URL."); }
if (callbackUrl.protocol !== "https:" || callbackUrl.username || callbackUrl.password) throw new Error("callback.url must be a valid HTTPS URL without embedded credentials.");
payload.callback = { url: String(options.callbackUrl).trim(), when: "final" };
}
return payload;
}
export function redactPayload(payload) {
const clone = structuredClone(payload);
const input = clone.input || {};
for (const field of ["first_frame_url", "last_frame_url"]) {
if (String(input[field] || "").startsWith("data:")) input[field] = `[data-uri:${input[field].length} chars]`;
}
for (const field of ["reference_image_urls", "reference_video_urls", "reference_audio_urls"]) {
if (Array.isArray(input[field])) {
input[field] = input[field].map((value) => String(value).startsWith("data:") ? `[data-uri:${value.length} chars]` : value);
}
}
return clone;
}
export async function requestJson(url, options = {}, fetchImpl = fetch) {
let response;
try {
response = await fetchImpl(url, options);
} catch (cause) {
const error = new Error(`Network request failed: ${cause?.message || cause}`);
error.cause = cause;
throw error;
}
const text = await response.text();
let body = null;
try { body = text ? JSON.parse(text) : null; } catch { body = text; }
if (!response.ok) {
const error = new Error(buildHttpErrorMessage(response.status, body));
error.httpStatus = response.status;
error.httpResponse = body;
throw error;
}
return body;
}
export function buildHttpErrorMessage(status, body) {
const summary = summarizeErrorBody(body);
const prefix = `HiAPI request failed with HTTP ${status}: ${summary}`;
const lower = summary.toLowerCase();
if (status === 401 || (status === 403 && !/(quota|credit|balance|payment)/i.test(lower))) {
return `${prefix}\nCheck HIAPI_API_KEY at ${HIAPI_API_KEYS_URL}.`;
}
if (status === 402 || /(quota|credit|balance|payment|insufficient)/i.test(lower)) {
return `${prefix}\nCheck balance at ${HIAPI_DASHBOARD_URL} and pricing at ${HIAPI_PRICING_URL}.`;
}
if (status === 400 || lower.includes("invalid")) {
return `${prefix}\nRun --dry-run --estimate and check the selected mode, 4-30s duration (or -1 in reference mode), mode-specific resolution, media counts, formats, sizes, and reference durations.`;
}
if (status === 429) return `${prefix}\nWait and retry, or reduce concurrent video tasks.`;
return prefix;
}
export function extractTaskId(response) {
return response?.data?.taskId || response?.data?.task_id || response?.taskId || response?.task_id || null;
}
export function extractStatus(response) {
return String(response?.data?.status || response?.status || "").toLowerCase();
}
export function isTerminalFailureStatus(status) {
return TERMINAL_FAILURES.has(String(status || "").toLowerCase());
}
export function extractTaskFailureSummary(response) {
return summarizeErrorBody(response?.data?.error || response?.error || response?.data?.message || response?.message || response);
}
export function extractVideoUrl(response) {
const output = response?.data?.output || response?.output;
if (Array.isArray(output)) {
const item = output.find((entry) => {
const url = typeof entry === "string" ? entry : entry?.url;
const type = typeof entry === "object" ? String(entry?.type || "").toLowerCase() : "";
return type === "video" || /\.(?:mp4|mov|webm)(?:\?|#|$)/i.test(String(url || ""));
});
if (typeof item === "string") return item;
if (item?.url) return item.url;
}
return response?.data?.video_url || response?.video_url || response?.data?.url || response?.url || response?.metadata?.url || null;
}
export async function createVideoTask(payload, config = resolveConfig(), options = {}) {
await warnOrRequireSkillUpdate({ fetchImpl: options.fetchImpl || fetch });
const idempotencyKey = String(options.idempotencyKey || randomUUID()).trim();
const headers = {
Authorization: `Bearer ${config.apiKey}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
};
const response = await requestJson(`${config.baseUrl}/v1/tasks`, {
method: "POST",
headers,
body: JSON.stringify(payload),
}, options.fetchImpl || fetch);
const taskId = extractTaskId(response);
if (!taskId) throw new Error("HiAPI accepted the request but did not return a task ID.");
return { taskId, idempotencyKey, response };
}
export async function getTask(taskId, config = resolveConfig(), fetchImpl = fetch) {
return requestJson(`${config.baseUrl}/v1/tasks/${encodeURIComponent(taskId)}`, {
headers: { Authorization: `Bearer ${config.apiKey}`, Accept: "application/json" },
}, fetchImpl);
}
export async function waitForVideo(taskId, config = resolveConfig(), options = {}) {
const timeoutMs = normalizeTimeoutMinutes(options.timeoutMinutes) * 60_000;
const pollIntervalMs = Number(options.pollIntervalMs ?? POLL_INTERVAL_MS);
const deadline = Date.now() + timeoutMs;
let transientFailures = 0;
while (Date.now() < deadline) {
let response;
try {
response = await getTask(taskId, config, options.fetchImpl || fetch);
transientFailures = 0;
} catch (error) {
if (![429, 500, 502, 503, 504].includes(error.httpStatus) && !error.message.startsWith("Network request failed")) throw error;
transientFailures += 1;
const delay = Math.min(pollIntervalMs * (2 ** Math.min(transientFailures, 3)), 30_000);
await sleep(delay);
continue;
}
const status = extractStatus(response);
const videoUrl = extractVideoUrl(response);
if (status === "success" && videoUrl) return { response, videoUrl };
if (isTerminalFailureStatus(status)) {
throw new Error(`Video generation failed: ${extractTaskFailureSummary(response)}`);
}
await sleep(pollIntervalMs);
}
throw new Error(`Video generation timed out after ${normalizeTimeoutMinutes(options.timeoutMinutes)} minutes. Task ${taskId} may still be running; resume it with --resume-task-id ${taskId}.`);
}
export async function saveVideoOutput(videoUrl, outputDir = DEFAULT_OUTPUT_DIR, options = {}) {
if (!videoUrl || !/^https?:\/\//i.test(videoUrl)) return null;
let response;
try { response = await (options.fetchImpl || fetch)(videoUrl); } catch { return null; }
if (!response.ok) return null;
const bytes = new Uint8Array(await response.arrayBuffer());
const contentType = response.headers.get("content-type") || "";
const urlExtension = extname(new URL(videoUrl).pathname).toLowerCase();
const extension = urlExtension === ".mov" || /quicktime/i.test(contentType) ? ".mov" : ".mp4";
const directory = resolve(outputDir);
await mkdir(directory, { recursive: true });
const filename = `seedance-2-5-${timestamp()}${extension}`;
const path = join(directory, filename);
await writeFile(path, bytes);
return path;
}
export async function generateVideo(options = {}, config = resolveConfig()) {
let taskId = String(options.resumeTaskId || "").trim();
let idempotencyKey = options.idempotencyKey ? String(options.idempotencyKey).trim() : null;
let model = null;
let payload = null;
if (!taskId) {
payload = buildVideoPayload(options);
model = payload.model;
idempotencyKey ||= randomUUID();
console.error(`HiAPI idempotency key: ${idempotencyKey}`);
let created;
try {
created = await createVideoTask(payload, config, { idempotencyKey, fetchImpl: options.fetchImpl });
} catch (error) {
if (error.message.startsWith("Network request failed")) {
throw new Error(`${error.message}\nSubmission acceptance is unknown. Do not create a new paid task blindly; retry with --idempotency-key ${idempotencyKey}.`);
}
throw error;
}
taskId = created.taskId;
console.error(`HiAPI task created: ${taskId}`);
} else {
console.error(`Resuming HiAPI task: ${taskId}`);
}
if (options.wait === false) return { ok: true, taskId, model, idempotencyKey, status: "submitted" };
const finished = await waitForVideo(taskId, config, options);
model ||= finished.response?.data?.model || finished.response?.model || null;
const path = options.save === false ? null : await saveVideoOutput(finished.videoUrl, options.outputDir, options);
return {
ok: true,
taskId,
model,
idempotencyKey,
status: "success",
output: path
? { kind: "file", path, value: path, sourceUrl: finished.videoUrl }
: { kind: "url", value: finished.videoUrl },
};
}
export async function fetchPricingEstimate(payload, options = {}) {
const siteUrl = (options.siteUrl || process.env.HIAPI_SITE_URL || DEFAULT_SITE_URL).replace(/\/+$/, "");
const response = await (options.fetchImpl || fetch)(`${siteUrl}/api/pricing`, { headers: { Accept: "application/json" } });
if (!response.ok) throw new Error(`Pricing check failed with HTTP ${response.status}.`);
const body = await response.json();
const model = body?.data?.find((entry) => entry?.model_name === payload.model);
if (!model) throw new Error(`Current public pricing does not list ${payload.model}.`);
const matchingPolicy = (model.policies || []).find((policy) => policyMatches(policy.rule, payload.input));
const unitUsd = Number(matchingPolicy?.usd_value ?? model.base_usd_value);
if (!Number.isFinite(unitUsd)) throw new Error(`Pricing for ${payload.model} is not a numeric per-second rate.`);
const duration = Number(payload.input.duration);
const referenceMode = payload.model === MODELS.reference;
const referenceDurations = options.referenceVideoDurations === undefined ? [] : (Array.isArray(options.referenceVideoDurations) ? options.referenceVideoDurations : [options.referenceVideoDurations]);
if (referenceMode) validateTimedReferences("reference video", payload.input.reference_video_urls, referenceDurations);
const referenceSeconds = referenceMode && referenceDurations?.length ? referenceDurations.map(Number).reduce((a, b) => a + b, 0) : null;
const minimumReferenceSeconds = referenceSeconds ?? (payload.input.reference_video_urls?.length || 0) * MIN_REFERENCE_MEDIA_SECONDS;
const maximumReferenceSeconds = referenceSeconds ?? MAX_REFERENCE_MEDIA_TOTAL_SECONDS;
const totalSeconds = referenceMode ? (duration === -1 || referenceSeconds === null ? null : referenceSeconds + duration) : duration;
return {
model: payload.model,
resolution: payload.input.resolution,
duration,
unitUsd,
referenceSeconds,
estimatedUsd: totalSeconds === null ? null : Number((unitUsd * totalSeconds).toFixed(4)),
...(referenceMode && totalSeconds === null ? { estimatedUsdRange: {
minimum: Number((unitUsd * (minimumReferenceSeconds + (duration === -1 ? MIN_SECONDS : duration))).toFixed(4)),
maximum: Number((unitUsd * (maximumReferenceSeconds + (duration === -1 ? MAX_SECONDS : duration))).toFixed(4)),
} } : {}),
billingBasis: referenceMode ? "reference-video duration + output-video duration" : "requested output duration",
billingUnit: model.base_display_unit?.en || "per second",
pricingPage: HIAPI_PRICING_URL,
note: referenceMode ? "Reference durations supplied to the CLI are estimates only. Final billing uses server-verified reference duration plus output duration; automatic output length is unknown before completion." : "Estimate from the current public pricing endpoint; final billing follows the accepted task parameters.",
};
}
function policyMatches(rule, input) {
return Object.entries(rule || {}).every(([field, condition]) => {
if (Object.hasOwn(condition || {}, "match")) return input[field] === condition.match;
if (condition?.with === true) return input[field] !== undefined && input[field] !== null;
return false;
});
}
export async function checkLiveContract(options = {}) {
const siteUrl = (options.siteUrl || process.env.HIAPI_SITE_URL || DEFAULT_SITE_URL).replace(/\/+$/, "");
const fetchImpl = options.fetchImpl || fetch;
const expected = {
[MODELS.text]: {
required: ["prompt", "model"],
properties: ["prompt", "model", "duration", "resolution", "aspect_ratio", "generate_audio", "output_format", "watermark", "web_search"],
ratios: [...SUPPORTED_RATIOS],
resolutions: [...SUPPORTED_RESOLUTIONS_BY_MODE.text],
defaultResolution: DEFAULT_RESOLUTIONS.text,
},
[MODELS.image]: {
required: ["prompt", "model"],
properties: ["prompt", "model", "duration", "resolution", "aspect_ratio", "generate_audio", "output_format", "watermark", "web_search", "first_frame_url", "last_frame_url", "reference_image_urls", "reference_audio_urls"],
ratios: ["adaptive"],
resolutions: [...SUPPORTED_RESOLUTIONS_BY_MODE.image],
defaultResolution: DEFAULT_RESOLUTIONS.image,
maxItems: { reference_image_urls: MAX_REFERENCE_IMAGES, reference_audio_urls: MAX_REFERENCE_AUDIO },
},
[MODELS.reference]: {
required: ["prompt", "reference_video_urls", "model"],
properties: ["prompt", "model", "duration", "resolution", "aspect_ratio", "generate_audio", "output_format", "web_search", "reference_video_urls", "reference_image_urls", "reference_audio_urls"],
ratios: [...SUPPORTED_RATIOS],
resolutions: [...SUPPORTED_RESOLUTIONS_BY_MODE.reference],
defaultResolution: DEFAULT_RESOLUTIONS.reference,
maxItems: { reference_video_urls: MAX_REFERENCE_VIDEOS, reference_image_urls: MAX_REFERENCE_IMAGES, reference_audio_urls: MAX_REFERENCE_AUDIO },
},
};
const checks = [];
for (const [model, contract] of Object.entries(expected)) {
const response = await fetchImpl(`${siteUrl}/api/models/content?name=${encodeURIComponent(model)}`, { headers: { Accept: "application/json" } });
if (!response.ok) throw new Error(`Contract check failed for ${model}: HTTP ${response.status}.`);
const body = await response.json();
const schema = body?.data?.input_schema || body?.data?.param_schema;
if (!schema) throw new Error(`Contract check failed for ${model}: public schema missing.`);
const missingRequired = contract.required.filter((field) => !(schema.required || []).includes(field));
const missingProperties = contract.properties.filter((field) => !Object.hasOwn(schema.properties || {}, field));
const duration = schema.properties?.duration || {};
const resolutions = schema.properties?.resolution?.enum || [];
const ratios = schema.properties?.aspect_ratio?.enum || [];
const outputFormats = schema.properties?.output_format?.enum || [];
const itemLimitMismatches = Object.entries(contract.maxItems || {})
.filter(([field, maximum]) => schema.properties?.[field]?.maxItems !== maximum)
.map(([field, maximum]) => ({ field, expected: maximum, actual: schema.properties?.[field]?.maxItems }));
const missingRatios = contract.ratios.filter((value) => !ratios.includes(value));
const ok = missingRequired.length === 0
&& missingProperties.length === 0
&& (model === MODELS.reference
? Array.isArray(duration.enum) && duration.enum.length === 28 && [-1, ...Array.from({ length: 27 }, (_, i) => i + 4)].every((value) => duration.enum.includes(value))
: duration.minimum === MIN_SECONDS && duration.maximum === MAX_SECONDS)
&& duration.default === DEFAULT_SECONDS
&& (schema.required || []).length === contract.required.length
&& Object.keys(schema.properties || {}).length === contract.properties.length
&& contract.resolutions.length === resolutions.length
&& contract.resolutions.every((value) => resolutions.includes(value))
&& schema.properties?.resolution?.default === contract.defaultResolution
&& ratios.length === contract.ratios.length
&& missingRatios.length === 0
&& SUPPORTED_OUTPUT_FORMATS.size === outputFormats.length
&& [...SUPPORTED_OUTPUT_FORMATS].every((value) => outputFormats.includes(value))
&& itemLimitMismatches.length === 0
&& (model !== MODELS.reference || schema.properties?.reference_video_urls?.minItems === 1);
checks.push({
model,
ok,
missingRequired,
missingProperties,
duration: duration.enum || [duration.minimum, duration.maximum],
resolutions,
resolutionDefault: schema.properties?.resolution?.default,
ratios,
outputFormats,
itemLimitMismatches,
});
}
return { ok: checks.every((check) => check.ok), checkedAt: new Date().toISOString(), checks };
}
export async function checkSkillUpdate(options = {}) {
const env = options.env || process.env;
if (["1", "true"].includes(String(env.HIAPI_SKIP_UPDATE_CHECK || "").toLowerCase())) return { status: "unverified", message: `Version verification is disabled. New paid tasks require the latest skill. Enable update checks and run: ${UPDATE_COMMAND}` };
const urls = options.manifestUrls || [
env.HIAPI_SKILLS_MANIFEST_URL || DEFAULT_SKILLS_MANIFEST_URL,
env.HIAPI_SKILL_POLICY_URL || DEFAULT_REPOSITORY_POLICY_URL,
];
for (const url of urls) {
const manifest = await fetchManifest(url, options);
if (!manifest) continue;
const skill = Array.isArray(manifest.skills)
? manifest.skills.find((entry) => entry?.id === (options.skillId || SKILL_ID))
: (manifest.id === (options.skillId || SKILL_ID) ? manifest : null);
if (!skill?.updatePolicy) continue;
const { latestVersion, minimumVersion } = skill.updatePolicy;
if (![latestVersion, minimumVersion].every((value) => typeof value === "string" && /^\d+\.\d+\.\d+$/.test(value)) || compareVersions(latestVersion, minimumVersion) < 0) continue;
return evaluateUpdatePolicy(skill, options.currentVersion || SKILL_VERSION);
}
return { status: "unverified", message: `Could not verify the latest skill version. No paid task was created. Restore access to the update sources and retry; existing task recovery remains available. Update: ${UPDATE_COMMAND}` };
}
async function fetchManifest(url, options) {
const controller = typeof AbortController === "function" ? new AbortController() : null;
const timer = controller ? setTimeout(() => controller.abort(), options.timeoutMs || 5_000) : null;
try {
const response = await (options.fetchImpl || fetch)(url, { headers: { Accept: "application/json" }, signal: controller?.signal });
if (!response.ok) return null;
return await response.json();
} catch { return null; } finally { if (timer) clearTimeout(timer); }
}
function evaluateUpdatePolicy(skill, currentVersion) {
const policy = skill.updatePolicy;
const minimumVersion = policy.minimumVersion || skill.version || currentVersion;
const latestVersion = policy.latestVersion || skill.version || minimumVersion;
const updateCommand = policy.updateCommand || UPDATE_COMMAND;
if (compareVersions(currentVersion, minimumVersion) < 0) {
return {
status: "required", latestVersion, minimumVersion, updateCommand,
message: `${policy.requiredNotice || "This skill version is incompatible with the current API."}\nInstalled: ${currentVersion}; required: ${minimumVersion}.\nUpdate now: ${updateCommand}`,
};
}
if (compareVersions(currentVersion, latestVersion) < 0) {
return {
status: "available", latestVersion, minimumVersion, updateCommand,
message: `${policy.notice || "A newer skill version is available."}\nInstalled: ${currentVersion}; latest: ${latestVersion}.\nUpdate: ${updateCommand}`,
};
}
return { status: "current", latestVersion, minimumVersion, updateCommand };
}
export async function warnOrRequireSkillUpdate(options = {}) {
const result = await checkSkillUpdate(options);
if (["required", "available", "unverified"].includes(result.status) && !options.allowRecovery) throw new Error(result.message);
if (["required", "available", "unverified"].includes(result.status) && result.message) console.error(result.message);
return result;
}
export function compareVersions(left, right) {
const parse = (value) => String(value || "0.0.0").split(/[+-]/, 1)[0].split(".").map((part) => Number.parseInt(part, 10) || 0);
const a = parse(left); const b = parse(right);
for (let index = 0; index < Math.max(a.length, b.length, 3); index += 1) {
const delta = (a[index] || 0) - (b[index] || 0);
if (delta) return delta > 0 ? 1 : -1;
}
return 0;
}
export function parseArgs(argv) {
const options = {};
const repeatable = new Map([
["--reference-image-url", "referenceImageUrls"],
["--reference-video-url", "referenceVideoUrls"],
["--reference-audio-url", "referenceAudioUrls"],
["--reference-video-duration", "referenceVideoDurations"],
["--reference-audio-duration", "referenceAudioDurations"],
]);
const values = new Map([
["--prompt", "prompt"], ["--mode", "mode"], ["--model", "model"], ["--seconds", "seconds"], ["--duration", "seconds"], ["--resolution", "resolution"],
["--ratio", "ratio"], ["--aspect-ratio", "ratio"], ["--output-format", "outputFormat"], ["--input-reference", "inputReference"],
["--first-frame-url", "firstFrameUrl"], ["--last-frame-url", "lastFrameUrl"], ["--output-dir", "outputDir"],
["--timeout-minutes", "timeoutMinutes"], ["--storage", "storage"], ["--callback-url", "callbackUrl"],
["--resume-task-id", "resumeTaskId"], ["--idempotency-key", "idempotencyKey"],
]);
for (let index = 0; index < argv.length; index += 1) {
const arg = argv[index];
if (arg === "--help" || arg === "-h") options.help = true;
else if (arg === "--dry-run") options.dryRun = true;
else if (arg === "--estimate") options.estimate = true;
else if (arg === "--check-contract") options.checkContract = true;
else if (arg === "--generate-audio") options.generateAudio = true;
else if (arg === "--no-audio" || arg === "--no-generate-audio") options.generateAudio = false;
else if (arg === "--web-search") options.webSearch = true;
else if (arg === "--no-web-search") options.webSearch = false;
else if (arg === "--watermark") options.watermark = true;
else if (arg === "--no-watermark") options.watermark = false;
else if (arg === "--no-save") options.save = false;
else if (arg === "--no-wait") options.wait = false;
else if (arg === "--accept-storage-cost") options.acceptStorageCost = true;
else if (repeatable.has(arg)) {
const key = repeatable.get(arg); const next = argv[++index];
if (next === undefined) throw new Error(`${arg} requires a value.`);
(options[key] ||= []).push(next);
} else if (values.has(arg)) {
const key = values.get(arg); const next = argv[++index];
if (next === undefined) throw new Error(`${arg} requires a value.`);
options[key] = next;
} else throw new Error(`Unknown argument: ${arg}`);
}
if (options.resumeTaskId && (options.dryRun || options.estimate || options.checkContract)) {
throw new Error("--resume-task-id cannot be combined with --dry-run, --estimate, or --check-contract.");
}
return options;
}
export function usage() {
return `HiAPI Seedance 2.5 video skill
Preflight (no paid task):
node scripts/hiapi-seedance-2-video.mjs --prompt "..." --seconds 5 --resolution 720p --dry-run --estimate
Create and wait:
node scripts/hiapi-seedance-2-video.mjs --prompt "..." --seconds 5 --resolution 720p
Recover an existing paid task (does not create another task):
node scripts/hiapi-seedance-2-video.mjs --resume-task-id <task-id>
Core options:
--mode <text|image|reference> Usually inferred from media inputs
--prompt <text> Required for new tasks
--model <exact-model-id> Alternative to --mode
--seconds, --duration <-1|4-30> Default: 5; -1 is reference mode only
--resolution <480p|720p|1080p> Text/image: 720p or 1080p (default 720p); reference: 480p, 720p, or 1080p (default 480p)
--ratio <16:9|4:3|1:1|3:4|9:16|21:9|adaptive> Default: adaptive
--output-format <mp4|mov> Default: mp4
--first-frame-url <url> Selects image-to-video
--last-frame-url <url> Requires first frame
--reference-image-url <url> Repeatable; max 30
--reference-video-url <url> Repeatable; max 10; selects reference-to-video
--reference-video-duration <2-30> Optional estimate metadata; if supplied, one per video; total <= 30s
--reference-audio-url <url> Repeatable; max 10
--reference-audio-duration <2-30> Optional local metadata; if supplied, one per audio; total <= 30s
--generate-audio | --no-audio API default: audio on
--web-search | --no-web-search Set web grounding explicitly
--watermark | --no-watermark Text/image modes only
--dry-run Validate and print a redacted payload; no paid task
--estimate Fetch current public per-second pricing
--check-contract Compare this skill with live public schemas
--idempotency-key <key> Reuse after an ambiguous submit failure
--resume-task-id <task-id> Poll/download an existing task without resubmitting
--no-wait Return immediately after task creation
--timeout-minutes <1-180> Default: 120
--output-dir <path> Default: outputs
--no-save Return the remote URL without downloading
--callback-url <https-url> Add a final-state callback
--storage <temp|persistent> Persistent storage is billed
--accept-storage-cost Required with persistent storage
`;
}
function summarizeErrorBody(body) {
if (!body) return "Unknown error";
if (typeof body === "string") return body;
return body?.error?.message || body?.message || body?.error || body?.detail || JSON.stringify(body);
}
function timestamp() {
return new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "").replace("T", "-");
}
function sleep(ms) { return new Promise((resolveSleep) => setTimeout(resolveSleep, ms)); }
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |