@talesofai/neta-skills 0.14.3 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @neta/skills-neta
 
+## 0.15.0
+
+### Minor Changes
+
+- support media assets upload
+
 ## 0.14.3
 
 ### Patch Changes

package/bin/apis/artifact.js

@@ -51,6 +51,20 @@ export const createArtifactApis = (client) => {
         })
             .then((res) => res.data);
     };
+    const createPicture = (data) => {
+        return client
+            .post(`/v1/artifact/picture`, {
+            url: data.url,
+        })
+            .then((res) => res.data);
+    };
+    const createVideo = (data) => {
+        return client
+            .post(`/v1/artifact/video`, {
+            url: data.url,
+        })
+            .then((res) => res.data);
+    };
     return {
         makeImage,
         makeVideo,
@@ -60,5 +74,7 @@ export const createArtifactApis = (client) => {
         postProcess,
         task,
         artifactDetail,
+        createPicture,
+        createVideo,
     };
 };

package/bin/apis/index.js

@@ -9,6 +9,7 @@ import { createConfigApis } from "./config.js";
 import { createFeedsApis } from "./feeds.js";
 import { createGptApis } from "./gpt.js";
 import { createHashtagApis, } from "./hashtag.js";
+import { createOssApis } from "./oss.js";
 import { createPromptApis } from "./prompt.js";
 import { createRecsysApis } from "./recsys.js";
 import { createSpaceApis } from "./space.js";
@@ -63,6 +64,7 @@ export const createApis = (option) => {
     const recsys = createRecsysApis(client);
     const travelCampaign = createTravelCampaignApis(client);
     const commerce = createCommerceApis(client);
+    const oss = createOssApis(client);
     return {
         baseUrl,
         tcp,
@@ -82,5 +84,6 @@ export const createApis = (option) => {
         recsys,
         travelCampaign,
         commerce,
+        oss,
     };
 };

package/bin/apis/oss.js

@@ -0,0 +1,22 @@
+export const createOssApis = (client) => {
+    const getStsCredentials = async (suffix) => {
+        const res = await client.get("/v1/oss/sts-upload-token", {
+            params: {
+                suffix,
+            },
+        });
+        return res.data;
+    };
+    const getVideoStsCredentials = async (suffix) => {
+        const res = await client.get("/v1/oss/anonymous-upload-token", {
+            params: {
+                suffix,
+            },
+        });
+        return res.data;
+    };
+    return {
+        getStsCredentials,
+        getVideoStsCredentials,
+    };
+};

package/bin/commands/creative/upload.cmd.en_us.yml

@@ -0,0 +1,10 @@
+name: upload
+title: Media File Upload
+description: Upload a media file (image or video) to create a media artifact.
+
+parameters:
+  file_path: Media file path (absolute path or relative path to command execution directory)
+
+errors:
+  file_type_not_supported: Media file type not supported
+  file_size_too_large: Media file size too large, maximum size is {max_size} bytes

package/bin/commands/creative/upload.cmd.js

@@ -0,0 +1,192 @@
+import { readFile } from "node:fs/promises";
+import { CompleteMultipartUploadCommand, CreateMultipartUploadCommand, S3Client, UploadPartCommand, } from "@aws-sdk/client-s3";
+import { Type } from "@sinclair/typebox";
+import { filetypeinfo } from "magic-bytes.js";
+import plimit from "p-limit";
+import { parseMeta } from "../../utils/parse_meta.js";
+import { polling } from "../../utils/polling.js";
+import { createCommand } from "../factory.js";
+const OSS_STS_OPTIONS_CN = {
+    bucket: "talesofai",
+    region: "oss-cn-shanghai",
+    endpoint: "oss.talesofai.cn",
+};
+const OSS_STS_OPTIONS_US = {
+    bucket: "talesofai-us",
+    region: "oss-us-west-1",
+    endpoint: "oss.talesofai.com",
+};
+const DEFAULT_IMAGE_LIMIT_SIZE = 1024 * 1024 * 10;
+const DEFAULT_VIDEO_LIMIT_SIZE = 1024 * 1024 * 100;
+const SUPPORTED_IMAGE_TYPES = ["png", "jpeg", "webp", "gif"];
+const SUPPORTED_VIDEO_TYPES = [
+    "avi",
+    "mov",
+    "flv",
+    "mkv",
+    "webm",
+    "mp4",
+    "mpeg",
+    "wmv",
+    "rm",
+    "vob",
+    "ts",
+];
+const meta = parseMeta(Type.Object({
+    name: Type.String(),
+    title: Type.String(),
+    description: Type.String(),
+    parameters: Type.Object({
+        file_path: Type.String(),
+    }),
+    errors: Type.Object({
+        file_type_not_supported: Type.String(),
+        file_size_too_large: Type.String(),
+    }),
+}), import.meta);
+const s3Upload = async (data, options) => {
+    const { mimeType, regionOptions, credentials, logger } = options;
+    const { bucket, region, endpoint } = regionOptions;
+    const { access_key_id, access_key_secret, security_token, expiration, path } = credentials;
+    const now = Date.now();
+    const expires = new Date(expiration).getTime();
+    if (now > expires) {
+        throw new Error("STS token expired");
+    }
+    const client = new S3Client({
+        region,
+        credentials: {
+            accessKeyId: access_key_id,
+            secretAccessKey: access_key_secret,
+            sessionToken: security_token,
+        },
+        endpoint: `https://${region}.aliyuncs.com`,
+    });
+    const createMultipartUploadCommand = new CreateMultipartUploadCommand({
+        Bucket: bucket,
+        Key: path,
+        ContentType: mimeType,
+    });
+    const createMultipartUploadResponse = await client.send(createMultipartUploadCommand);
+    const uploadId = createMultipartUploadResponse.UploadId;
+    const partSize = 1 * 1024 * 1024;
+    const parts = Math.ceil(data.length / partSize);
+    const tasks = [];
+    let uploadedSize = 0;
+    for (let i = 0; i < parts; i++) {
+        const start = i * partSize;
+        const end = Math.min(start + partSize, data.length);
+        const partData = data.subarray(start, end);
+        const uploadPartCommand = new UploadPartCommand({
+            Bucket: bucket,
+            Key: path,
+            PartNumber: i + 1,
+            UploadId: uploadId,
+            Body: partData,
+        });
+        const uploadPart = async (partNumber) => {
+            const res = await client.send(uploadPartCommand);
+            uploadedSize += partData.length;
+            logger.debug("uploaded %d bytes, part %d", uploadedSize, partNumber);
+            return res;
+        };
+        tasks.push(uploadPart);
+    }
+    const limit = plimit(8);
+    const completedParts = await Promise.all(tasks.map((run, index) => limit(() => run(index + 1).then((res) => ({
+        ETag: res.ETag,
+        PartNumber: index + 1,
+    })))));
+    const completeMultipartUploadCommand = new CompleteMultipartUploadCommand({
+        Bucket: bucket,
+        Key: path,
+        UploadId: uploadId,
+        MultipartUpload: {
+            Parts: completedParts,
+        },
+    });
+    await client.send(completeMultipartUploadCommand);
+    const url = `https://${endpoint}/${path}`;
+    logger.debug("completed multipart upload, url: %s", url);
+    return url;
+};
+const createArtifact = async (url, options) => {
+    const { type, apis, logger } = options;
+    let uuid;
+    if (type === "image") {
+        const res = await apis.artifact.createPicture({ url });
+        uuid = res.uuid;
+    }
+    if (type === "video") {
+        const res = await apis.artifact.createVideo({ url });
+        uuid = res.uuid;
+    }
+    const res = await polling(() => apis.artifact.artifactDetail([uuid]), (result) => {
+        const artifact = result[0];
+        if (!artifact)
+            throw new Error("Artifact not found");
+        logger.debug("polling: %o", artifact);
+        return artifact.status !== "PENDING" && artifact.status !== "MODERATION";
+    }, 1000, 60 * 1000);
+    if (res.isTimeout) {
+        throw new Error("Timeout");
+    }
+    // biome-ignore lint/style/noNonNullAssertion: checked
+    return res.result[0];
+};
+export const upload = createCommand({
+    name: meta.name,
+    title: meta.title,
+    description: meta.description,
+    inputSchema: Type.Object({
+        file_path: Type.String({ description: meta.parameters.file_path }),
+    }),
+}, async ({ file_path }, { apis, user, log }) => {
+    if (!user) {
+        throw new Error("Not authenticated. Please check your NETA_TOKEN.");
+    }
+    const regionOptions = apis.baseUrl.endsWith(".cn")
+        ? OSS_STS_OPTIONS_CN
+        : OSS_STS_OPTIONS_US;
+    const file = await readFile(file_path);
+    const infos = filetypeinfo(file);
+    const info = infos[0]; // always use first extension
+    if (!info || !info.extension || !info.mime) {
+        throw new Error(meta.errors.file_type_not_supported);
+    }
+    if (SUPPORTED_IMAGE_TYPES.includes(info.extension)) {
+        if (file.length > DEFAULT_IMAGE_LIMIT_SIZE) {
+            throw new Error(meta.errors.file_size_too_large.replace("{max_size}", DEFAULT_IMAGE_LIMIT_SIZE.toString()));
+        }
+        const credentials = await apis.oss.getStsCredentials(info.extension);
+        const url = await s3Upload(file, {
+            mimeType: info.mime,
+            regionOptions: regionOptions,
+            credentials,
+            logger: log,
+        });
+        return createArtifact(url, {
+            type: "image",
+            apis,
+            logger: log,
+        });
+    }
+    if (SUPPORTED_VIDEO_TYPES.includes(info.extension)) {
+        if (file.length > DEFAULT_VIDEO_LIMIT_SIZE) {
+            throw new Error(meta.errors.file_size_too_large.replace("{max_size}", DEFAULT_VIDEO_LIMIT_SIZE.toString()));
+        }
+        const credentials = await apis.oss.getVideoStsCredentials(info.extension);
+        const url = await s3Upload(file, {
+            mimeType: info.mime,
+            regionOptions: regionOptions,
+            credentials,
+            logger: log,
+        });
+        return createArtifact(url, {
+            type: "video",
+            apis,
+            logger: log,
+        });
+    }
+    throw new Error(meta.errors.file_type_not_supported);
+});

package/bin/commands/creative/upload.cmd.zh_cn.yml

@@ -0,0 +1,10 @@
+name: upload
+title: 媒体文件上传
+description: 上传媒体文件（图片、视频）并创建一个媒体素材。
+
+parameters:
+  file_path: 媒体文件路径（绝对路径或命令执行目录的相对路径）
+
+errors:
+  file_type_not_supported: 文件类型不支持
+  file_size_too_large: 文件大小超过最大限制, 最大支持 {max_size} 字节

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talesofai/neta-skills",
-  "version": "0.14.3",
+  "version": "0.15.0",
   "description": "Neta API pi coding agent skills for interacting with Neta API to generate images, videos, songs, and manage characters/elements.",
   "type": "module",
   "repository": {
@@ -25,24 +25,11 @@
   "engines": {
     "node": ">=22.0.0"
   },
-  "packageManager": "pnpm@10.25.0",
   "bin": {
     "neta-cli": "bin/cli.js"
   },
-  "scripts": {
-    "lint": "biome check . --write --unsafe",
-    "validate": "skills-ref to-prompt ./skills/neta ./skills/neta-community ./skills/neta-creative ./skills/neta-suggest ./skills/neta-space ./skills/neta-character ./skills/neta-elementum ./skills/neta-adventure",
-    "type-check": "tsc --noEmit",
-    "check": "pnpm lint && pnpm type-check && pnpm validate",
-    "changelog": "changeset",
-    "bump": "changeset version",
-    "prepare": "husky",
-    "build": "rimraf bin && tsc",
-    "postbuild": "node scripts/postbuild.js",
-    "dev": "NODE_ENV=development node src/cli.ts",
-    "start": "node bin/cli.js"
-  },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1013.0",
     "@commander-js/extra-typings": "^14.0.0",
     "@sinclair/typebox": "^0.34.48",
     "axios": "^1.7.9",
@@ -50,7 +37,9 @@
     "dayjs": "^1.11.20",
     "dotenv": "^16.4.7",
     "dotenv-flow": "^4.1.0",
+    "magic-bytes.js": "^1.13.0",
     "os-locale": "^8.0.0",
+    "p-limit": "^7.3.0",
     "qs": "^6.15.0",
     "skills-ref": "^0.1.5",
     "yaml": "^2.8.2"
@@ -74,5 +63,17 @@
     "README.zh_cn.md",
     "CHANGELOG.md",
     "LICENSE"
-  ]
-}
+  ],
+  "scripts": {
+    "lint": "biome check . --write --unsafe",
+    "validate": "skills-ref to-prompt ./skills/neta ./skills/neta-community ./skills/neta-creative ./skills/neta-suggest ./skills/neta-space ./skills/neta-character ./skills/neta-elementum ./skills/neta-adventure",
+    "type-check": "tsc --noEmit",
+    "check": "pnpm lint && pnpm type-check && pnpm validate",
+    "changelog": "changeset",
+    "bump": "changeset version",
+    "build": "rimraf bin && tsc",
+    "postbuild": "node scripts/postbuild.js",
+    "dev": "NODE_ENV=development node src/cli.ts",
+    "start": "node bin/cli.js"
+  }
+}

package/skills/neta-creative/SKILL.md

@@ -55,6 +55,16 @@ Combine an audio track and video to create a full MV.
 npx -y @talesofai/neta-skills@latest remove_background --input_image "image_artifact_uuid"
 ```
 
+**Upload local image or video**
+
+Registers a file from disk as a Neta artifact (after upload and moderation). Use the returned **`uuid`** or **`url`** in `make_image` (`ref_img-…`), `make_video` (`--image_source` URL), `remove_background`, or collection commands.
+
+```bash
+npx -y @talesofai/neta-skills@latest upload --file_path "/path/to/file.png"
+```
+
+📖 [Media upload](./references/media-upload.md) — supported types, size limits, and how outputs map to each downstream command.
+
 ### Character queries
 
 **Search characters**
@@ -137,6 +147,7 @@ npx -y @talesofai/neta-skills@latest pay_premium_order --order_uuid "order-uuid"
 | 🎬 Video generation   | [video-generation.md](./references/video-generation.md) |
 | 🎵 Song generation    | [song-creation.md](./references/song-creation.md)       |
 | 🎞️ MV creation       | [song-mv.md](./references/song-mv.md)                   |
+| 📤 Local media upload | [media-upload.md](./references/media-upload.md)        |
 | 👤 Character queries  | [character-search.md](./references/character-search.md) |
 | 🖊️ Creative remixing | [collection-remix.md](./references/collection-remix.md) |
 | ⭐ Premium / subscribe | [premium.md](./references/premium.md)                   |

package/skills/neta-creative/references/collection-remix.md

@@ -38,9 +38,12 @@ You will typically use the following commands for remix workflows:
 - `make_video`
 - `make_song`
 
+If the user supplies **local images or videos** that are not in the collection payload, run **`upload`** first, then reference picture artifacts with **`ref_img-<uuid>`** in `make_image` or the artifact **`url`** in `make_video`. See [Media upload](./media-upload.md).
+
 📖 See also:
 
 - [Generate Images](./image-generation.md)
 - [Generate Videos](./video-generation.md)
 - [Generate Songs](./song-creation.md)
+- [Media upload](./media-upload.md)
 

package/skills/neta-creative/references/image-generation.md

@@ -10,7 +10,7 @@ Applicable to `make_image` and `remove_background` commands.
 
 - **Characters**: Use characters in the format "@character_name", e.g., "@character_name". The character name must be an exact string match—no modifications, no spaces, no simplified/traditional Chinese conversion. This reference contains the character's complete visual information.
 - **Image Elements**: Use built-in image elements in the format "/element_name", e.g., "/comic_style".
-- **Reference Images**: When using the 8_image_edit model, you can reference existing images as references using the format "reference-image-artifact_uuid", e.g., "reference-image-1234567890". A maximum of 14 images is supported.
+- **Reference Images**: When using the 8_image_edit model, reference existing picture artifacts with the pattern **`ref_img-<uuid>`**, e.g. `ref_img-1234567890` (matches the CLI prompt parser). A maximum of 14 images is supported.
 - **Chinese Natural Language Phrases**: Descriptive text composed of short phrases depicting the scene. If no character is referenced, describe the character's appearance within the natural language phrases.
 
 **Recommended Format:**
@@ -23,10 +23,10 @@ Applicable to `make_image` and `remove_background` commands.
 - Image elements must appear in the format "/name", e.g., "/comic_style"
 - For the 8_image_edit model, provide more context and intent. Describe the scene rather than just listing keywords. This model's core strength lies in its deep language understanding. Narrative descriptive paragraphs almost always generate better, more coherent images compared to strings of unrelated words
 - You can search for available characters or elements using search_character_or_elementum, and verify their availability using request_character_or_elementum before use
-- Reference images must appear in the format "reference-image-artifact_uuid", and can only use images obtained via `read_collection` or generated images as references
+- Reference images must use **`ref_img-<uuid>`** (artifact UUID). Sources include **`upload`** (local files), **`make_image` / `read_collection` outputs**, or other picture artifacts the user already owns
 - When referencing characters or elements, add spaces or commas before and after, e.g., "@Neta#996, /comic_style, walking in school"
 - For image modifications and other generations related to referencing the original image, be sure to use reference images with the 8_image_edit model
-- Example (referencing characters and elements): @Neta#996, /comic_style, reference-image-artifact_uuid, reference-image-artifact_uuid, phrase1, phrase2…
+- Example (referencing characters and elements): @Neta#996, /comic_style, ref_img-uuid, ref_img-uuid, phrase1, phrase2…
 - **When a specific character exists, use the character via @character_name rather than re-describing the character's appearance**
 ---
 
@@ -89,6 +89,12 @@ npx -y @talesofai/neta-skills@latest make_image \
 
 ---
 
+## Local files as reference images
+
+If the user’s image only exists **on disk**, run **`upload`** first, then use the returned artifact UUID in the prompt as `ref_img-<uuid>`. Formats, size limits, and mapping to `make_video` / `remove_background` are documented in [Media upload](./media-upload.md).
+
+---
+
 ## Common Use Cases
 
 ### Character Standing Illustration
@@ -163,3 +169,4 @@ npx -y @talesofai/neta-skills@latest remove_background --input_image "image_arti
 
 - [Character Search](./character-search.md) - Get character standard information
 - [Video Generation](./video-generation.md) - Convert images to dynamic videos
+- [Media upload](./media-upload.md) - Local files → artifacts for reference / video / cutout

package/skills/neta-creative/references/media-upload.md

@@ -0,0 +1,101 @@
+# Uploading user media (local files)
+
+Use the `upload` command when the user has **image or video files on disk** that must become Neta **artifacts** before other creative commands can reference them. The CLI reads the file, uploads it via STS to object storage, registers it as a picture or video artifact, and polls until processing leaves `PENDING` / `MODERATION`.
+
+**Command**
+
+```bash
+npx -y @talesofai/neta-skills@latest upload --file_path "/absolute/or/relative/path/to/file.png"
+```
+
+**Requirements**
+
+- **`NETA_TOKEN`** must be set (same as other authenticated commands). Unauthenticated runs fail with an explicit error.
+- **`file_path`**: absolute path, or path relative to the **current working directory** when the command runs.
+
+---
+
+## Supported formats and limits
+
+Detection uses file **magic bytes** (not only the extension). Unsupported or unrecognised types raise `file_type_not_supported`.
+
+| Kind   | Extensions (examples) | Default max size |
+|--------|------------------------|------------------|
+| Image  | `png`, `jpeg`, `webp`, `gif` | 10 MiB |
+| Video  | `avi`, `mov`, `flv`, `mkv`, `webm`, `mp4`, `mpeg`, `wmv`, `rm`, `vob`, `ts` | 100 MiB |
+
+Oversized files raise `file_size_too_large`.
+
+**Region / bucket**: the implementation picks CN vs US OSS settings from the API base URL (`.cn` vs default). You normally do not configure this in the skill.
+
+---
+
+## Command output
+
+On success, the command returns an **artifact detail** object (same shape as other artifact APIs), including at least:
+
+- **`uuid`**: stable artifact id — use this anywhere a command expects an artifact UUID (see below).
+- **`url`**: public URL for the asset when available — use for parameters that expect an **image URL** (e.g. `make_video --image_source`).
+- **`modality`**, **`status`**, and optional `image_detail` / `video_detail`.
+
+Wait until the command finishes; it already waits through upload and moderation polling (timeout can still occur on very slow jobs — treat as a hard error and retry or narrow the file).
+
+---
+
+## Where uploaded artifacts are used in the creative skill
+
+These are the **neta-creative** flows that consume **user-origin** content once it exists as an artifact (via `upload`, or via prior generation / `read_collection`).
+
+| Goal | Command | What to pass from `upload` result |
+|------|---------|-----------------------------------|
+| Image edit / multi-reference generation (`8_image_edit`) | `make_image` | Put **`ref_img-<uuid>`** in the prompt (up to 14). See [Image generation](./image-generation.md). |
+| Image → video | `make_video` | **`--image_source`** = the artifact’s **`url`** (string URL), not the bare UUID. See [Video generation](./video-generation.md). |
+| Transparent background | `remove_background`, `remove_background_nocrop` | **`--input_image`** = artifact **`uuid`**. See [Image generation](./image-generation.md) (background removal). |
+| Remix / reference from a work | `read_collection` | Collection payloads may include reference images; local files are not injected directly — **upload first**, then use `ref_img-<uuid>` in `make_image` if you need them in-prompt. See [Creative remix](./collection-remix.md). |
+| Publish or update a collection with specific assets | `publish_collection`, `edit_collection` | **`artifacts`**: comma-separated picture **UUIDs** (1–12). Upload images first, then pass their UUIDs. |
+
+**`make_song`** does not take image or video uploads; for MVs you still combine song + `make_image` / `make_video` as in [Song MV](./song-mv.md). Use **`upload`** when the cover or plate still lives only as a local file.
+
+---
+
+## Suggested workflows
+
+### Local photo → video
+
+```bash
+npx -y @talesofai/neta-skills@latest upload --file_path "./still.png"
+# From JSON output, copy "url" for image_source and/or "uuid" for other steps.
+
+npx -y @talesofai/neta-skills@latest make_video \
+  --image_source "<URL_FROM_UPLOAD_OUTPUT>" \
+  --prompt "Gentle breathing, slight hair movement, soft light." \
+  --model "model_s"
+```
+
+### Local image → edit with `8_image_edit`
+
+```bash
+npx -y @talesofai/neta-skills@latest upload --file_path "./reference.jpg"
+
+npx -y @talesofai/neta-skills@latest make_image \
+  --prompt "ref_img-<UUID_FROM_UPLOAD_OUTPUT>, change outfit to winter coat, keep pose and background" \
+  --aspect "3:4" \
+  --model_series "8_image_edit"
+```
+
+### Local image → cutout
+
+```bash
+npx -y @talesofai/neta-skills@latest upload --file_path "./character.png"
+
+npx -y @talesofai/neta-skills@latest remove_background --input_image "<UUID_FROM_UPLOAD_OUTPUT>"
+```
+
+---
+
+## Related docs
+
+- [Image generation](./image-generation.md) — `ref_img-` prompt syntax, models, background removal.
+- [Video generation](./video-generation.md) — `image_source` and motion prompts.
+- [Song MV](./song-mv.md) — combining audio and visuals.
+- [Creative remix](./collection-remix.md) — using `read_collection` with generation commands.

package/skills/neta-creative/references/song-mv.md

@@ -158,6 +158,10 @@ npx -y @talesofai/neta-skills@latest make_video --image_source "<URL3>" --prompt
 - Use `16:9` aspect ratio for images.
 - Works well for mainstream video platforms.
 
+### Local cover or key art
+
+If the user already has a cover image file, **`upload`** it and pass the returned **`url`** into `make_video --image_source` (or use `ref_img-<uuid>` in `make_image` when compositing). Details: [Media upload](./media-upload.md).
+
 ### Model selection
 
 - Prototyping: `model_s` (faster).

package/skills/neta-creative/references/video-generation.md

@@ -2,6 +2,8 @@
 
 Applies to the `make_video` command.
 
+**User-uploaded stills:** `make_video --image_source` expects an **image URL** string. After **`upload`**, use the artifact’s **`url`** field from the command output (not the bare UUID). See [Media upload](./media-upload.md).
+
 ---
 
 ## Prompt principles
@@ -238,5 +240,6 @@ She slowly blinks, the corners of her mouth lifting slightly, strands of hair sw
 ## Related docs
 
 - [Image generation](./image-generation.md) — generating still images for video conversion.
+- [Media upload](./media-upload.md) — using local stills as `image_source`.
 - [Song MV](./song-mv.md) — combining songs and videos to build full music videos.
 

package/skills/zh_cn/neta/SKILL.md

@@ -68,6 +68,7 @@ npx skills add talesofai/neta-skills/skills/zh_cn/neta-adventure
 
 负责：
 - 生成图片、视频、歌曲、MV
+- 上传本地图片/视频为平台素材（`upload`，供参考图、图生视频、抠图等使用）
 - 移除图片背景
 - 角色搜索与详情（创作语境下使用）
 - 通过 `read_collection` 从作品反向拆解创作思路

package/skills/zh_cn/neta-creative/SKILL.md

@@ -20,8 +20,9 @@ description: Neta API 创作技能——生成图片、视频、歌曲、MV，
 
 **生成图片**
 ```bash
-npx -y @talesofai/neta-skills@latest make_image --prompt "@角色名，/风格元素，参考图-图片uuid，描述词，描述词" --aspect "3:4"
+npx -y @talesofai/neta-skills@latest make_image --prompt "@角色名，/风格元素，参考图-素材uuid，描述词，描述词" --aspect "3:4"
 ```
+（`参考图-` 与 `ref_img-` 前缀均可，后接图片素材的 UUID。）
 📖 [详细指南](./references/image-generation.md) - 提示词结构、宽高比选择、用例
 
 **生成视频**
@@ -47,6 +48,16 @@ npx -y @talesofai/neta-skills@latest make_song --prompt "风格描述" --lyrics
 npx -y @talesofai/neta-skills@latest remove_background --input_image "image_artifact_uuid"
 ```
 
+**上传本地图片或视频**
+
+将磁盘上的文件登记为 Neta 素材（含上传与审核等待）。根据输出中的 **`uuid`** / **`url`**，再用于 `make_image`（`参考图-…` / `ref_img-…`）、`make_video`（`--image_source` 填 **URL**）、`remove_background`、或合集相关命令。
+
+```bash
+npx -y @talesofai/neta-skills@latest upload --file_path "/path/to/file.png"
+```
+
+📖 [媒体上传](./references/media-upload.md) — 支持格式、大小限制、与各下游命令的对应关系。
+
 ### 角色查询
 
 **搜索角色**
@@ -83,5 +94,6 @@ npx -y @talesofai/neta-skills@latest read_collection --uuid "作品-uuid"
 | 🎬 视频生成 | [video-generation.md](./references/video-generation.md) |
 | 🎵 歌曲创作 | [song-creation.md](./references/song-creation.md) |
 | 🎞️ MV 制作 | [song-mv.md](./references/song-mv.md) |
+| 📤 本地上传 | [media-upload.md](./references/media-upload.md) |
 | 👤 角色查询 | [character-search.md](./references/character-search.md) |
 | 🖊️ 内容创作思路 | [collection-remix.md](./references/collection-remix.md) |

package/skills/zh_cn/neta-creative/references/collection-remix.md

@@ -31,10 +31,14 @@ npx -y @talesofai/neta-skills@latest read_collection --uuid "作品-uuid"
 
 ## 开始创作
 
-适用 `make_image` `make_video` `make_song` 命令
+适用 `make_image` `make_video` `make_song` 命令。
+
+若用户提供的**图片或视频在本地**、不在合集返回的素材列表中，请先 **`upload`**，再在 `make_image` 中使用 **`参考图-<uuid>`** / **`ref_img-<uuid>`**，或在 `make_video` 中使用素材的 **`url`**。详见 [媒体上传](./media-upload.md)。
 
 📖 - [生成图片](./image-generation.md)
 
 📖 - [生成视频](./video-generation.md)
 
 📖 - [生成歌曲](./song-creation.md)
+
+📖 - [媒体上传](./media-upload.md)

package/skills/zh_cn/neta-creative/references/image-generation.md

@@ -10,7 +10,7 @@
 
 - 角色:通过"@角色名"格式使用角色,如"@角色名"。角色名必须是完全一致的字符串,不得修改,不得加空格,不得简体繁体转换。这个引用会包含角色的完整形象信息。
 - 画面元素:通过"/元素名称"格式使用工具自带的画面元素,如"/漫画屋"。
-- 参考图: 当使用 8_image_edit 模型时可以通过"参考图-artifact_uuid"格式引用已存在的图片作为参考图,如"参考图-1234567890"。最多能有 14 张图片
+- 参考图: 使用 `8_image_edit` 时，用 **`参考图-<uuid>`** 引用已有**图片素材**，如 `参考图-1234567890`；亦可使用 **`ref_img-<uuid>`**（与英文 CLI 说明一致），解析效果相同。最多 14 张
 - 中文自然语言词组:由短语组成的描述画面的文本,如果没有引用角色,则需要在自然语言词组中描述角色形象.
 
 **推荐格式：**
@@ -23,10 +23,10 @@
   - 画面元素必须以 "/名称" 形式出现,如 "/漫画屋"
   - 对于 8_image_edit 模型，要多提供上下文和意图。要描述场景，而不仅仅是列出关键字。该模型的核心优势在于其深厚的语言理解能力。与一连串不相关的字词相比，叙述性描述段落几乎总是能生成更好、更连贯的图片
   - 可以通过 search_character_or_elementum 搜索来获取可以使用的角色或元素，使用前通过 request_character_or_elementum 验证角色或者元素可用
-  - 参考图必须以 参考图-artifact_uuid 形式出现, 只能使用 `read_collection` 获取到的图片 artifact，或者生成过的图片作为参考图
+  - 参考图须为 **`参考图-<uuid>`** 或 **`ref_img-<uuid>`**（`<uuid>` 为图片素材 ID）。来源包括：**`upload`（本地文件）**、`read_collection` 中的图片、或其它已生成的图片素材
   - 引用角色或者元素的时候,前后要添加空格或逗号分隔,如："@奈塔#996, /漫画风格, 在校园里散步"
   - 对于修改图片等跟原图参考相关的生成,请一定使用携带参考图并使用 8_image_edit 模型
-  - 示例(引用角色和元素)：@奈塔#996, /漫画风格, 参考图-artifact_uuid, 参考图-artifact_uuid, 词组1, 词组2…
+  - 示例(引用角色和元素)：@奈塔#996, /漫画风格, 参考图-uuid, 参考图-uuid, 词组1, 词组2…
   - **存在具体的角色时，通过@角色名来使用角色，而不是重新描述角色的外貌**
 ---
 
@@ -89,6 +89,12 @@ npx -y @talesofai/neta-skills@latest make_image \
 
 ---
 
+## 本地文件作为参考图
+
+若图片**只存在于本机**，请先执行 **`upload`**，再在提示词中使用 **`参考图-<uuid>`** 或 **`ref_img-<uuid>`**（`<uuid>` 取自上传命令返回的 JSON）。支持格式、大小及与 `make_video` / `remove_background` 的衔接见 [媒体上传](./media-upload.md)。
+
+---
+
 ## 常见用例
 
 ### 角色立绘
@@ -163,3 +169,4 @@ npx -y @talesofai/neta-skills@latest remove_background --input_image "image_arti
 
 - [角色查询](./character-search.md) - 获取角色标准信息
 - [视频生成](./video-generation.md) - 将图片转换为动态视频
+- [媒体上传](./media-upload.md) - 本地文件 → 素材，供参考图 / 视频首帧 / 抠图使用

package/skills/zh_cn/neta-creative/references/media-upload.md

@@ -0,0 +1,103 @@
+# 上传用户媒体（本地文件）
+
+当用户有**磁盘上的图片或视频**，需要先变成 Neta 平台上的**素材（artifact）** 时，使用 **`upload`** 命令。CLI 会读取文件、通过 STS 上传到对象存储、登记为图片或视频素材，并轮询直到状态离开 `PENDING` / `MODERATION`。
+
+**命令**
+
+```bash
+npx -y @talesofai/neta-skills@latest upload --file_path "/绝对路径或相对路径/文件.png"
+```
+
+**前置条件**
+
+- 需设置 **`NETA_TOKEN`**（与其他需登录的命令相同）。未登录会报错。
+- **`file_path`**：绝对路径，或相对于**执行命令时当前工作目录**的相对路径。
+
+---
+
+## 支持的格式与大小限制
+
+类型依据文件 **魔数** 检测（不仅看扩展名）。无法识别或不支持的类型会触发 `file_type_not_supported`。
+
+| 类型 | 扩展名（示例） | 默认最大体积 |
+|------|----------------|--------------|
+| 图片 | `png`、`jpeg`、`webp`、`gif` | 10 MiB |
+| 视频 | `avi`、`mov`、`flv`、`mkv`、`webm`、`mp4`、`mpeg`、`wmv`、`rm`、`vob`、`ts` | 100 MiB |
+
+超出限制会触发 `file_size_too_large`。
+
+**地域与存储桶**：实现会根据 API 基址是否以 `.cn` 结尾选择国内或海外 OSS，一般无需在技能侧单独配置。
+
+---
+
+## 命令输出
+
+成功时返回 **素材详情**（与其他 artifact 接口结构一致），通常包括：
+
+- **`uuid`**：素材 ID —— 凡是命令要求「素材 UUID」的场景都使用它（见下表）。
+- **`url`**：可访问的图片/视频 URL（若已就绪）—— 用于要求 **图片 URL** 的参数（例如 `make_video --image_source`）。
+- **`modality`**、**`status`**，以及可选的 `image_detail` / `video_detail`。
+
+需等待命令执行结束；其中已包含上传与审核轮询（极端情况下仍可能超时，按错误处理或换更小文件重试）。
+
+---
+
+## 上传结果在创作技能中的用法
+
+以下 **`neta-creative`** 流程会在素材已存在（通过 **`upload`**、此前 **`make_image`** 产出、或 **`read_collection`** 等）时消费用户侧内容。
+
+| 目标 | 命令 | 如何使用 `upload` 的返回值 |
+|------|------|---------------------------|
+| 图生图 / 多参考图（`8_image_edit`） | `make_image` | 在提示词中写 **`参考图-<uuid>`** 或 **`ref_img-<uuid>`**（最多 14 张，两种前缀解析器均支持）。见 [图片生成](./image-generation.md)。 |
+| 图生视频 | `make_video` | **`--image_source`** 填素材的 **`url`**（字符串 URL），不要只填裸 UUID。见 [视频生成](./video-generation.md)。 |
+| 抠图 / 去背 | `remove_background`、`remove_background_nocrop` | **`--input_image`** 填素材 **`uuid`**。见 [图片生成](./image-generation.md) 中去背景一节。 |
+| 从作品 Remix | `read_collection` | 合集载荷里可能带参考图；**本地文件**不会自动进入合集 —— 先 **`upload`**，再在 `make_image` 里用 **`参考图-<uuid>`** / **`ref_img-<uuid>`**，或把 **`url`** 用于 `make_video`。见 [内容创作思路](./collection-remix.md)。 |
+| 发布或更新合集素材 | `publish_collection`、`edit_collection` | **`artifacts`**：逗号分隔的**图片 UUID**（1～12 个）。先上传图片，再传入对应 UUID。 |
+
+**`make_song`** 不接受图片/视频文件；做 MV 仍按 [歌曲 MV](./song-mv.md) 组合歌曲与画面。若封面只在本地，先 **`upload`** 再接到 `make_image` / `make_video`。
+
+---
+
+## 推荐工作流
+
+### 本地静图 → 视频
+
+```bash
+npx -y @talesofai/neta-skills@latest upload --file_path "./静帧.png"
+# 从输出的 JSON 中取 "url" 作为 image_source，或 "uuid" 用于后续步骤
+
+npx -y @talesofai/neta-skills@latest make_video \
+  --image_source "<上传输出中的_URL>" \
+  --prompt "轻微呼吸感，发丝微动，光线柔和。" \
+  --model "model_s"
+```
+
+### 本地图片 → 用 `8_image_edit` 改图
+
+```bash
+npx -y @talesofai/neta-skills@latest upload --file_path "./参考.jpg"
+
+npx -y @talesofai/neta-skills@latest make_image \
+  --prompt "参考图-<上传输出中的_UUID>，改为冬装外套，保持姿势与背景不变" \
+  --aspect "3:4" \
+  --model_series "8_image_edit"
+```
+
+（将 `参考图-` 换成 `ref_img-` 效果相同。）
+
+### 本地图片 → 抠图
+
+```bash
+npx -y @talesofai/neta-skills@latest upload --file_path "./角色.png"
+
+npx -y @talesofai/neta-skills@latest remove_background --input_image "<上传输出中的_UUID>"
+```
+
+---
+
+## 相关文档
+
+- [图片生成](./image-generation.md) — 参考图写法、模型、去背景。
+- [视频生成](./video-generation.md) — `image_source` 与动作描述。
+- [歌曲 MV](./song-mv.md) — 歌曲与画面组合。
+- [内容创作思路](./collection-remix.md) — `read_collection` 与二创流程。

package/skills/zh_cn/neta-creative/references/song-mv.md

@@ -162,6 +162,10 @@ npx -y @talesofai/neta-skills@latest make_video --image_source "<URL3>" --prompt
 - 单个视频片段适合 5-15 秒
 - 完整 MV 需要多个片段组合
 
+### 本地封面或主视觉
+
+若用户已有封面图文件，先 **`upload`**，再将返回的 **`url`** 传给 `make_video --image_source`；若要在 `make_image` 里与其它元素合成，可使用 **`参考图-<uuid>`** 或 **`ref_img-<uuid>`**。详见 [媒体上传](./media-upload.md)。
+
 ---
 
 ## 常见问题
@@ -196,3 +200,4 @@ npx -y @talesofai/neta-skills@latest make_video --image_source "<URL3>" --prompt
 
 - [歌曲生成](./song-creation.md) - 生成歌曲和歌词
 - [视频生成](./video-generation.md) - 图片转视频技巧
+- [媒体上传](./media-upload.md) - 本地封面 / 素材接入流程

package/skills/zh_cn/neta-creative/references/video-generation.md

@@ -2,6 +2,8 @@
 
 适用于 `make_video` 命令。
 
+**用户上传的静图：** `make_video --image_source` 需要 **图片 URL 字符串**。在 **`upload`** 完成后，应使用输出 JSON 里素材的 **`url`** 字段（不要只传裸 UUID）。详见 [媒体上传](./media-upload.md)。
+
 ---
 
 ## 提示词原则
@@ -218,4 +220,5 @@ npx -y @talesofai/neta-skills@latest make_video \
 ## 相关文档
 
 - [图片生成](./image-generation.md) - 生成用于视频转换的图片
+- [媒体上传](./media-upload.md) - 本地静图作为 `image_source`
 - [歌曲 MV](./song-mv.md) - 结合歌曲和视频制作 MV