> ## Documentation Index
> Fetch the complete documentation index at: https://chenyu.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 上传工作流资源

> 上传用于工作流输入的临时资源

# 上传工作流资源

上传图片、视频、音频或文件，生成可在工作流 `inputs` 中使用的临时资源地址。适用于文件较大、需要复用、或不方便直接暴露公网 URL 的场景。

<Info>
  上传成功后使用返回的 `asset_uri` 字段值，例如 `asset://asset_xxx`。提交工作流时可以直接把这个字符串放入 `inputs`。需要声明素材角色或在提示词里引用素材时，使用 `{ "uri": "...", "role": "...", "label": "..." }` 对象。临时资源默认 48 小时有效。
</Info>

## 请求参数

请求类型为 `multipart/form-data`。

<ParamField body="file" type="file" required>
  要上传的本地文件，单个文件最大 100MB
</ParamField>

<ParamField body="media_type" type="string">
  资源类型。常用值：`image`、`video`、`audio`、`file`。不传时服务端会根据文件类型推断
</ParamField>

<ParamField body="purpose" type="string">
  资源用途。当前对外接口仅支持 `temp_input`，不传时默认 `temp_input`
</ParamField>

<ParamField body="ttl_hours" type="integer">
  临时资源有效小时数。不传时默认 48 小时
</ParamField>

## 响应参数

<ResponseField name="code" type="integer">
  响应码，`0` 表示成功
</ResponseField>

<ResponseField name="msg" type="string">
  响应信息
</ResponseField>

<ResponseField name="data" type="object">
  上传后的资源信息

  <Expandable title="data">
    <ResponseField name="asset_id" type="string">
      资源 ID，可用于查询资源状态和访问地址
    </ResponseField>

    <ResponseField name="asset_uri" type="string">
      资源引用地址，提交工作流 `inputs` 时优先使用，例如 `asset://asset_xxx`
    </ResponseField>

    <ResponseField name="url" type="string">
      资源访问地址
    </ResponseField>

    <ResponseField name="content_url" type="string">
      资源内容访问地址，与 `url` 含义一致
    </ResponseField>

    <ResponseField name="signed_url" type="string">
      带签名的临时访问地址
    </ResponseField>

    <ResponseField name="media_type" type="string">
      资源类型，例如 `image`
    </ResponseField>

    <ResponseField name="mime_type" type="string">
      MIME 类型，例如 `image/png`
    </ResponseField>

    <ResponseField name="size_bytes" type="integer">
      文件大小，单位字节
    </ResponseField>

    <ResponseField name="purpose" type="string">
      资源用途，当前为 `temp_input`
    </ResponseField>

    <ResponseField name="persistent" type="boolean">
      是否为长期资源。临时输入资源一般为 `false`
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      临时资源过期时间
    </ResponseField>

    <ResponseField name="status" type="string">
      资源状态。可用状态通常为 `confirmed`
    </ResponseField>
  </Expandable>
</ResponseField>

## 代码示例

<CodeGroup>
  ```python Python theme={null}
  import requests

  url = "https://www.chenyu.cn/api/open/v2/assets"
  headers = {"Authorization": "Bearer your_api_key"}
  files = {"file": open("input.png", "rb")}
  data = {
      "media_type": "image",
      "purpose": "temp_input"
  }

  response = requests.post(url, headers=headers, files=files, data=data)
  asset_uri = response.json()["data"]["asset_uri"]
  print(asset_uri)
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');
  const fs = require('fs');
  const FormData = require('form-data');

  const form = new FormData();
  form.append('file', fs.createReadStream('input.png'));
  form.append('media_type', 'image');
  form.append('purpose', 'temp_input');

  axios.post('https://www.chenyu.cn/api/open/v2/assets', form, {
    headers: {
      Authorization: 'Bearer your_api_key',
      ...form.getHeaders()
    }
  }).then((response) => {
    console.log(response.data.data.asset_uri);
  });
  ```

  ```curl cURL theme={null}
  curl -X POST "https://www.chenyu.cn/api/open/v2/assets" \
    -H "Authorization: Bearer your_api_key" \
    -F "file=@input.png" \
    -F "media_type=image" \
    -F "purpose=temp_input"
  ```
</CodeGroup>

## 响应示例

```json theme={null}
{
  "code": 0,
  "msg": "上传成功",
  "data": {
    "asset_id": "asset_38d2ff7769fb3b7267039941547e6a78",
    "asset_uri": "asset://asset_38d2ff7769fb3b7267039941547e6a78",
    "url": "https://www.chenyu.team/assets/asset_38d2ff7769fb3b7267039941547e6a78/content",
    "content_url": "https://www.chenyu.team/assets/asset_38d2ff7769fb3b7267039941547e6a78/content",
    "signed_url": "https://www.chenyu.team/assets/asset_38d2ff7769fb3b7267039941547e6a78/content?expires=1781295600&signature=xxxx",
    "media_type": "image",
    "mime_type": "image/png",
    "size_bytes": 102400,
    "purpose": "temp_input",
    "persistent": false,
    "expires_at": "2026-06-16T12:00:00+08:00",
    "status": "confirmed",
    "original_filename": "input.png"
  }
}
```

## 在工作流中使用

先查询 [工作流详情](/api-reference/workflow/market-info)。当 `editable_parameter_manifest[].value_type` 表示图片、视频、音频或文件输入时，在 `inputs` 中使用该条目的 `name` 作为 key，参数值支持三种资源字符串：

```json theme={null}
{
  "n10_image": "https://example.com/input.png"
}
```

```json theme={null}
{
  "n10_image": "data:image/png;base64,iVBORw0KGgo..."
}
```

```json theme={null}
{
  "n10_image": "asset://asset_38d2ff7769fb3b7267039941547e6a78"
}
```

本地文件优先使用本接口返回的 `asset_uri`。参数名、必填规则和文件类型均以当前工作流详情返回的 manifest 为准，完整说明见 [`editable_parameter_manifest` 输入参数清单](/api-reference/workflow/market-info)。


## OpenAPI

````yaml upload-assets.openapi.json POST /api/open/v2/assets
openapi: 3.0.1
info:
  title: 晨羽智云资源上传接口
  version: 1.0.0
servers: []
security: []
paths:
  /api/open/v2/assets:
    post:
      summary: 上传工作流资源
      description: 上传用于工作流输入的临时资源。请求必须使用 multipart/form-data。
      operationId: uploadWorkflowAsset
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AssetUploadRequest'
      responses:
        '200':
          description: 上传结果
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowAssetUploadResponse'
      security:
        - bearerAuth: []
      servers:
        - url: https://www.chenyu.cn
          description: 生产环境
components:
  schemas:
    AssetUploadRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          description: 要上传的本地文件，单个文件最大 100MB
        media_type:
          type: string
          enum:
            - image
            - video
            - audio
            - file
          description: 资源类型。不传时服务端根据文件类型推断
        purpose:
          type: string
          enum:
            - temp_input
          default: temp_input
          description: 资源用途，当前仅支持 temp_input
        ttl_hours:
          type: integer
          minimum: 1
          default: 48
          description: 临时资源有效小时数
    WorkflowAssetUploadResponse:
      type: object
      properties:
        code:
          type: integer
          description: 响应码，0 表示成功
        msg:
          type: string
          description: 响应信息
        data:
          $ref: '#/components/schemas/Asset'
      required:
        - code
        - msg
        - data
    Asset:
      type: object
      properties:
        id:
          type: string
          description: 资源 ID；大模型网关响应包含此字段
        asset_id:
          type: string
          description: 资源 ID
        asset_uri:
          type: string
          example: asset://asset_38d2ff7769fb3b7267039941547e6a78
          description: 提交工作流或模型请求时使用的资源引用地址
        url:
          type: string
          format: uri
          description: 资源访问地址
        content_url:
          type: string
          format: uri
          description: 资源内容访问地址
        signed_url:
          type: string
          format: uri
          description: 带签名的临时访问地址
        media_type:
          type: string
          description: 资源类型
        mime_type:
          type: string
          description: MIME 类型
        size_bytes:
          type: integer
          format: int64
          description: 文件大小，单位字节
        purpose:
          type: string
          description: 资源用途
        persistent:
          type: boolean
          description: 是否为长期资源
        expires_at:
          type: string
          format: date-time
          description: 临时资源过期时间
        status:
          type: string
          description: 资源状态
        original_filename:
          type: string
          description: 原始文件名
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API Key，格式：Bearer your_api_key

````