> 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

Reelway 不接受把文件内联在 API 请求或 WebSocket 帧里。输入(参考图、首尾帧、参考音频)通过**预签名上传 URL** 直传对象存储;产物通过**预签名下载 URL** 获取。四个端点分为 `image` 与 `media` 两组槽位,语义相同,只在内容类型白名单上不同。

| 端点                                        | 槽位    | 内容类型      |
| ----------------------------------------- | ----- | --------- |
| `GET /v1/image/uploadUrl` / `downloadUrl` | 图像    | `image/*` |
| `GET /v1/media/uploadUrl` / `downloadUrl` | 音频、视频 | 音频/视频白名单  |

需要**可复用**的上传(多次项目引用同一文件、去重、配额管理)请使用[资产库 `/v1/assets`](https://docs.reelway.ai/api-reference/media-utilities.md#%E8%B5%84%E4%BA%A7%E5%BA%93),它在同一存储之上提供 `prepare → PUT → finalize → bind` 状态机。

## `GET /v1/image/uploadUrl`


GEThttps://rcn.reelway.ai/v1/image/uploadUrl鉴权:凭证 / 节点任务能力

签发预签名 PUT 上传 URL


### 查询参数

| 参数            | 说明                                       |
| ------------- | ---------------------------------------- |
| `type`        | 槽位用途,例如 `startingImage`、`referenceImage` |
| `jobId`       | 关联的项目 id                                 |
| `contentType` | 将要上传的 MIME 类型,必须在白名单内                    |

### 响应

```json
{
  "status": "success",
  "data": {
    "uploadUrl": "https://…/presigned-put",
    "uploadHeaders": { "Content-Type": "image/png" }
  }
}
```

随后以 **HTTP PUT** 把文件体直传到 `uploadUrl`,并原样携带 `uploadHeaders` 中的每一个头:

```bash
curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @start-frame.png
```

:::info 节点侧用法
GPU 节点在完成任务时也调用本端点申请**产物上传 URL**:无凭证,凭任务能力 `(jobId, imageId)` 申请 `complete` 槽位。这是协议面的细节,见[节点协议](https://docs.reelway.ai/run-a-worker/worker-protocol.md)。
:::

## `GET /v1/image/downloadUrl`


GEThttps://rcn.reelway.ai/v1/image/downloadUrl鉴权:凭证

签发产物或输入的下载 URL


### 查询参数

| 参数                | 说明                                                     |
| ----------------- | ------------------------------------------------------ |
| `type`            | 槽位,产物用 `complete`                                      |
| `jobId`           | 项目 id                                                  |
| `imageId`(或 `id`) | 作业的 `imgID`(来自 `jobResult` 帧或 `GET /v2/projects/{id}`) |

### 响应

```json
{ "status": "success", "data": { "downloadUrl": "https://…/presigned-get" } }
```

对象不存在返回 `404`。`complete` 槽位按登记的产物解析对象键,因此只能在 `jobResult` 之后调用。

## `GET /v1/media/uploadUrl` 与 `GET /v1/media/downloadUrl`


GEThttps://rcn.reelway.ai/v1/media/uploadUrl鉴权:凭证 / 节点任务能力

同 image 组,内容类型为音频/视频白名单



GEThttps://rcn.reelway.ai/v1/media/downloadUrl鉴权:凭证

同 image 组,media 侧槽位


参数与响应与 `image` 组完全一致。视频产物(MiniMax H3)与音频产物(CosyVoice 3)走本组。

## URL 有效期与安全

- `jobResult` 帧里的 `resultUrl` 与本页签发的 `downloadUrl` 均为**48 小时**有效的签名 URL;过期后重新调用 `downloadUrl` 即可再次签发。
- 签名 URL 可被任何持有者访问:不要写进日志或分享到公共渠道;需要公开分发请转存到自有存储。
- 上传 URL 仅接受一次 PUT 且绑定 `contentType`;类型不符会被存储侧拒绝。

## 错误

| HTTP | 错误码    | 含义                                        |
| ---- | ------ | ----------------------------------------- |
| 400  | —      | 缺少 `jobId` / `type`,或 `contentType` 不在白名单 |
| 401  | `101`  | 凭证无效                                      |
| 404  | —      | 对象不存在(产物尚未上传,或 `imageId` 错误)              |
| 500  | `1004` | 对象存储故障,可重试                                |