MMnode/skills/easy-media-multitrack-workflow/references/upload-api.md
turtle89431 4ea8431cd0
Some checks are pending
Publish to Comfy registry / Publish Custom Node to registry (push) Waiting to run
init
2026-09-26 11:11:23 -07:00

60 lines
2.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 媒体上传与路径记录
本参考用于把 Codex 上下文中的素材放入目标 ComfyUI input 目录。优先使用用户给出的 ComfyUI 地址;未提供地址时先读取 Easy Media 节点包 `config.yaml` 的 `COMFYUI_URL`,文件或字段不存在(含空值)时才回退至 `http://127.0.0.1:8188`。同一次工作流执行的上传、排队和历史查询必须使用同一实例。
地址解析与配置文件定位见 [提交参考](execution-api.md#地址与预检)。以下 curl 示例中的本机地址需替换为解析后的地址。
## 上传到 input 子目录
项目的前端统一通过 ComfyUI `/upload/image` 接口上传图片、音频和视频,并传递 input 子目录:
```bash
curl --fail-with-body --silent --show-error \
-X POST http://127.0.0.1:8188/upload/image \
-F 'image=@/absolute/path/to/clip.mp4' \
-F 'type=input' \
-F 'overwrite=false' \
-F 'subfolder=codex/session-name'
```
响应通常为:
```json
{"name":"clip.mp4","subfolder":"codex/session-name","type":"input"}
```
写入 TRACK_DATA 的 `file_path` 必须使用响应拼出的相对路径 `subfolder/name`,`source_type` 为 `input`。不要写上传前的本机绝对路径,也不要假设同名文件未被服务端改名。
## 通用根目录上传
`POST /easy-media/upload` 接受任意媒体文件并写入 input 根目录,但当前实现不支持子目录:
```bash
curl --fail-with-body --silent --show-error \
-X POST http://127.0.0.1:8188/easy-media/upload \
-F 'file=@/absolute/path/to/audio.wav'
```
响应为 `{"file_name":"..."}`。只有 `/upload/image` 不适用且用户不需要子目录时才使用此接口。
## URL 素材
`POST /easy-media/download-url` 会把 URL 下载到 input 根目录:
```bash
curl --fail-with-body --silent --show-error \
-X POST http://127.0.0.1:8188/easy-media/download-url \
-H 'Content-Type: application/json' \
--data '{"url":"https://example.com/media.mp4"}'
```
如果用户希望保持远程引用而非下载,可在 TRACK_DATA 中使用 `source_type: "url"` 与 `url` 字段。不要在没有用户授权时把私有素材发送到远程服务。
## 上传后检查
- 为本次编辑选择稳定且不含 `..` 的相对子目录,例如 `codex/<project-or-date>`。
- 逐个检查 HTTP 状态和 JSON 响应;失败时停止,不把失败素材写入时间线。
- 同一素材只上传一次,复用返回路径。
- 可通过 `GET /easy-media/media/recent?source=inputs&type=all&subfolder=...` 检查近期文件。
- 上传属于外部写入;dry-run 工作流补丁不会回滚已上传文件。