HD70X/nxtpath-video

Nxtpath Image-to-Video (Antigravity)

Use this Skill's standalone Python client to generate video candidates. The default model is the already-tested seedance-2.5; the workflow does not depend on a specific project, other working trees, or deployment state.

Local Configuration and Execution Entry Point

• The single credential is NXTPATH_API_KEY, read by default from the environment variable or ~/.config/nxtpath/env. The environment variable takes precedence; NXTPATH_ENV_FILE can specify an alternate private configuration. Do not read chat tokens from other applications, and do not place the key into command lines, Skills, reports, or task records.
• New zsh processes load local configuration via ~/.zshenv; when GUI or old processes do not inherit the environment, the client can still read the aforementioned files directly. Only report whether configuration exists, do not display its content.
• Locate scripts/nxtpath_video.py from the currently loaded Skill directory. Prefer ~/.config/nxtpath/venv/bin/python; if it does not exist, HTTPS reference images and the video API can run directly with Python 3.9+. Local image hosting additionally requires boto3 from scripts/requirements.txt.
• In the target project, first read the applicable resource and privacy conventions. Tasks are placed by default in the project's ignored tmp/artwork/generations/<run-id>/<asset-id>/<attempt-id>/ directory; if there is no project, use the user-selected output directory. Do not overwrite old attempts, and do not automatically include candidates in the build or formal resources.

Creating One Shot or Resuming an Existing Task

When the user has explicitly requested the generation of a specific video, complete one candidate according to that request without repeatedly asking for generic confirmation. Asking about routes, configuration, or Skill usage does not authorize paid generation. Batch quantity, rework count, and cost range follow the user's agreement for this session; if not agreed, generate one first, and do not automatically expand or re-generate failed tasks.

1. Run doctor --check-api via run_command to verify credentials and available models. This is a read-only request that does not generate videos.
2. Confirm the reference image and action description (view local reference images first with read_file). Clarify action phase, shot, composition, duration, and any characters or props to be maintained. Default to 4 seconds / 480p for unspecified drafts; do not treat low-resolution defaults as final productions. Native frame rate, character consistency, starting/ending poses, and transparency are subject to the actual video.
3. Save the prompt as a UTF-8 file and use prepare to create immutable inputs. --reference can be repeated to pass local PNG/JPEG/WebP or HTTPS image URLs; these are ordinary guiding images and cannot claim the API locks the first and last keyframes. Text-to-video generation may omit reference images.
4. When local images exist, run host to upload or reuse input snapshots in the configured private R2 bucket, issue a 24-hour GET URL, and verify the download hash. This operation transmits reference images to the hosting service and the video provider; it should stay within the scope of the user-requested assets. Do not submit a video if hosting fails; do not automatically switch accounts, public buckets, or services. HTTPS reference images do not require host.
5. Run submit exactly once. It first persists an exclusive submission record, then issues a paid POST. Subsequently use independent status calls, and upon success use download to retrieve video.mp4; execute each command via run_command independently. Do not embed minute-long polling in a single long shell call, and never use shell sleep as a timer. When waiting is required, use schedule(DurationSeconds=...) to set a one-shot timer and end the current turn to await wake-up, then run status again. Do not re-generate a request due to timeout.
6. When resuming across conversations, use the original job path; first inspect, then status / download. For attempts with existing submissions, unknown results, or no task ID, do not repeat POST. When the task ID is missing, verify with the provider based on the private submission record. Only retry download upon download failure. Stop submission on 401/403, insufficient quota, or unavailable model, report the reason, and do not automatically switch keys, models, or endpoints.

Command examples (CLIENT refers to the actual script in the Skill; PY refers to the local Python; JOB is the new task directory for this run):

"$PY" "$CLIENT" doctor --check-api
"$PY" "$CLIENT" prepare --job "$JOB" --prompt-file "$PROMPT_FILE" --reference "$REFERENCE_IMAGE" --duration 4 --resolution 480p --ratio 1:1
"$PY" "$CLIENT" host --job "$JOB"
"$PY" "$CLIENT" submit --job "$JOB"
"$PY" "$CLIENT" status --job "$JOB"
"$PY" "$CLIENT" download --job "$JOB"

Delivery and Boundaries

Deliver as a playable local video and job path; display the video using [video.mp4](file:///absolute/path/to/video.mp4) link, and indicate that it is a candidate along with the actual content checked. When review of the final output is needed, directly use Antigravity's read_file tool to read the downloaded video.mp4 (natively supports multimodal video reading), checking original speed, key actions, and starting/ending poses. Do not equate HTTP success with motion or art approval.

Task records contain the prompt, input snapshots, exact request, provider task handle, result, and file hash. Permissions default to readable only by the current user; these records may contain temporary signed URLs and must not be pasted wholesale into chat or committed to Git. Show only the task handle fingerprint in the console.

Transparent background removal, SVG transitions, and app integration are subsequent tasks to be handled according to the target project's tools and authorization.

Only read Configuration and Failure Recovery when changing devices, updating credentials, or hosting fails. Interface reference: Provider Seedance Skill.