@birdapi/velinstyle-motion

Velin Motion Clip Pipeline — image → short motion clip.

• Local (default): CSS / Web Animations HTML clips — free, offline, reproducible
• AI (optional): pluggable providers — first partner: PixVerse (credits + API key)

This package is separate from the DOM Motion Design System (@birdapi/velinstyle/motion / core/motion).

Ship with @birdapi/[email protected] (export @birdapi/velinstyle/motion-clip).

CLI (via VelinStyle)

velinstyle motion providers
velinstyle motion setup pixverse
velinstyle motion create atelier.webp
velinstyle motion create hero.png --preset cinematic --yes
velinstyle motion create logo.png --ai --yes   # needs PIXVERSE_API_KEY; dry: VELIN_MOTION_DRY_RUN=1
velinstyle motion atelier ./assets --count 10 --preset atelier --yes
velinstyle motion transition a.webp b.webp --yes
velinstyle motion sequence 01.webp 02.webp 03.webp --provider pixverse --yes
velinstyle motion usage                 # local job stats + live PixVerse balance (if key set)
velinstyle motion setup pixverse --yes  # connection + credit totals via GET /account/balance

PixVerse partner

PixVerse is an external AI video platform. VelinStyle does not sell credits and does not host PixVerse.

| | | |--|--| | Setup | velinstyle motion setup pixverse — open PixVerse account · copy account link · enter API key | | Account | PixVerse account | | API docs | https://docs.platform.pixverse.ai/ | | Live balance | GET /openapi/v2/account/balance → credit_monthly + credit_package (shown by motion usage / setup) | | Site guide | https://velinstyle.info/docs/guides/pixverse.html |

You need a PixVerse account and API key. The CLI opens the account page (no bare platform.pixverse.ai bypass). If a tracker blocker blocks the open, use copy account link.

Config

.velin/motion/config.json
.velin/motion/.env          # PIXVERSE_API_KEY=… (gitignored via .velin/)

{
  "provider": "pixverse",
  "api_key": "${PIXVERSE_API_KEY}",
  "model": "v6",
  "quality": "720p",
  "default_duration": 5,
  "output_dir": "./motion-output",
  "pixverse": { "setup_completed": false }
}

Never store plaintext API keys in config.json. Prefer PIXVERSE_API_KEY env or .velin/motion/.env. Keys are never logged, printed in --json, or written to job manifests.

--yes + AI without a key → hard error (CI-safe). Affiliate browser opens only during explicit setup / first-time gate when setup_completed is false.

Image inputs: non-empty .webp / .png / .jpg / .jpeg with valid raster magic bytes.

Programmatic

import { createMotionClip, listClipPresets } from '@birdapi/velinstyle-motion';

await createMotionClip({
  image: 'atelier.webp',
  preset: 'soft-zoom',
  yes: true,
});

Providers

Add another backend under src/ai/providers/ and registerAiProvider(...).
PixVerse implements imageToVideo, transition, multiTransition (capabilities-driven).

Framework guide: docs/guides/velin-motion-clips.md