> ## 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.

# 提交工作流运行

> 提交一次工作流运行任务

# 提交工作流运行

提交一次工作流运行任务。系统会先按工作流报价进行预扣费，任务完成后按实际消耗结算，多退少补以实际账单为准。

<Warning>
  `idempotency_key` 必填。同一用户、相同工作流、相同幂等键的重复请求会返回同一笔运行记录，避免网络重试造成重复提交。
</Warning>

<Info>
  图片、视频、音频等普通媒体字段直接传资源字符串：公网 URL、`data:image/<format>;base64,<data>` 或 `asset://asset_xxx`。需要声明素材角色或在提示词中引用素材时，使用 `{ "uri": "...", "role": "reference_image", "label": "人物A" }`。本地文件建议先调用 [上传工作流资源](/api-reference/workflow/assets-upload)，再把返回的 `asset_uri` 字段值放入 `inputs`。
</Info>

## 请求参数

<ParamField body="workflow_id" type="string" required>
  工作流 ID
</ParamField>

<ParamField body="revision_id" type="string">
  工作流版本 ID。建议使用详情接口返回的 `revision_id`，不传时使用当前已发布版本
</ParamField>

<ParamField body="inputs" type="object">
  工作流输入参数。key 来自详情接口的 `editable_parameter_manifest`
</ParamField>

<ParamField body="inputs.contains_real_person_material" type="boolean">
  历史 Seedance 视频工作流兼容参数。新接入外部视频模型时，建议使用 [外部模型任务接口](/api-reference/model-runs/video-submit)。
</ParamField>

<ParamField body="idempotency_key" type="string" required>
  幂等键，由调用方生成。建议使用业务订单号、请求流水号或 UUID
</ParamField>

<ParamField body="accept_external_cost_risk" type="boolean">
  是否确认接受第三方模型费用风险。工作流可能产生外部模型费用时应传 `true`
</ParamField>

## 响应参数

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

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

<ResponseField name="data" type="object">
  运行提交结果

  <Expandable title="data">
    <ResponseField name="run_order_id" type="string">
      运行订单 ID。后续查询运行记录、进度、日志和输出均使用此 ID
    </ResponseField>

    <ResponseField name="workflow_id" type="string">
      工作流 ID
    </ResponseField>

    <ResponseField name="revision_id" type="string">
      本次运行使用的版本 ID
    </ResponseField>

    <ResponseField name="quote_currency" type="string">
      报价币种
    </ResponseField>

    <ResponseField name="quote_amount" type="string">
      预扣费参考报价
    </ResponseField>

    <ResponseField name="freeze_status" type="string">
      预扣费状态，如 `frozen`
    </ResponseField>

    <ResponseField name="run_status" type="string">
      运行状态，如 `queued`、`running`、`succeeded`、`failed`
    </ResponseField>

    <ResponseField name="task_id" type="string">
      执行引擎任务 ID
    </ResponseField>

    <ResponseField name="prompt_id" type="string">
      执行引擎 prompt ID
    </ResponseField>

    <ResponseField name="billing_run_id" type="string">
      计费运行 ID
    </ResponseField>

    <ResponseField name="idempotent_replay" type="boolean">
      是否为幂等重放结果
    </ResponseField>
  </Expandable>
</ResponseField>

## 错误响应

当提交阶段调用执行引擎失败时，接口会返回一个简单原因和详细错误信息，便于定位输入参数、文件获取、实例调度或工作流执行器问题。

<ResponseField name="code" type="integer">
  非 `0` 表示失败
</ResponseField>

<ResponseField name="msg" type="string">
  简单失败原因
</ResponseField>

<ResponseField name="data.error" type="object">
  执行引擎错误详情

  <Expandable title="data.error">
    <ResponseField name="reason" type="string">
      简单失败原因，与 `msg` 保持一致
    </ResponseField>

    <ResponseField name="detail" type="string">
      详细错误信息
    </ResponseField>

    <ResponseField name="engine_code" type="string">
      执行引擎返回的错误码
    </ResponseField>

    <ResponseField name="status_code" type="integer">
      执行引擎 HTTP 状态码
    </ResponseField>
  </Expandable>
</ResponseField>

## 代码示例

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

  url = "https://www.chenyu.cn/api/open/v2/workflow/run/submit"
  headers = {
      "Authorization": "Bearer your_api_key",
      "Content-Type": "application/json"
  }
  payload = {
      "workflow_id": "wf_861ef31e94dcfb10e6e7",
      "revision_id": "wfr_f9f2a2dcb99d73b0c3aa",
      "inputs": {
          "generation_category": "reference_to_video",
          "model": "doubao-seedance-2-0-fast-260128",
          "prompt": "@人物A cinematic portrait video",
          "images": [
              {
                  "uri": "asset://asset_reference_image",
                  "label": "人物A",
                  "role": "reference_image"
              }
          ],
          "contains_real_person_material": true,
          "resolution": "720p",
          "duration": "5"
      },
      "idempotency_key": str(uuid.uuid4()),
      "accept_external_cost_risk": False
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');
  const crypto = require('crypto');

  axios.post('https://www.chenyu.cn/api/open/v2/workflow/run/submit', {
    workflow_id: 'wf_861ef31e94dcfb10e6e7',
    revision_id: 'wfr_f9f2a2dcb99d73b0c3aa',
    inputs: {
      generation_category: 'reference_to_video',
      model: 'doubao-seedance-2-0-fast-260128',
      prompt: '@人物A cinematic portrait video',
      images: [{
        uri: 'asset://asset_reference_image',
        label: '人物A',
        role: 'reference_image'
      }],
      contains_real_person_material: true,
      resolution: '720p',
      duration: '5'
    },
    idempotency_key: crypto.randomUUID(),
    accept_external_cost_risk: false
  }, {
    headers: {
      Authorization: 'Bearer your_api_key',
      'Content-Type': 'application/json'
    }
  }).then((response) => {
    console.log(response.data);
  });
  ```

  ```curl cURL theme={null}
  curl -X POST "https://www.chenyu.cn/api/open/v2/workflow/run/submit" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "workflow_id": "wf_861ef31e94dcfb10e6e7",
      "revision_id": "wfr_f9f2a2dcb99d73b0c3aa",
      "inputs": {
        "generation_category": "reference_to_video",
        "model": "doubao-seedance-2-0-fast-260128",
        "prompt": "@人物A cinematic portrait video",
        "images": [
          {
            "uri": "asset://asset_reference_image",
            "label": "人物A",
            "role": "reference_image"
          }
        ],
        "contains_real_person_material": true,
        "resolution": "720p",
        "duration": "5"
      },
      "idempotency_key": "run_20260508_001",
      "accept_external_cost_risk": false
    }'
  ```
</CodeGroup>

## 提示词引用素材

历史 Seedance 工作流或外部视频模型工作流支持在 `inputs` 的资源对象中传 `label`，并在 `inputs.prompt` 中使用 `@label` 指向该素材。

```json theme={null}
{
  "workflow_id": "wf_xxx",
  "revision_id": "wfr_xxx",
  "idempotency_key": "run_20260613_ref_001",
  "inputs": {
    "generation_category": "reference_to_video",
    "model": "doubao-seedance-2-0-fast-260128",
    "prompt": "@阿九 携手 @沈渡 跳舞",
    "images": [
      {
        "uri": "asset://asset_a252553f9364ad0fa635cb7c48793491",
        "label": "阿九",
        "role": "reference_image"
      },
      {
        "uri": "asset://asset_cf7584e3e836a2b3ee65ef072a71fdd6",
        "label": "沈渡",
        "role": "reference_image"
      }
    ],
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9"
  }
}
```

说明：

* `label` 建议直接写显示名，例如 `阿九`，不需要带 `@`
* `prompt` 中写 `@阿九`，也兼容 `{{阿九}}` 和 `{{ 阿九 }}`
* 同一个请求里 `label` 不能重复
* 服务端会把自定义标签绑定到当前请求中的资源顺序，例如图片会映射为上游需要的 `@图1`、`@图2`

## 响应示例

```json theme={null}
{
  "code": 0,
  "msg": "提交成功",
  "data": {
    "run_order_id": "wfrun_314ff7d8b7a5beff1388",
    "workflow_id": "wf_861ef31e94dcfb10e6e7",
    "revision_id": "wfr_f9f2a2dcb99d73b0c3aa",
    "quote_currency": "CNY",
    "quote_amount": "0.03000000",
    "freeze_status": "frozen",
    "run_status": "queued",
    "task_id": "task_1778147626528703038_eb84d292e0851c08",
    "prompt_id": "prompt_1778147626528707364_b0c0687e49d1f72f",
    "billing_run_id": "wfbill_1778147626528703038",
    "idempotent_replay": false
  }
}
```

## 错误示例

```json theme={null}
{
  "code": 1,
  "msg": "Workflow input content is invalid.",
  "data": {
    "error": {
      "reason": "Workflow input content is invalid.",
      "detail": "input n4_video must be an uploaded file URL or file id",
      "engine_code": "INVALID_WORKFLOW_INPUT",
      "status_code": 400
    }
  }
}
```