MotionGit API

These APIs prepare images, footage, stickers, music and narration for a .motion production. Use the verified bundled entry and the original downloader's account Key. No particular assistant is required, and a new template download does not issue a new Key automatically.

Start from the template

Read 00-START-HERE.md and assistant/guide.json, verify the helper against official HTTPS metadata, then run:

node assistant/motion.mjs start /original-personal.motion
node assistant/motion.mjs api /original-personal.motion status

New packages include templateApi in assistant/guide.json; existing packages receive current template_api_guide through usage. Keep the original credential inside the signed package. Do not extract it into the project, request a supplier Key or widen permissions automatically.

Requests and credits

Free existing images/footage, stickers and library music cost 0 credits, sharing 30 material requests per account per day across Keys and templates. The allowance resets at midnight Asia/Shanghai. Search, selection and file download count separately; reuse prepared material in the current instance. Usage, quote and task queries do not consume this free material allowance.

Read free_material_requests for the limit, remaining requests and reset time. A daily limit returns429; wait until reset rather than purchasing credits. Paid generation and TTS use the user's explicitly authorized credit budget. credits.remaining and Key daily/monthly credit budgets are independent of request counts. A zero credit balance does not block authorized free materials. A403 permission error is not a missing endpoint.

Plan only the material this production needs

Understand the output and supplied files, then read the selected workflow's actual inputs. Missing recordings do not mean no narration. Keep no narration, no presenter, no music and complete silence distinct. Reuse suitable files and ask only for unresolved output choices. Unreadable usage means unknown allowance, not denial of independently authorized free calls.

TTS 2.0 (tts.speak / volc-tts-2.0) and image generation (images.generate / current native-image) use quote → submit → task → receipt → download. Full requests are in templateApi.examples; read live fields, readiness and access. A quote or balance is not consent. Reuse explicit authorization when its capability list, per-call ceiling and remaining total cover the request.

Reconcile accepted or uncertain submissions using the original state/task before creating another operation, even after a quote expires. Preserve the old state and re-quote only after proving it was not accepted. Generation quoting still requires readable usage.models; explain this helper limitation without manual HTTP or expanding Key access.

Prepare and bind materials

node assistant/motion.mjs api /original-personal.motion search /instance/image-query.json
node assistant/motion.mjs api /original-personal.motion select src_result_reference
node assistant/motion.mjs api /original-personal.motion download ast_selected_id /instance/inputs/assets/photo.jpg
node assistant/motion.mjs api /original-personal.motion music-prepare /instance/music-request.json /instance/music-v1
node assistant/motion.mjs api /original-personal.motion voices en

Example image query: {"kind":"image","provider":"pexels","q":"keywords for this scene","limit":"3"}. Use kind=video for existing footage. Existing-image search is free; new AI image generation is paid. Never switch to paid generation merely because free search failed.

For TTS use voices, quote, submit, task, receipt and download; preserve the original operation/state after interruption. Read the template's public guide/schema and bind the actual files to its declared inputs. Inspect previews and encoded output; an API result alone is not a completed video.

HTTP clients

Authenticated HTTP calls use Authorization: Bearer <user MotionGit Key>. The server holds supplier credentials. Search, sticker downloads, music library calls, usage and quotes cost0 credits. POST /api/v1/generations uses the confirmed quote; closed services must not dispatch. Check current permissions, status and prices rather than historical examples.

Complete template material API guide · Music · Capabilities · API settings · OpenAPI

Match stickers to a scene

Use POST /api/v1/stickers/match with one scene's text, optional explicit keywords and limit1–50. The Key needs stickers.search and local-stickers permission; file delivery needs stickers.file. Version metadata-keywords-v2 returns extracted_keywords, excluded_keywords, reasons and ranking scores. It ignores common scene/presentation instructions and supports bounded Chinese/English exclusions. Explicit keywords take priority; complex negation and irony still require caller review. Check has_text and the actual animation before binding to the template. A false metadata flag does not establish the absence of outlined or baked-in lettering.

Known missing-image-dependent stickers are omitted from search/matching. Direct delivery returns503 sticker_dependencies_missing without consuming material requests. Downloads of already-paid generated assets and the user's uploads are independent of the30 daily free-library requests. Existing helpers without sticker match/file actions need an official helper update; never extract a package Key to work around a missing action.