> For AI agents: the complete documentation index is available at https://docs.reelway.ai/llms.txt, the full documentation bundle is available at https://docs.reelway.ai/llms-full.txt.

# 媒体上传 URL

托管工具与生成任务需要「HTTP(S) URL」形态的媒体引用(`media_references` 校验 http(s),`1009` 错误码兜底)。把本地文件变成可引用 URL 的两条路径:

| 方式         | 端点                                                | 适用                    |                    |
| ---------- | ------------------------------------------------- | --------------------- | ------------------ |
| 预签名 URL 直传 | \`GET /v1/image                                   | media/uploadUrl\`     | 一次性输入(首帧、参考图、参考音频) |
| 获取下载 URL   | \`GET /v1/image                                   | media/downloadUrl\`   | 读取已完成项目的产物或已上传槽位   |
| 资产库(可复用)   | `POST /v1/assets/prepare → PUT → finalize → bind` | 同一文件被多个项目引用、需要去重与配额管理 |                    |

## 直传示例

```bash
# 1. 申请上传 URL
curl "https://rcn.reelway.ai/v1/image/uploadUrl?type=referenceImage&jobId=$JOB_ID&contentType=image/png" \
  -H "api-key: $REELWAY_API_KEY"

# 2. PUT 文件体(原样携带 uploadHeaders)
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" --data-binary @ref.png
```

槽位枚举(image 侧):`preview`、`complete`、`startingImage`、`cnImage`、`contextImage1..16`、`keyframeImage1..8`、`referenceImage`、`referenceImageEnd`、`referenceMask`;media 侧:`referenceAudio`、`referenceVideo`。细节见[媒体与图像 URL](https://docs.reelway.ai/api-reference/media.md)。

## 资产库四步

`prepare` 按 sha256 去重(同文件直接 `reused: true` 跳过上传),`finalize` 复验哈希与大小后置 `ready`,`bind` 把资产绑定到项目槽位;配额见[媒体工具](https://docs.reelway.ai/api-reference/media-utilities.md)。

## 错误速查

| HTTP | 错误码    | 场景                                    |
| ---- | ------ | ------------------------------------- |
| 400  | `1009` | 工作流 `media_references` 引用了非 http(s) 值 |
| 404  | —      | `downloadUrl` 对象不存在                   |
| 423  | —      | `bind` 时资产非 `ready`                   |