nexu-io/openmotion / skills/openmotion-media
openmotion-media
VerifiedGenerate, poll and inspect individual image, video, speech or music assets through openmotion_assets_use after openmotion_media_use discovery (configured Atlas Cloud, fal.ai, WaveSpeedAI or OpenDesign Cloud BYOK providers, or a signed-in OpenDesign account), either when delegated by an OpenMotion film workflow or for a standalone asset-generation request. Native-only tasks with no new speech or music stay outside generation unless explicitly requested. Not a whole-film entry point: creating, recreating, templating, editing or exporting a whole video belongs to the OpenMotion video entries.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.4 KB |
| agents/openai.yaml | config | 359 B |
| references/inspection.md | markdown | 5.5 KB |
| references/jobs.md | markdown | 8.5 KB |
| references/planning.md | markdown | 3.6 KB |
| references/providers/account.md | markdown | 8.0 KB |
| references/providers/atlascloud.md | markdown | 7.4 KB |
| references/providers/codex.md | markdown | 1.6 KB |
| references/providers/compatible.md | markdown | 6.4 KB |
| references/providers/fal.md | markdown | 8.3 KB |
| references/providers/opendesign.md | markdown | 14.3 KB |
| references/providers/wavespeed.md | markdown | 6.4 KB |
| references/setup.md | markdown | 3.1 KB |
references/jobs.md
View on GitHub# Submit and track media jobs
Read before submission or when resuming, recovering or regenerating a job. Apply the [entry authorization](../SKILL.md#provider-preference-and-authorization) before any paid request.
## Provider references
Call `action: "reference"` with the selected provider ID from `inspect`, or open that provider's guide below, and read only that guide for endpoint rules, supported modes and parameter schemas. Its request templates are `openmotion_assets_use` arguments; an existing project-direct job keeps its original route (step 5 below).
- [fal.ai](providers/fal.md)
- [Atlas Cloud](providers/atlascloud.md)
- [WaveSpeedAI](providers/wavespeed.md)
- [OpenDesign Cloud](providers/opendesign.md)
- [OpenDesign account](providers/account.md)
- [Registered compatible APIs](providers/compatible.md)
- [Local Codex images](providers/codex.md)
## Generate library assets and track the original job
1. Prefer `openmotion_assets_use` when it appears in `tools/list`. If only `openmotion_assets` is exposed, use its compatible asset actions; it has no `read`, so inspect adopted local files with `ffprobe`, extracted frames and available playback tools. Do not invoke an undiscovered name or silently fall back after a failed submission.
2. Submit `action: "generate"` with a deterministic `requestId` per distinct asset intent, the **full model ID** returned by discovery (for example `fal:fal-ai/flux/schnell`), `modality`, `prompt`, optional supported `mode` and provider-specific `parameters`. No project is required for generation or a standalone asset request. State concrete subject/action/framing/lighting/text-safe space, or exact spoken script and delivery/musical structure. For several **independent** approved assets (such as voice, music and unchained shots), submit them all before polling; because the local service runs a limited number of jobs in submission order, submit the assets most likely to fail or need rework first (several people, complex action, hands or legible text). Keep **dependent cross-shot chains** staged instead of blind parallel submission: lock and inspect the anchor image first; derive and visually verify shot-specific first frames (or extract the previous clip's handoff frame) before submitting dependent image-to-video jobs; once independent first frames pass inspection, submit their video jobs together. Do not submit unapproved extra paid image-edit jobs when the user's spend approval covers only the requested video clips.
3. For image editing, first `import` a local image into the library with a stable `requestId` and real absolute `sourcePath`. Pass `references: [{assetId, versionId}, ...]` in the order the prompt names them, no more than the model's `maxInputImages` (one when absent), and only to an image model advertising `supportsImageReference`. Set target `assetId` and `parentVersionId` to append a version while retaining the original; the parent alone is not a reference input. For image-to-video, pass one image reference to a video model whose discovery reports `maxInputImages`; it becomes the first frame. A video model without `maxInputImages` accepts no input image, and no current route sends first-and-last frames: explain the gap and offer text-to-video or a still animated with native Motion; do not invent reference support or send a local disk path as a remote URL. OpenDesign account and Cloud reference images must be PNG/JPEG/WebP under 2 MiB (other local adapters keep the 20 MB limit). An existing project-direct task keeps its own reference form: `openmotion_media_use` accepts one project-relative PNG/JPEG/WebP (under 2 MiB for OpenDesign account/Cloud, or under 20 MB for other local adapters) as top-level `referenceAsset` for a model with `supportsImageReference: true`, snapshots it when queued and never overwrites the source.
4. Use resume with the original jobId and a stable requestId to check a failed/interrupted Cloud task or account image task with a known remoteId, without uploading inputs or submitting another paid generation. Cancelled jobs and confirmed remote failures cannot resume. Use retry_save only for retained local outputs (savePending); regeneration is a separate paid request requiring authorization. Studio offers Check original task for Cloud jobs and Continue download for account images. Account image recovery reuses the original prompt/model and remote task; draft edits apply only to a new generation. Partial files resume only with verified asset identity, local checksum and strong ETag; otherwise the same image downloads from zero. Account video/audio recovery is not supported. Reference counts follow the selected model before any reference file is read; there is no fixed library count ceiling. Local Codex/account editing remains one image, video remains one first frame, and project referenceAsset remains image-only. Queued `job.id` is not finished media. Keep that original local `jobId` and poll `action: "status", jobId` through the same asset Tool until `completed`, `failed` or `cancelled`. `jobs` can recover new project and library tasks in this workspace, but is not a reason to generate again. For `savePending: true`, repair storage and call `retry_save` with the original `jobId` and stable `requestId`; this saves retained local outputs without a model call. `cancel` requests a stop, without promising remote cancellation or a refund.
5. **Keep old project tasks on their original route**: a task already submitted through `openmotion_media_use` retains its original Tool, `projectId`, `requestId` and `jobId`. Do not move it to a new generate call. That compatibility route saves project files directly; do not import them again. After completion, immediately `openmotion_get_project` to record the external-change snapshot before editing or restoring a version.
6. **Regeneration**: regenerate only within the asset count and spend the user explicitly approved, including any retries they approved. If that approval does not cover another paid request, keep usable versions and ask before submitting it. Keep earlier usable versions; changing text/layout does not regenerate pixels or audio. A failed/interrupted request or uncertain outcome is not a quality regeneration: inspect the original task before considering another paid submission, never switch Tool/provider to hide an unknown result.
Classify failures from the actual status, error code and stage before deciding the next step:
- **Provider key or permission rejection (`401` / `403`) vs upstream vendor auth (`upstream_provider_unauthenticated`)**: distinguish an invalid/unauthorized workspace or provider key from an upstream model vendor authentication issue behind a gateway.
- **Unexposed route vs missing resource (`404`)**: distinguish a gateway origin where `/api/v1/media/*` is not deployed on that environment from an unknown model slug or expired remote task ID.
- **Timeouts and interrupted polling**: distinguish submit timeout, status-poll timeout and media-download timeout. After an unknown outcome, query `action: "status"` on the original `jobId` (or replay the exact `requestId` with identical inputs) before proposing any new billable submission. Changing prompt, model or parameters requires a new `requestId`.
- **Tell the user the next step in plain language**: for third-party BYOK, a credential-rejection `401` / `403` marks the saved key rejected, so ask them to replace it in **Model providers** / **模型供应商**; an error whose text names balance, credit, quota or insufficient funds means topping up in that provider's own console; for any other failure, relay the provider's message briefly without guessing a cause. Keep assets that already finished and offer the same choices as for a missing kind for the failed part.
## OpenDesign account recovery
For OpenDesign account failures, match the actual returned message as well as any exposed error code. “Your OpenDesign plan does not include this model” means opening Settings with `openmotion_open_preview` (`target: "providers"` and `entry: "agent_media_upgrade_free"` or `"agent_media_upgrade_go"` when known), then using the **Upgrade to Plus** button in **Settings → Model providers → OpenDesign** for Free/Go; an already eligible plan may still need another entitled model. “Your OpenDesign balance is too low” means opening Settings with `entry: "agent_media_balance_low"` and using **Manage subscription** on the opened **OpenDesign** page to check credits and top-up options. Other BYOK providers use their own console for top-ups. After setup confirmation, inspect again and continue the original request; inspect the original job before considering any new paid submission.
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 |