Copy.ai 工作流 API 快速上手：密钥、运行与 Webhook 全流程

Copy.ai 的工作流 API 解决的是一个很具体的对接问题：把在 Copy.ai 平台上已经搭好的工作流，直接当成一个可编程的接口来调用。你不需要在业务系统里重新实现一遍提示词逻辑，只要拿到工作流的 ID，就能从自己的服务端触发它运行，再取回运行结果。它适合需要把内容生成、数据处理这类流程嵌进自有产品、内部工具或自动化管线的开发者，也适合想用脚本批量跑工作流的团队。如果你只是想先了解这个工具本身，可以看 Copy.ai 的工具页；下面讲的是 API 层面的接入方式。

这套 API 覆盖三类能力：触发工作流运行、查询某次运行的详情与状态、注册 Webhook 以便在工作流事件（例如运行完成）发生时收到推送。所有请求都走同一个域名，鉴权方式统一，端点数量不多，整体接入成本较低。

准备工作

在写第一行请求代码之前，需要先确认三件事：一个可用的 Copy.ai 账号、一个 API Key、以及一个已经存在于工作区里的工作流。

账号与工作区

API Key 是在 Copy.ai 的账号设置里创建的，因此你需要能够登录 Copy.ai。工作流本身也要先在平台上搭好——API 只是触发它，不会替你创建工作流。Webhook 的注册范围与工作区相关：如果不指定工作流 ID，收到的事件会覆盖工作区内的所有工作流，这一点在后面的 Webhook 部分会再说明。

创建 API Key

API Key 的创建路径如下：

1. 登录 Copy.ai。
2. 在左侧边栏点击 Configuration。
3. 点击 View API Keys。
4. 点击页面右上角的 Create。
5. 填写表单字段。
6. 点击 Create 完成创建。
7. 复制生成的 API Key 并妥善保存。

创建表单包含三个字段：

字段	说明
Key Name	为该 API Key 起一个唯一的名称，便于日后识别用途。
User	选择一个用户。此项为可选项。
Expiry Date	选择有效期：Never 表示密钥永不过期，可长期使用；12 Months 表示 12 个月后密钥失效、无法再使用，适合只在有限时间内使用的场景。

务必在创建后立即复制并保存 API Key。密钥创建完成后将无法再次查看。

鉴权方式

所有 API 路由都通过 https://api.copy.ai/api/ 访问，并且必须携带 x-copy-ai-api-key 请求头。请求头形如：

x-copy-ai-api-key <api key goes here>

也就是说，无论调用哪个端点，鉴权信息都放在这个自定义请求头里，而不是放在 URL 参数或请求体中。把密钥写进代码时，建议通过环境变量注入，不要硬编码进仓库。

端点总览

接入前先建立一张端点地图，有助于判断某个需求该用哪个接口。可用端点如下：

方法	端点	说明
POST	/webhook	注册一个 Webhook
GET	/webhook/{webhook_id}	获取指定的 Webhook
GET	/webhook	获取全部 Webhook
DELETE	/webhook/{webhook_id}	删除一个 Webhook
POST	/workflow/{workflow_id}/run	启动一次工作流运行
GET	/workflow/{workflow_id}/run/{run_id}	获取指定的工作流运行
GET	/workflow/{workflow_id}/run/	获取全部工作流运行

可以看到，Webhook 相关端点自成一组，工作流运行相关端点自成一组。前者用于配置通知渠道，后者用于实际执行与查询。

操作步骤

第一步：找到 Workflow ID

要通过 API 使用某个工作流，必须先拿到它的 Workflow ID。获取方式是在 Copy.ai 中打开该工作流，然后：

1. 选中目标工作流。
2. 点击 API 标签页。
3. 在 API ENDPOINT 字段中查看完整 URL。

Workflow ID 位于该 URL 的末尾，以 WFCG- 开头。例如：

https://api.copy.ai/api/workflow/WCFG-6db59f06-43gh-4ca0-943d-9831cac5ce7b/run

在这个例子里，WCFG-6db59f06-43gh-4ca0-943d-9831cac5ce7b 就是 Workflow ID。后续所有针对该工作流的运行请求，都要把这个 ID 填进 URL 的 {workflow_id} 位置。

第二步：启动一次工作流运行

启动运行的方式是向 https://api.copy.ai/api/workflow/<workflow_id>/run 发送 POST 请求，请求体是一个 JSON 对象，包含本次运行的起始变量。示例：

POST https://api.copy.ai/api/workflow/<workflow_id>/run
{
  "startVariables": {
    "Input 1": "Inputs vary depending on the workflow used.",
    "Input 2": "The best way to see an example is to try it!"
  },
  "metadata": {
    "api": true
  }
}

请求体里有两个顶层字段：

• startVariables：本次运行的起始变量。键名与工作流定义的输入项一一对应，具体有哪些输入、叫什么名字，取决于你使用的是哪个工作流。上面示例中的 Input 1、Input 2 只是占位，实际键名需要按工作流定义填写。
• metadata：附加的元数据对象。示例中传入了 {"api": true}，用于标记这次运行来自 API 调用。

调用成功后返回的响应形如：

{
  "status": "success",
  "data": {
    "id": "<run_id>"
  }
}

响应中的 id 就是本次运行的 Run ID。它有两个用途：一是用来跟踪这次运行的进度，二是当运行完成时，Webhook 请求里也会带上这个 ID。因此拿到之后应当保存下来。

第三步：跟踪或轮询运行进度

要跟踪某次运行，向 https://api.copy.ai/api/workflow/<workflow_id>/run/<run_id> 发送 GET 请求。示例：

GET https://api.copy.ai/api/workflow/<workflow_id>/run/<run_id>
{
  "status": "success",
  "data": {
    "id": "<run_id>",
    "input": {
      "Input 1": "Inputs vary depending on the workflow used.",
      "Input 2": "The best way to see an example is to try it!"
    },
    "status": "PROCESSING",
    "output": {
      "Output 1": "Outputs vary depending on the workflow used.",
      "Output 2": "The best way to see an example is to try it!"
    },
    "createdAt": "2022-11-18T20:30:07.434Z"
  }
}

返回的 data 对象包含以下字段：

字段	说明
id	本次运行的 Run ID。
input	本次运行的输入变量，即启动时传入的 startVariables。
status	运行状态。示例中为 PROCESSING，表示仍在处理中。
output	运行输出。输出项的键名同样取决于所用工作流。
createdAt	运行创建时间，ISO 8601 格式。

关于运行状态有哪些取值、运行详情还包含哪些信息，可参考 Get Workflow Run 相关说明。轮询的典型做法是：启动运行拿到 Run ID 后，按固定间隔重复调用这个 GET 端点，直到 status 变为 COMPLETE，再读取 output。如果不想轮询，就改用下一节的 Webhook。

第四步：注册 Webhook

注册 Webhook 的方式是向 https://api.copy.ai/api/webhook 发送 POST 请求，请求体是一个 JSON 对象，包含你的 Webhook URL、想接收的事件类型，以及可选的工作流 ID。示例：

POST https://api.copy.ai/api/webhook
{
  "url": "https://mywebsite.com/webhook",
  "eventType": "workflowRun.completed",
  "workflowId": "<my-workflow-id>"
}

三个字段的含义：

• url：接收事件推送的地址，需要是你自己服务端可公开访问的端点。
• eventType：要订阅的事件类型。示例中订阅的是 workflowRun.completed，即工作流运行完成事件。
• workflowId：可选字段，用于把订阅限定到某个具体工作流。

如果请求体中没有包含工作流 ID，你将收到该工作区内所有工作流的事件。

注册成功后的响应形如：

{
  "status": "success",
  "data": {
    "id": "<id of webhook>",
    "url": "https://mywebsite.com/webhook",
    "eventType": "workflowRun.completed",
    "workflowId": "<my-workflow-id>"
  }
}

响应中的 id 是 Webhook 自身的标识，后续可以用它查询或删除该 Webhook。

第五步：处理运行完成事件

当运行完成时，状态会变为 COMPLETE，同时系统会向所有订阅了该工作流完成事件的 Webhook 地址发送一个 POST 请求。请求体示例：

{
  "type": "workflowRun.completed",
  "workflowRunId": "<run_id>",
  "workflowId": "<workflow_id>",
  "result": {
    "Output 1": "Outputs vary depending on the workflow used.",
    "Output 2": "The best way to see an example is to try it!"
  },
  "metadata": {},
  "credits": 2
}

这个载荷里几个字段值得注意：

• type：事件类型，与注册时订阅的 eventType 对应。
• workflowRunId：本次运行的 Run ID，与启动运行时返回的 id 一致，可用来把推送与之前的请求对应起来。
• workflowId：产生该事件的工作流 ID。
• result：运行输出结果，结构与查询运行详情时的 output 一致。
• metadata：元数据对象。
• credits：本次运行消耗的额度数。示例中为 2。

接收端应当先做幂等处理再落库，因为推送可能重复到达；同时建议快速返回 2xx，把耗时的后续处理放到异步任务里。

一个完整示例

下面把上面的步骤串成一条最小可跑通的链路：注册完成事件 Webhook，触发一次运行，等待推送，读取结果。

第 1 步：注册 Webhook

POST https://api.copy.ai/api/webhook
x-copy-ai-api-key: <api key goes here>
Content-Type: application/json

{
  "url": "https://mywebsite.com/webhook",
  "eventType": "workflowRun.completed",
  "workflowId": "WCFG-6db59f06-43gh-4ca0-943d-9831cac5ce7b"
}

返回的 data.id 记下来，这是 Webhook ID。

第 2 步：启动运行

POST https://api.copy.ai/api/workflow/WCFG-6db59f06-43gh-4ca0-943d-9831cac5ce7b/run
x-copy-ai-api-key: <api key goes here>
Content-Type: application/json

{
  "startVariables": {
    "Input 1": "Inputs vary depending on the workflow used.",
    "Input 2": "The best way to see an example is to try it!"
  },
  "metadata": {
    "api": true
  }
}

响应中返回 data.id，即 Run ID。

第 3 步：轮询确认状态（可选）

GET https://api.copy.ai/api/workflow/WCFG-6db59f06-43gh-4ca0-943d-9831cac5ce7b/run/<run_id>
x-copy-ai-api-key: <api key goes here>

如果此时 status 仍是 PROCESSING，说明还在处理中；变为 COMPLETE 后即可读取 output。

第 4 步：接收完成推送

运行完成后，https://mywebsite.com/webhook 会收到如下 POST 请求：

{
  "type": "workflowRun.completed",
  "workflowRunId": "<run_id>",
  "workflowId": "WCFG-6db59f06-43gh-4ca0-943d-9831cac5ce7b",
  "result": {
    "Output 1": "Outputs vary depending on the workflow used.",
    "Output 2": "The best way to see an example is to try it!"
  },
  "metadata": {},
  "credits": 2
}

用 workflowRunId 与第 2 步拿到的 Run ID 比对，即可确认这是哪一次运行的结果。

第 5 步：清理

如果这个 Webhook 只是临时使用，可以用 DELETE 请求移除：

DELETE https://api.copy.ai/api/webhook/<webhook_id>
x-copy-ai-api-key: <api key goes here>

注意事项

• API Key 只显示一次。创建完成后无法再次查看密钥内容，必须当场复制并保存到安全位置。如果丢失，只能重新创建。
• 有效期需要提前规划。创建密钥时可选 Never 或 12 Months。选择 12 个月的密钥到期后会失效、无法继续使用，适合有明确使用期限的场景；长期运行的服务则应评估是否选择永不过期。
• 鉴权头是必需的。所有路由都要求 x-copy-ai-api-key 请求头，缺少该头会导致请求无法通过鉴权。
• 输入输出键名随工作流而变。startVariables 的键名、output 与 result 的键名都取决于具体工作流，示例中的 Input 1、Output 1 只是占位。接入前应先确认目标工作流定义了哪些输入项。
• 不指定工作流 ID 会扩大订阅范围。注册 Webhook 时如果省略 workflowId，会收到工作区内所有工作流的事件，而不是某一个工作流的事件。在多工作流环境下，这可能导致接收端需要额外做过滤。
• 运行状态需要判断。启动运行后返回的只是 Run ID，并不代表已经完成。示例中查询到的状态为 PROCESSING，完成时才会变为 COMPLETE。轮询逻辑必须处理中间状态。
• 运行会消耗额度。完成事件的载荷中包含 credits 字段，示例中为 2，表示该次运行消耗的额度数。批量触发前应评估额度消耗。
• 价格、配额与可用性以官网当前信息为准。本文只描述接口的调用方式，具体套餐限制、额度规则与区域可用情况请以 Copy.ai 官网的最新说明为准。