开源视频处理神器 No-Code Architects Toolkit 实战全攻略

No-Code Architects Toolkit (NCA Toolkit) 是一个开源的、免费的媒体处理 API 工具包。它整合了常见的音视频处理功能，旨在帮助内容创作者、自动化工作流开发者等，在无需支付高额订阅费用的情况下完成各种媒体处理任务。NCA Toolkit 基于 Python/Flask 实现，可通过 Docker 部署在本地或云端服务器上，自行托管以保障成本可控和数据安全。

本教程旨在为中文用户提供一份关于 no-code-architects-toolkit GitHub 项目的完整深度指南。它特别关注如何将此工具包集成到 n8n 和 Make.com 等流行的无代码/低代码自动化平台中，从而帮助用户大幅降低 API 订阅成本，并显著提升媒体相关工作流程的自动化效率。无论您是内容创作者、AI 自动化爱好者，还是希望优化业务流程的企业用户，本教程都将为您提供清晰、实用且易于操作的指导。

注意这篇教程主要针对概念原理进行讲解所，具体请求参数详情请参考官方文档，地址如下：

https://github.com/stephengpope/no-code-architects-toolkit

手把手安装教程请访问如下地址：

https://xiangyugongzuoliu.com/google-cloud-nocode-architects-toolkit-guide-zh/

目录隐藏

5 附录：完整的 curl 示例合集与参数表格

项目总览与应用场景说明

在深入了解 No-Code Architects Toolkit (后文简称 NCA Toolkit) 的各项具体功能之前，首先对其核心定位、主要特性、目标用户以及典型的应用场景进行概述，这将有助于您快速把握该项目的核心价值。

1.1. 项目核心定位与价值NCA Toolkit 的核心定位非常明确：它是一个 100% 免费的开源 API 工具包。其主要目标是通过将一系列常见的 API 功能，特别是围绕媒体处理的复杂操作，整合到一个统一且免费的 API 服务中，从而帮助用户彻底摆脱或显著减少对多种昂贵商业 API 服务的月度订阅依赖 。在当前的数字化浪潮中，无论是个人开发者、内容创作团队还是中小型企业，在构建自动化流程时，往往需要调用各种第三方 API 服务。例如，视频转录可能依赖 A 服务，视频格式转换可能依赖 B 服务，而图片生成视频又可能需要 C 服务。这些服务通常采用订阅制收费，日积月累，API 订阅费用会成为一笔不小的开支。NCA Toolkit 正是针对这一痛点而生，它可以有效地替代市面上一些知名的付费服务，如 OpenAI 的部分功能（例如基于 Whisper 的语音转录）、Creatomate、ZeroCodeKit、Cloud Convert、JSON2Video、Placid 等。该工具包基于 Python 语言和 Flask Web 框架构建，确保了其轻量级和可扩展性。这种定位的深远意义在于，NCA Toolkit 不仅仅是提供了一套免费的工具，更重要的是，它为用户提供了一种极具成本效益的媒体处理与自动化整合方案。许多用户可能正为视频处理、音频转录、格式转换等不同需求分别支付多个订阅费用，而 NCA Toolkit 的出现，使得他们有机会将这些原本分散的付费服务整合起来，通过部署和调用一个自有的、免费的工具包来满足多种媒体处理需求。这种转变，从依赖多个“单一工具替代品”到构建一个统一的“媒体处理中枢”，对于那些希望大幅削减运营开支、简化技术栈管理并提升工作流自主性的团队和个人而言，具有重塑其自动化生态系统的潜力。它让用户不再受制于不同服务商的定价策略和功能限制，从而在实现高级自动化的道路上拥有更多的主动权和灵活性。
1.2. 主要功能概览 NCA Toolkit 以其功能覆盖的广度著称，提供了一系列强大的媒体处理能力，几乎涵盖了内容创作和自动化流程中常见的媒体操作需求。以下是其主要功能的概览：
- 视频处理：
  - 视频加字幕： 支持为视频添加可定制样式的字幕，包括字体、颜色、位置等。
  - 视频拼接： 将多个独立的视频片段合并成一个完整的视频文件。
  - 提取缩略图： 从视频的指定时间点抓取一帧作为缩略图。
  - 视频剪辑： 精确剪切视频的特定片段，或去除视频首尾多余部分。
  - 视频分割： 将一个长视频按照指定的时间点分割成多个短视频片段。
- 音频处理：
  - 音频拼接： 合并多个音频文件为一个。
  - 音频叠加/混音： 将不同的音轨（如背景音乐、旁白）与视频或主音轨混合。
- 图像处理：
  - 静态图片转视频： 将单张或多张静态图片转换为动态视频，可设置时长、转场和动态效果（如Ken Burns）。
- 媒体转换：
  - 通用格式转换： 支持多种媒体格式之间的相互转换，例如 MOV 转 MP4，AVI 转 WebM 等。
  - 提取/转换为 MP3 ： 从视频文件中提取音轨并保存为 MP3，或将其他音频格式转换为 MP3 。
- 内容分析与提取：
  - 音视频转录/翻译： 将音频或视频中的语音内容转换为文本，并支持翻译到其他语言（通常是翻译到英文）。
  - 静音检测： 识别媒体文件中的静音片段，返回其开始和结束时间。
  - 提取媒体元数据： 获取媒体文件的详细信息，如编码格式、分辨率、帧率、时长、比特率等。
- 高级处理：
  - FFmpeg 命令封装： 这是 NCA Toolkit 的一个核心亮点。它提供了一个接口，允许用户直接执行自定义的 FFmpeg 命令。虽然 NCA Toolkit 提供了许多预设的视频和音频操作端点，但这些预设功能可能无法覆盖所有细致入微或高度定制化的媒体处理需求。ffmpeg/compose 端点的存在，赋予了用户近乎无限的灵活性。FFmpeg 本身是一个极其强大的多媒体处理库，通过这个端点，用户可以利用 FFmpeg 的全部功能来实现复杂的滤镜、叠加、编码参数调整等操作，而不仅仅局限于 NCA Toolkit 预设的几个简单功能。这使得 NCA Toolkit 从一个“固定功能集”的 API，一跃成为一个可被高级用户深度定制的媒体处理引擎。
- 代码执行：
  - 远程执行 Python 代码： 允许用户提交 Python 代码片段到 NCA Toolkit 服务器执行，并获取返回结果。这为在自动化流程中嵌入自定义逻辑提供了极大便利。
- 云存储集成：
  - 虽然 NCA Toolkit 主要处理媒体文件，但它也需要与云存储服务进行交互，以上传处理后的结果或下载源文件。它支持与主流云存储的集成，如 Google Drive, Amazon S3, Google Cloud Storage, Dropbox 等。特别是提到了针对 Amazon S3 的直接上传功能。
- 工具集实用程序：
  - API 密钥认证： 验证 API 请求的合法性。
  - API 安装测试： 用于检查 NCA Toolkit 服务是否已正确部署并正常运行。
  - 任务状态查询： 对于耗时较长的异步操作（如大型视频处理），可以查询任务的执行状态。
这些功能的广度是 NCA Toolkit 的核心竞争力之一。用户可能最初因为一个特定的需求（例如视频加字幕）而被吸引，但在使用过程中会发现，这个工具包能够解决他们在媒体处理和自动化方面遇到的更多问题，从而真正实现“一个工具包满足多种需求”的目标。
1.3. 适用人群 NCA Toolkit 的设计考虑了广泛的用户群体，其目标受众包括：
- 企业： 尤其是那些希望通过自动化来简化运营流程、降低 IT 成本的中小型企业。
- 内容创作者： 包括视频博主、播客主、社交媒体运营者等，他们需要高效处理大量媒体内容，但预算可能有限。
- 开发者： 寻求一个免费、功能强大且整合了多种媒体处理能力的 API，用于构建自己的应用程序或服务。
- 教练与咨询顾问： 他们可能需要为客户创建教学视频、播客等内容，或帮助客户搭建自动化系统。
- AI 自动化机构： 利用 NCA Toolkit 为客户提供更具成本效益的媒体自动化解决方案。
- 社交媒体营销机构： 批量处理和优化用于社交媒体发布的视频和图片内容。
- SaaS 初创公司创始人： 在产品早期，可以使用 NCA Toolkit 快速实现媒体处理相关功能，降低初期研发和运营成本。值得特别指出的是，尽管开发者是 NCA Toolkit 的重要目标用户之一，但该项目的创建者 Stephen G. Pope 的许多公开内容、社区推广活动，以及本教程的用户查询本身都明确指向了 NCA Toolkit 在 n8n 和 Make.com 等无代码/低代码自动化平台上的应用。这表明，无代码/低代码平台的用户是 NCA Toolkit 的一个核心用户群体，或者至少是一个快速增长的、极具潜力的用户群体。 近年来，n8n、Make.com (原 Integromat)、Zapier 等平台的普及，极大地降低了自动化的门槛。越来越多的非传统开发者用户（如市场营销人员、运营专员、小型企业主）开始利用这些平台构建复杂的工作流。当这些工作流涉及到媒体文件的处理时（如自动为YouTube视频生成字幕、将博客文章转化为短视频等），他们很快就会遇到媒体处理的复杂性和相关 API 服务的成本问题。NCA Toolkit 恰好填补了这一空白，它与 n8n 或 Make.com 的结合，为这部分用户提供了一个既强大又经济的解决方案。用户可以在熟悉的无代码界面中编排工作流，并通过简单的 HTTP 请求节点调用 NCA Toolkit 的 API 来完成复杂的媒体处理任务，而无需编写大量代码或支付高昂的订阅费。因此，本教程将重点放在 NCA Toolkit 与 n8n 和 Make.com 的集成上，旨在帮助这些用户跨越使用 API 的心理障碍，充分发挥 NCA Toolkit 的威力。
1.4. 典型应用场景 凭借其丰富的功能集，NCA Toolkit 可以在多种实际场景中发挥巨大作用，帮助用户实现媒体处理的自动化和效率提升。以下是一些典型的应用场景：
- 视频内容自动化：
  - 视频转字幕与翻译：自动为上传的视频生成字幕文件（SRT, VTT），或将语音内容转录并翻译成其他语言，提升视频的可访问性和国际化程度。例如，内容创作者可以搭建一个工作流，当新视频上传到云存储时，自动调用 NCA Toolkit 进行转录和字幕生成。
  - 批量生成短视频/社交媒体视频： 将长视频自动剪辑成多个适合社交媒体发布的短片段，或者将一系列图片、文字内容合成为动态视频，并自动调整为不同平台的推荐尺寸（如竖屏的 TikTok/Reels 视频）。
  - 图文转视频： 将博客文章、新闻稿等文本内容，结合相关的图片素材，自动合成为解说视频或演示视频。
- 音频处理与生成：
  - 播客后期自动化：自动拼接播客的各个录音片段，去除长时间的静音，统一音量，并提取音频转录稿用于后续编辑或发布。
  - 语音转文字与内容存档： 将会议录音、采访录音等批量转换为文本格式，便于检索、分析和存档。
  - 配音与音频增强： 虽然 NCA Toolkit 本身不直接生成语音（TTS），但它可以配合外部 TTS 服务使用。例如，先用 TTS 生成配音，然后使用 NCA Toolkit 将配音与视频或背景音乐混合，调整音量等。
- 媒体内容增强与转换：
  - 批量格式转换：将收集到的各种格式的媒体文件（视频、音频、图片）统一转换为标准格式，便于后续处理或在不同设备上播放。
  - 视频画面优化： 自动裁剪视频画面以适应不同平台的显示比例（如从16:9裁剪为9:16），调整视频分辨率、帧率、比特率以优化播放体验或减小文件大小。
  - 为社交媒体优化内容： 自动化生成符合 Instagram, TikTok, YouTube Shorts 等平台要求的视频格式和规格。
- 自动化工作流中的媒体处理节点：
  - 在 n8n 或 Make.com 等无代码/低代码平台构建的自动化流程中，NCA Toolkit 可以作为一个强大的媒体处理“节点”或“模块”。例如，一个工作流可以设计为：当用户在表单中提交一个视频 URL 时，n8n/Make.com 自动触发，调用 NCA Toolkit 下载该视频，然后进行转录，接着将转录结果保存到数据库，并发送通知给相关人员。这些应用场景的共同特点是，它们往往涉及到重复性的、耗时的媒体操作。手动完成这些任务不仅效率低下，而且容易出错。购买专业的软件或订阅多个 API 服务又会带来高昂的成本。NCA Toolkit 的出现，极大地赋能了那些预算有限的小团队、独立内容创作者或希望“敏捷内容创作”的个人。通过将这些任务自动化，NCA Toolkit 帮助他们节省了宝贵的时间和资金，使他们能够更专注于核心的创意和业务本身，从而显著提升生产力和市场竞争力。许多以往需要昂贵工具或大量人工才能完成的任务，现在借助 NCA Toolkit 和无代码平台的结合，变得触手可及。

API 接口逐一解析

NCA Toolkit 提供了一系列 RESTful API 接口来完成不同的媒体处理任务。除特别说明外，这些接口均通过 HTTP POST 方法调用，并需要在请求头中携带预先配置的 API 密钥（x-api-key: <YOUR_API_KEY>）用于认证。每个端点的请求参数和返回结果都有严格的格式验证和清晰的文档说明。下面将按照官方文档列出的路径顺序，分别介绍每个接口的功能、参数和使用示例。

音频处理接口

/v1/audio/concatenate

音频拼接

功能说明： 将多个音频文件按顺序合并为一个音频文件。适用于将背景音乐、语音片段等拼接成完整音频，如播客剪辑合并、有声书章节串接等场景。 请求参数：

audio_urls (数组，必填)：待合并的音频源 URL 列表。数组中的每个元素是一个对象，包含字段：
- audio_url (字符串)：音频文件的直链 URL。支持公网可访问的 HTTP(S) 链接。示例：{“audio_url”: “https://example.com/intro.mp3“}。
id (字符串，可选)：请求的自定义跟踪ID。将在结果中用于标识任务，可用于文件命名等用途。如果不提供，系统会自动生成。
webhook_url (字符串，可选)：用于异步回调通知的URL。如果提供，当音频合并完成后，Toolkit 将向该 URL 发送 POST 请求，携带处理结果。

⚠️ 注意： 提供的各个 audio_url 所指向的音频文件在采样率、声道数等参数上尽量保持一致，以避免合并过程中的潜在格式兼容问题。Toolkit 会尝试自动处理少量差异，但如果相差过大可能导致输出质量下降或失败。

使用示例：

以下示例通过 curl 请求将两段 MP3 音频拼接为一段音频：

curl -X POST "https://<你的服务器地址>/v1/audio/concatenate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "audio_urls": [
          {"audio_url": "https://mybucket.s3.amazonaws.com/part1.mp3"},
          {"audio_url": "https://mybucket.s3.amazonaws.com/part2.mp3"}
        ],
        "id": "podcast-episode-001"
      }'

请求发送后，服务端会立即返回一个 JSON 响应，示例如下：

{
  "code": 200,
  "id": "podcast-episode-001",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "message": "Audio concatenation started"
}

上述响应中包含一个唯一的任务ID (job_id) 用于跟踪合并任务的状态。因为音频合并需要一定时间处理，默认情况下Toolkit采用异步处理：立即返回任务ID，后台继续执行合并操作。可以通过 /v1/toolkit/job/status 查询任务完成情况，或在请求中提供 webhook_url 让服务器处理完毕后主动通知。

如果提供了正确的 webhook_url，响应会更简短，例如：

{ "code": 200, "job_id": "<...>", "message": "Sent to webhook" }

当任务完成时，Toolkit 会向指定 webhook发送包含结果的请求。若未使用webhook，则需要客户端自行轮询任务状态。

可能的错误提示： 如果缺失必需参数（如遗漏 audio_urls），接口将返回 HTTP 400/422 错误以及详细的提示信息。例如漏掉 audio_urls 字段时，可能返回：

{ "code": 422, "error": "'audio_urls' is required" }

此外，audio_url 链接无效或无法访问时，会返回类似 “error”: “Unable to fetch audio file” 的信息。若同时处理的音频数量超出服务器队列限制，可能返回 HTTP 429 错误，提示 “MAX_QUEUE_LENGTH (10) reached”。

代码执行接口

/v1/code/execute/python

远程执行 Python 代码

功能说明： 在服务器端隔离的Python运行环境中执行传入的代码片段，并返回执行结果。这个接口可以替代诸如 OCodeKit 等在线代码运行服务，实现运行自定义 Python 脚本的功能。适用场景包括：在自动化流程中执行数据处理脚本、调用Python库（已预装库）进行计算，或在不暴露本地环境的情况下安全运行第三方代码。

请求参数：

code (字符串，必填)：需要执行的 Python 源代码。可以是完整的脚本段落或函数调用。注意应确保代码是幂等且无恶意的，因为Toolkit会在隔离环境中执行但仍可能影响性能。
id (字符串，可选)：请求ID，用于标记此次代码执行任务。
webhook_url (字符串，可选)：异步执行完毕后的回调URL。如果代码运行可能耗时较长，建议提供此参数以避免轮询等待。

使用示例：

假设我们希望计算斐波那契数列的前10项并打印输出，可以提交如下请求：

curl -X POST "https://<服务器地址>/v1/code/execute/python" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "code": "fib = [0,1]\nfor i in range(2,10): fib.append(fib[i-1]+fib[i-2])\nprint(fib)",
        "id": "compute-fib-10"
      }'

服务器会立即返回类似响应：

{
  "code": 200,
  "id": "compute-fib-10",
  "job_id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
  "message": "Execution started"
}

表示代码已经开始执行。由于代码运行通常较快，如果在30秒内完成，Toolkit 可能直接在响应中附带执行结果。例如，对于上述简单计算，返回结果可能直接包含运行输出，如：

{
  "code": 200,
  "id": "compute-fib-10",
  "job_id": "<...>",
  "response": "[0, 1, 1, 2, 3, 5, 8, 13, 21, 34]\n"
}

其中 response 字段是代码执行时标准输出的内容。在异步模式下，如果没有立即返回 response，则可稍后使用任务ID查询结果或等待 webhook 通知。

可能的错误提示： 如果代码字符串语法错误或运行中抛出异常，响应的 message 或 response 将包含错误信息和堆栈跟踪。例如代码有 NameError，返回的 response 可能会显示 “NameError: name ‘x’ is not defined”. 此外，如果服务器禁用了某些高危操作，尝试使用时会报安全错误。请注意不要在代码中执行无限循环或耗尽资源的操作，服务器可能在一定超时时间后强制终止执行并返回错误提示（如 “error”: “Execution timeout”）。

通用 FFmpeg 接口

/v1/ffmpeg/compose

FFmpeg 自由编排接口

功能说明： 提供一个灵活强大的接口来执行任意 FFmpeg 操作。通过 JSON 描述输入、滤镜和输出参数，用户可以实现复杂的媒体处理流程，相当于以声明式方式构建 FFmpeg 命令。此接口适用于高级场景，如多视频/音频拼接混流、画中画叠加、滤镜特效、文本水印/动画等，用户可以突破预设接口的限制，自定义处理管线。

请求参数：

inputs (数组，必填)：输入媒体列表。每个元素包含：
- file_url (字符串)：输入文件的 URL。支持视频、音频、图像等媒体类型。可提供多个输入用于多路合成。
filters (数组，必填)：FFmpeg 滤镜图表(filtergraph)列表。每个元素包含：
- filter (字符串)：FFmpeg 滤镜命令字符串。例如 “0:vconcat=n=2:v=1[outv]” 表示将两个视频流拼接，“crop=640:480” 表示裁剪画面等。可以串联多个滤镜，用分号或逗号等FFmpeg约定的方式分隔。在提供多个输入的情况下，需要通过如 [0:v]、[1:a] 引用对应输入流。
outputs (数组，必填)：输出配置列表。一般只需一个元素，包含：
- options (数组)：FFmpeg 输出选项。每个选项是一个对象：
  - option 和 argument：分别对应FFmpeg命令行的参数名和值。例如 {“option”: “-c:v”, “argument”: “libx264”}** 表示视频编码器使用 H.264; {“option”: “-b:a”, “argument”: “128k”} 表示音频比特率128kbps。**
- （可选）如果有多个输出文件需求，可在数组中提供多个输出配置，每个可以有不同选项，如分别输出视频和音频文件等。
metadata (对象，可选)：指定是否返回处理后媒体的部分元数据信息。可包含以下布尔字段：
- thumbnail：是否提取输出视频的缩略图（首帧)。
- filesize：是否获取输出文件大小。
- duration：是否获取输出媒体时长。
- bitrate：是否获取比特率。
- encoder：是否获取编码器信息。
id (字符串，可选)：任务ID，用于标识此次操作。
webhook_url (字符串，可选)：回调URL，用于异步通知处理结果。

使用示例：

示例1：拼接两个视频 – 等价于简单使用专用的视频拼接接口。比如将两个短片尾接输出：

curl -X POST "https://<服务器地址>/v1/ffmpeg/compose" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "inputs": [
          {"file_url": "https://example.com/vid1.mp4"},
          {"file_url": "https://example.com/vid2.mp4"}
        ],
        "filters": [
          {"filter": "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1[outv][outa]"}
        ],
        "outputs": [
          {"options": [
              {"option": "-map", "argument": "[outv]"},
              {"option": "-map", "argument": "[outa]"},
              {"option": "-c:v", "argument": "libx264"},
              {"option": "-preset", "argument": "medium"},
              {"option": "-c:a", "argument": "aac"},
              {"option": "-b:a", "argument": "128k"}
          ]}
        ],
        "id": "video-merge-01"
      }'

上述JSON指定：将输入0和输入1的视频音频流通过 concat 滤镜拼接（产生输出视频流[outv]和音频流[outa]），然后输出配置中用 -map 选项指定分别输出该视频流和音频流，并设置编码器和参数。等价于FFmpeg命令行：

ffmpeg -i vid1.mp4 -i vid2.mp4 -filter_complex "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1[outv][outa]" -map "[outv]" -map "[outa]" -c:v libx264 -preset medium -c:a aac -b:a 128k output.mp4

Toolkit 会处理生成合并后的视频文件并提供结果。

示例2：剪切视频片段 – 裁剪出视频的第10秒到第15秒部分：

{
  "inputs": [ {"file_url": "https://example.com/movie.mp4"} ],
  "filters": [
    {"filter": "[0:v]trim=start=10:end=15,setpts=PTS-STARTPTS[vout];[0:a]atrim=start=10:end=15,asetpts=PTS-STARTPTS[aout]"}
  ],
  "outputs": [
    {"options": [
        {"option": "-map", "argument": "[vout]"},
        {"option": "-map", "argument": "[aout]"},
        {"option": "-c:v", "argument": "libx264"},
        {"option": "-c:a", "argument": "aac"}
    ]}
  ],
  "id": "clip-10-15s",
  "metadata": { "thumbnail": true, "duration": true }
}

这个示例通过 trim 滤镜剪出了 10s–15s 的音视频段，并要求返回输出文件的缩略图和持续时间信息。完成后，假设任务ID为clip-10-15s，我们可以通过查询任务状态或 webhook 获取结果。结果中 metadata 字段可能会包含类似：

"metadata": { "duration": 5.0, "thumbnail": "data:image/png;base64,iVBORw0K..." }

其中缩略图以 Base64 编码或 URL 提供。

可能的错误提示： 由于 /v1/ffmpeg/compose 灵活性极高，错误多数来自于滤镜或参数不正确。典型错误如 FFmpeg 滤镜语法错误，会导致任务状态返回 “error”: “Filtering failed: …” 的信息。确保 filters 中引用的输入流索引正确、滤镜字符串符合 FFmpeg 规范。如果提供的选项组合无效（例如不支持的编码参数），也会在输出结果中标记错误。此时需要参考 FFmpeg 文档调整参数。另一个常见问题是处理性能：复杂滤镜可能耗时较长，建议搭配 webhook_url 异步执行，并注意服务器性能瓶颈。

图像转视频接口

/v1/image/convert/video

将图像转换为视频

功能说明： 将一张静态图像转换为一段视频。可指定视频时长，并在视频中实现平滑的缩放（Zoom）效果，让静态图片产生动态展示的感觉（类似Ken Burns效果）。适用于制作幻灯片视频、封面图动画等场景。例如将产品海报生成一个几秒的视频用于平台上传，或者把文章插图转为短视频片头等。

请求参数：

image_url (字符串，必填)：源图像文件的URL链接。支持常见图片格式(JPG, PNG等)的公网链接。
duration (数字，可选)：生成视频的持续时间，单位秒。默认值约为 5.0 秒左右。如需更长或更短的视频，可指定此值。
zoom (布尔，可选)：是否启用图像缓慢缩放效果。默认值为 true（启用）。启用时，视频会从图像中心开始轻微放大或缩小，增加动态感；若设为 false，则输出的视频为静止图像持续指定时长。
id (字符串，可选)：任务ID，用于标识此次转换操作。
webhook_url (字符串，可选)：回调URL，用于异步处理完毕后的通知。

使用示例：

将一张宣传海报生成时长10秒的视频（带缩放效果）：

curl -X POST "https://<服务器地址>/v1/image/convert/video" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "image_url": "https://mysite.com/banner.png",
        "duration": 10,
        "zoom": true,
        "id": "banner-video-2024"
      }'

发送请求后，Toolkit 会开始处理图像转码。由于处理可能耗时（需要对图像帧进行合成编码），默认采用异步方式返回 job_id。我们可以像之前一样通过查询任务或 webhook 获得结果。当处理完成后，若成功，将得到输出视频文件的下载链接或存储位置。

假设已配置了 S3 存储，Toolkit 会将生成的视频上传至指定 S3 bucket，并在结果中通过 response 字段给出文件URL，例如：

{
  "code": 200,
  "job_id": "<...>",
  "id": "banner-video-2024",
  "response": "https://<your-bucket>.s3.amazonaws.com/banner-video-2024.mp4"
}

可以直接通过该链接下载或播放生成的视频。

可能的错误提示： 如果提供的 image_url 无法访问或文件格式不受支持，接口会返回错误，例如：

{ "code": 400, "error": "Invalid or inaccessible image URL" }

此外，对于超大分辨率的图片，处理可能较慢甚至内存不足，此时服务器可能返回500错误表示处理失败。建议对于超高分辨率图片，先行压缩或调整大小再转换。duration 值若过长也会使处理耗时线性增长，应合理设置。

媒体文件处理接口

媒体类接口包括对音视频文件的一般转换、下载、转录、静音检测、元数据提取等操作。

/v1/media/convert

通用格式转换

功能说明： 将媒体文件从一种格式转换为另一种格式。支持视频和音频的格式转码，并允许指定编码参数以满足不同质量或兼容性需求。典型应用如：将 MOV 视频转换为 MP4 以便网络播放，或将 WAV 音频压缩为 MP3 等。

请求参数：

media_url (字符串，必填)：源媒体文件的URL，可为音频或视频文件。
format (字符串，必填)：目标格式或文件扩展名，例如 “mp4”、“mov”、“gif”、“wav” 等。Toolkit 将根据此选择输出容器格式，并自动选择常用编解码器（如 MP4 默认 H.264/AAC 编码）。
video_codec (字符串，可选)：指定视频编码格式（如 “libx264”、“hevc” 等），不指定则根据格式采用默认编码。
audio_codec (字符串，可选)：指定音频编码格式（如 “aac”、“mp3” 等）。
crf (整数，可选)：视频质量系数，0~51，值越低质量越高（默认约为23，对应较高质量）。仅在有视频轨时适用。
preset (字符串，可选)：视频编码预设，控制编码速度与压缩率，如 “fast”、“medium”（默认）等，仅对某些编码器有效。
bitrate (字符串，可选)：音频比特率，如 “128k”、“320k” 等。不指定则使用编码器默认值。
id (字符串，可选)：任务ID，用于标识此次转换。
webhook_url (字符串，可选)：回调URL，异步通知转换结果。

使用示例：

将一个 MKV 视频转换为 MP4 格式：

curl -X POST "https://<服务器>/v1/media/convert" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "media_url": "https://videos.example.com/input.mkv",
        "format": "mp4",
        "video_codec": "libx264",
        "audio_codec": "aac",
        "crf": 23,
        "preset": "medium",
        "id": "mkv-to-mp4"
      }'

上述请求将把 input.mkv 转码为 output.mp4（文件名一般基于 id 或源文件名生成）。Toolkit 在后台执行FFmpeg完成转码，并异步返回结果。假如任务成功完成，结果可能通过 webhook 发送，或通过查询获取，例如：

{
  "code": 200,
  "id": "mkv-to-mp4",
  "job_id": "<...>",
  "response": "https://<bucket>/mkv-to-mp4.mp4"
}

response 给出输出文件的URL。

可能的错误提示： 若指定的 format 不受支持，接口会返回错误提示，例如：

{ "error": "Unsupported format: mkvxyz" }

如果源文件URL无法下载或格式解析失败，也会返回相应400错误。对于视频转GIF这类体积暴增的操作，要注意输出文件可能很大导致处理超时，Toolkit 在 Cloud Run 等环境下对单次处理时长有5分钟限制。必要时可缩短视频或降低帧率以避免超时。

/v1/media/convert/mp3

转为 MP3 音频

功能说明： 将输入媒体转换为 MP3 格式音频。支持从视频中提取音轨并转码为MP3，或将其他音频编码统一为MP3。适合播客音频制作、背景音乐统一格式等。

请求参数：

media_url (字符串，必填)：源媒体文件URL，既可以是视频（将提取其中的音频部分），也可以是音频文件本身。
bitrate (字符串，可选)：输出MP3的比特率，默认 128k。可以根据需要指定更高如 192k、320k 获取更高音质，或更低如 64k 以减小文件。
id (字符串，可选)：任务ID。
webhook_url (字符串，可选)：回调URL。

使用示例：

将一个MP4视频提取音频为MP3：

curl -X POST "https://<服务器>/v1/media/convert/mp3" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "media_url": "https://videos.example.com/sample.mp4",
        "bitrate": "192k",
        "id": "sample-audio"
      }'

Toolkit 接收请求后，会下载视频并提取其中的音频轨，以192kbps比特率编码为MP3文件。处理完毕后，输出MP3文件可通过结果中的URL获取。例如：

{
  "code": 200,
  "id": "sample-audio",
  "job_id": "<...>",
  "response": "https://<bucket>/sample-audio.mp3"
}

可能的错误提示： 如果源文件不包含音频轨道（比如纯视频无声），Toolkit 会返回错误说明没有音频可提取。若URL无效，同样会返回获取失败的错误消息。通常此接口相对简单，错误较少，确保提供正确URL即可。

/v1/media/download

媒体下载，BETA

功能说明： 下载指定的在线视频或音频内容，并保存到本地或云存储。此接口通过集成 yt-dlp 工具，支持从各大平台获取媒体资源，包括 YouTube 视频、社交媒体上的公开视频等等。它可以自动处理重定向、选择最佳画质/音质并下载，方便用户在后续流程中使用该媒体文件。注意：该接口目前为 BETA 版本，可能不支持所有网站，且使用需遵守各平台的服务条款。

请求参数：

source_url (字符串，必填)：要下载的媒体页面URL。例如 YouTube 视频页面链接 “https://www.youtube.com/watch?v=abc123“, Twitter 视频贴文链接等。
format (字符串，可选)：下载的格式选项。默认下载带视频和音频的最佳组合格式。如只需音频可设为 “bestaudio”，或其他 yt-dlp 支持的格式码。
id (字符串，可选)：任务ID。
webhook_url (字符串，可选)：回调URL。

使用示例：

下载一个YouTube视频：

curl -X POST "https://<服务器>/v1/media/download" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "source_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "id": "youtube-download-01"
      }'

Toolkit 将调用 yt-dlp 获取该链接实际的视频流，并下载到服务器。本例未指定 format，将下载默认的最佳可用视频。接口会立即返回任务ID：

{ "code": 200, "id": "youtube-download-01", "job_id": "<...>", "message": "Download started" }

下载完成后，如果配置了云存储，文件将上传至云，并在结果中提供下载地址。例如 webhook 收到：

{
  "id": "youtube-download-01",
  "status": "completed",
  "response": "https://<bucket>/youtube-download-01.mp4"
}

可能的错误提示： 若URL对应的站点不受支持，可能返回：

{ "error": "Download failed: Unsupported site or URL" }

如果视频因权限或地区限制无法下载，yt-dlp 也会抛出相应错误并传递给响应。如果未配置任何云存储，下载的文件将保存在本地临时目录，结果的 response 可能给出服务器本地路径（对调用方而言不可直接访问）。建议配置 S3/GCP 等以获取可访问的URL。

/v1/media/feedback

媒体反馈收集界面

功能说明： 提供一个用于收集和展示媒体内容反馈的简易Web界面。当您想要对生成的媒体内容进行人工审核、打分或评论时，可以使用此接口生成一个网页，方便相关人员观看媒体并提交反馈。例如在内容制作流程中，让团队成员观看视频并标注精彩程度或问题。

请求参数：

media_id 或 file_url (字符串，可选)：需要收集反馈的媒体标识。如果提供 media_id（通常对应Toolkit生成内容的ID），页面会展示该ID关联的媒体。如果提供 file_url，将直接加载该媒体文件。
mode (字符串，可选)：反馈模式，例如 “rating”（评分）、“comment”（评论）或两者兼有。决定页面上提供的反馈表单类型。
id (字符串可选)：本次反馈会话ID，用于区分不同反馈收集活动。

使用示例：

假设我们想让团队审核一个 ID 为 video-001 的生成视频，可以这样调用：

curl -X POST "https://<服务器>/v1/media/feedback" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"media_id": "video-001", "mode": "rating"}'

成功后，Toolkit 会返回一个带有临时访问Token的URL，例如：

https://<服务器>/v1/media/feedback?session=abc123

团队成员在浏览器打开此链接，即可观看视频 video-001，并在页面上对其进行评分。在提交后，Toolkit 会记录反馈结果（目前可能保存在服务器内存或日志中，具体实现视版本而定）。

（注：由于该接口主要涉及网页交互，无法用纯粹的 API 响应展现效果，需在浏览器中访问。Make.com 或 n8n 用户一般不会通过 HTTP模块直接调用此接口，而是将生成的反馈页面链接发送给人工处理环节。）

可能的错误提示： 若提供的 media_id 找不到对应内容，页面可能显示“Media not found”的提示。如果参数不正确，接口会返回400错误。由于这是Toolkit的辅助接口，错误排查主要查看服务器日志以了解是否成功加载媒体、是否记录了反馈等。

/v1/media/transcribe

媒体转录/翻译

功能说明： 将音频或视频内容中的语音转录为文本。支持多语言语音识别，并可选进行英文翻译。基于集成的OpenAI Whisper模型或类似技术，实现高准确率的自动字幕生成。常用于视频内容字幕提取、会议录音整理、跨语言翻译等场景。

请求参数：

media_url (字符串，必填)：待转录的音频或视频文件URL。
language (字符串，可选)：语音所在语言。如果明确知道音频语言，可提供语言代码（如 “en”、“zh”、“es” 等）以提高转录准确度。默认不提供则自动检测语言。
translate_to (字符串，可选)：将转录结果翻译成指定语言的代码。例如原音频为法语，“translate_to”: “en” 则会输出英文翻译文本。若不提供此参数，则输出原语言转录文本。
output_format (字符串，可选)：输出格式，“text”（纯文本，默认）、“srt”（字幕文件）或 “vtt” 等。如果选择字幕格式，Toolkit 会生成对应的字幕文件。
id (字符串，可选)：任务ID。
webhook_url (字符串可选)：回调URL。

使用示例：

转录一个访谈MP3音频为中文文本：

curl -X POST "https://<服务器>/v1/media/transcribe" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "media_url": "https://audio.example.com/interview.mp3",
        "language": "zh",
        "id": "interview-transcript"
      }'

发送请求后，Toolkit 将下载音频并开始转录中文语音。由于转录过程较耗时，接口会立即返回 job_id 供查询进度：

{ "code": 200, "id": "interview-transcript", "job_id": "..." }

当转录完成时，若未指定 translate_to，结果将是中文文本。可以通过 /v1/toolkit/job/status?job_id=…** 获取，例如：**

{
  "id": "interview-transcript",
  "status": "completed",
  "text": "采访者：请您介绍一下自己。\n受访者：大家好，我是…"
}

如果指定了 translate_to: “en”，则输出字段可能为 translated_text 或直接覆盖 text 字段，内容为英文翻译。若选择了字幕格式，如 output_format: “srt”，结果会提供一个可下载的字幕文件链接，例如：

{
  "status": "completed",
  "file": "https://<bucket>/interview-transcript.srt"
}

可能的错误提示： 如果音频质量差或语言不支持，转录结果可能不准确或返回空字幕。这通常不算错误，但需要人工检查。如果提供的 media_url 下载失败，会返回错误。另一个注意点是处理时长：长音频转录可能超过 1 分钟甚至数分钟，建议务必使用 webhook_url 以避免请求超时。另外，部署在某些平台（如 Cloud Run）时，单任务超过5分钟可能被强制终止，因此对于非常长的音频可考虑手动分段后分别转录。

/v1/media/silence

静音片段检测

功能说明： 分析音频或视频文件，检测其中静默（无明显声音）的时间段。返回文件中所有静音区间的起始和结束时间。适用于自动剪辑场景，例如去除演讲或播客中的无声片段、统计影片对白密度、在视频剪辑中定位停顿点等。

请求参数：

media_url (字符串，必填)：要分析的媒体文件URL，可以是音频或视频。
threshold (数值，可选)：静音判定的音量阈值（dB）。低于此音量将视为静音。默认约为 -40dB。
min_duration (数值，可选)：最小静音持续时间，单位秒。短于此时长的静音不计入结果。默认值可为1秒左右。
id (字符串，可选)：任务ID。
webhook_url (字符串可选)：回调URL。

使用示例：

检测一个演讲视频中的静音段：

curl -X POST "https://<服务器>/v1/media/silence" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "media_url": "https://videos.example.com/talk.mp4",
        "threshold": -35,
        "min_duration": 2,
        "id": "talk-silences"
      }'

Toolkit 将对视频进行音频分析，找到至少2秒的静音区间（低于-35dB）。由于分析耗时短，一般会很快完成，可能同步返回结果。假设通过 webhook 获取结果：

{
  "id": "talk-silences",
  "status": "completed",
  "silences": [
    { "start": 12.5, "end": 15.0 },
    { "start": 98.3, "end": 101.7 }
  ]
}

上述示例表示在视频中检测到两处静音：第一处从12.5秒到15.0秒，第二处从98.3秒到101.7秒。收到这些时间段后，我们就可以据此调用 /v1/video/cut 接口将这些静音片段剪掉（稍后会演示）。

可能的错误提示： 如果音频轨不存在（比如对纯静音文件或无音轨视频），接口可能返回空结果或提示 “No audio track found”。参数格式不正确会导致400错误，如阈值需为数字。大部分错误与文件访问有关，提供正确URL即可减少问题。

/v1/media/metadata

媒体元数据提取

功能说明： 提取媒体文件的详细元数据信息。返回例如格式容器、编码格式、时长、分辨率、比特率、帧率、声道等全面的信息。该接口相当于执行 ffprobe 工具，可帮助用户了解媒体技术细节，用于决策后续处理（如判断视频清晰度、音频采样率等）。

请求参数：

media_url (字符串，必填)：媒体文件URL。
id (字符串，可选)：任务ID（通常metadata获取很快，是否异步取决于实现）。
webhook_url (字符串可选)：回调URL。

使用示例：

获取一个MP4视频的元数据：

curl -X POST "https://<服务器>/v1/media/metadata" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media_url": "https://videos.example.com/movie.mp4"}'

可能返回（为简洁仅示例部分字段）：

{
  "code": 200,
  "metadata": {
    "format": "mov,mp4,m4a,3gp,3g2,mj2",
    "duration": 120.47,
    "size": 10485760,
    "bitrate": 697000,
    "video": {
      "codec": "h264 (High)",
      "width": 1920,
      "height": 1080,
      "fps": 30
    },
    "audio": {
      "codec": "aac (LC)",
      "sample_rate": 44100,
      "channels": 2
    }
  }
}

上述JSON展示了容器格式（MP4），总时长120.47秒，文件大小约10MB，比特率697kbps。视频编码为H.264 High Profile，分辨率1080p30fps。音频编码AAC，采样率44.1kHz立体声。

可能的错误提示： 如果媒体文件无法下载或解析，接口会返回错误，如：

{ "error": "Failed to probe media file" }

确保URL正确、文件格式受支持（几乎所有常见格式都支持）。另外，metadata提取通常很快同步完成，但对于超大文件（>数GB）可能耗时增加，也可考虑使用 webhook 来获取结果。

S3 云存储接口

/v1/s3/upload

上传文件到 S3

功能说明： 将指定URL的文件上传到 Amazon S3 或兼容的对象存储中。该接口以流式方式直接拉取源文件并推送到目标 bucket，避免先将文件完整保存到本地。适用于将生成的媒体内容存档到云端，或迁移外部文件到自己云存储。

环境要求： 使用此接口前需要在 NCA Toolkit 的环境变量中配置好 S3 相关信息，包括 S3_ENDPOINT_URL（若使用非AWS服务）、S3_ACCESS_KEY、S3_SECRET_KEY、S3_BUCKET_NAME 等。只有正确配置后端才能执行上传。

请求参数：

file_url (字符串，必填)：要上传的源文件URL。
file_name (字符串，可选)：指定上传到 S3 后的文件名称（包括路径）。不提供则默认使用源URL的文件名或随机生成。
bucket (字符串，可选)：目标 bucket 名称。如不提供则使用配置的默认 S3_BUCKET_NAME。
id (字符串可选)：任务ID。
webhook_url (字符串可选)：回调URL。

使用示例：

将一个公网视频文件上传到自己的 S3 存储：

curl -X POST "https://<服务器>/v1/s3/upload" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://videos.example.com/sample.mov",
        "file_name": "uploads/2025/01/sample.mov",
        "id": "upload-sample-2025"
      }'

接口验证请求后，会返回任务受理信息：

{ "code": 200, "id": "upload-sample-2025", "job_id": "<...>", "message": "Upload started" }

Toolkit 后台从源URL下载文件并直接上传至 S3 bucket 的 uploads/2025/01/sample.mov 路径。当处理完成时，若成功，结果的 response 字段将提供上传文件的 S3 路径或URL，例如：

{
  "id": "upload-sample-2025",
  "status": "completed",
  "response": "s3://my-bucket/uploads/2025/01/sample.mov"
}

可能的错误提示： 若环境变量缺失或配置错误，请求会失败并返回 HTTP 500 错误，内容包含 “No S3 credentials” 或 “Invalid S3 configuration” 等提示。源文件无法下载时会返回400错误。若文件较大上传耗时长，可以使用 webhook_url 让完成后通知。另需注意服务器对并发上传的队列限制，若同时上传任务过多会导致请求被拒绝（HTTP 429）。请合理控制并发或调整 MAX_QUEUE_LENGTH 配置。

工具箱 (Toolkit) 实用接口

Toolkit 提供了一些辅助接口，用于认证测试和任务管理等。

/v1/toolkit/authenticate

验证 API 密钥

功能说明： 验证提供的 API Key 是否正确。调用此接口可以快速检查当前 Toolkit 部署是否运行正常、密钥配置是否正确。适用于上线前健康检查或集成测试。

请求方式：GET 请求（无需主体）。只需在请求头加入 x-api-key 即可。若密钥正确且服务正常，将返回成功状态。

使用示例：

curl -X GET "https://<服务器>/v1/toolkit/authenticate" \
  -H "x-api-key: YOUR_API_KEY"

成功时，服务器返回：

{ "code": 200, "authenticated": true }

这表明提供的 API Key 有效，Toolkit 服务处于运行状态。如果 API Key 错误，将返回 HTTP 401 未授权错误，响应例如：

{ "code": 401, "error": "Invalid API Key" }

可能的错误提示： 仅有 API Key 不正确这一情况。未提供密钥则返回401；提供错误密钥同样401。因此这个接口简单明确，用于检查身份认证。

/v1/toolkit/test

安装测试接口

功能说明： 检查 Toolkit 是否安装配置正确的简易端点。调用该接口会触发 Toolkit 在后台执行一系列自检操作：创建一个临时文件，尝试上传到已配置的云存储，删除临时资源等。通过它可以验证存储服务连通性、队列处理等是否正常工作。

请求方式：GET 请求（无需主体）。同样需要 x-api-key 认证。

使用示例：

curl -X GET "https://<服务器>/v1/toolkit/test" \
  -H "x-api-key: YOUR_API_KEY"

如果一切正常，Toolkit 将返回一个 JSON，类似：

{
  "code": 200,
  "id": null,
  "job_id": "a1b2c3d4-e5f6-...-o5p6",
  "response": "https://<storage-url>/nca-test/success.txt"
}

其中 response 字段是Toolkit在云存储中创建的测试文件URL，例如一个名为 success.txt 的文件。下载该文件如果内容是 “OK” 或类似消息，则表示读写正常。

如果没有配置云存储，Toolkit 可能改为将文件存于本地并返回本地路径，或在 message 字段提示跳过云测试。总之，该接口的执行结果表明Toolkit服务功能正常。

可能的错误提示： 如果 response 返回的URL无法访问或者文件不存在，则说明云存储配置有误或连接失败。此时请检查 S3/GCP 凭据是否正确。该接口本身不会返回400类错误，除非认证失败或者内部异常。因此若收到500错误或长时间无响应，应根据提示检查日志定位问题。

/v1/toolkit/job/status

查询单个任务状态

功能说明： 根据任务ID查询对应任务的执行状态和结果。当使用各处理接口异步执行操作时，可通过此端点获取任务当前状态（排队中、进行中、已完成、失败等）以及结果数据或错误信息。

请求参数： GET 请求，需要将 job_id 作为查询参数或路径参数提供。例如：GET /v1/toolkit/job/status?job_id=<任务ID>。

使用示例：

假设之前调用 /v1/video/concatenate** 获得的 job_id 为 123e4567-e89b-12d3-a456-426614174000，则可以查询：**

curl -X GET "https://<服务器>/v1/toolkit/job/status?job_id=123e4567-e89b-12d3-a456-426614174000" \
  -H "x-api-key: YOUR_API_KEY"

可能的返回结果示例：

进行中：任务尚未完成：

{ "job_id": "123e...74000", "status": "processing", "progress": 50 }

（其中 progress 字段如存在，表示完成进度百分比；不是所有任务都有此字段）
已完成（成功）：任务完成且有结果：

{
  "job_id": "123e...74000",
  "status": "completed",
  "result_url": "https://<bucket>/merged-video.mp4",
  "message": "Success"
}

（字段名称可能是 result_url 或 response 等，包含任务成果，比如输出文件的URL）
已完成（失败）：任务执行失败：

{
  "job_id": "123e...74000",
  "status": "failed",
  "error": "FFmpeg process exited with code 1",
  "message": "Conversion failed"
}

可以从 error 或 message 看出失败原因。

可能的错误提示： 如果查询一个不存在的任务ID，接口会返回 HTTP 404 或错误消息：

{ "error": "Job ID not found" }

另外，如果未提供 job_id 参数，则会返回400错误要求提供ID。

/v1/toolkit/jobs/status

查询多个任务状态

功能说明： 批量查询在一定时间范围内所有任务的状态列表。便于监控近期所有任务的执行情况，例如获取最近一小时内所有任务的结果或查看哪些任务仍在进行中。适合后台管理或Dashboard用途。

请求参数：GET 请求。可使用查询参数 start 和 end 指定时间范围（通常使用UTC时间的 ISO8601 字符串或时间戳）。例如：/v1/toolkit/jobs/status?start=2025-01-01T00:00:00Z&end=2025-01-01T01:00:00Z 将查询该小时内的任务。如果不提供参数，可能默认返回最近若干条任务记录（视实现而定）。

使用示例：

获取最近24小时内所有任务状态：

curl -X GET "https://<服务器>/v1/toolkit/jobs/status?start=2025-01-01T00:00:00Z&end=2025-01-02T00:00:00Z" \
  -H "x-api-key: YOUR_API_KEY"

假设返回：

{
  "jobs": [
    { "job_id": "aaa-bbb-ccc", "status": "completed", "id": "video-merge-01", "type": "/v1/video/concatenate" },
    { "job_id": "ddd-eee-fff", "status": "failed", "id": "clip-10-15s", "type": "/v1/ffmpeg/compose", "error": "..." },
    { "job_id": "ggg-hhh-iii", "status": "processing", "id": "mkv-to-mp4", "type": "/v1/media/convert" }
    // ... 其他任务
  ]
}

每个数组元素列出了任务ID、状态、用户提供的ID（若有）以及接口类型，可能还包括错误信息或部分结果。通过该列表，可以一目了然过去一天内Toolkit处理任务的概况，例如成功多少、失败多少、正在处理哪些。

可能的错误提示： 如果时间参数格式不对，将返回400错误提示正确格式。如果任务列表过长，也许接口会做分页或限制输出长度（具体视实现）。通常来说，只要提供正确的时间范围，本接口不会返回500类错误。

视频处理接口

/v1/video/caption

视频自动字幕

功能说明： 为视频添加可定制样式的字幕。该接口自动转录视频中的语音内容，并将其以字幕形式烧录到视频画面上。用户可以调整字幕的字体、颜色、位置、每行字数等，以适应不同风格需求。常用于短视频字幕（抖音风格高亮逐字字幕等）制作，以及为无声观看优化的视频内容。

请求参数：

video_url (字符串，必填)：源视频文件URL。
replace (数组，可选)：需要替换的文字列表。每个元素是一个对象：
- find: 要查找的原文字，
- replace: 替换后的文字。
例如 {“find”: “秘密”, “replace”: “***”} 可在字幕中将出现的“秘密”二字用星号替代。可用于审查敏感词或打码脏话。
settings (对象，可选)：字幕样式设置，包括以下字段：
- font_family: 字体名称。如 “Arial” 或 “Source Han Sans” 等。Toolkit 镜像内预置了一些常用字体，可以指定之。默认为一种内置醒目字体。
- font_size: 字体大小（像素）。默认大约60px，用于1080p视频。
- word_color: 字体颜色（当前朗读的词），HEX色值，如 “#FFFF00”（黄色）。
- line_color: 字体颜色（整行文本，其余部分），如 “#FFFFFF”（白色）。
- all_caps: 是否将字幕强制转换为全大写。布尔值，默认 false。
- bold: 加粗，italic: 斜体，underline: 下划线，strikeout: 删除线 – 这些为布尔选项，控制文字样式，默认都为 false。
- outline_width: 字体描边宽度，默认3（像素）。设为0则无描边。
- shadow_offset: 阴影偏移值，默认4像素。0则无阴影。
- shadow_color: 阴影颜色，默认黑色（通常无需改）。
- position: 字幕位置，可选 “bottom_center”（底部居中，默认）、“top_center” 等预设位置。
- max_words_per_line: 每行最多单词数（或汉字数）。超过则自动换行。默认3。
- style: 样式模式，“highlight” 为卡拉OK逐字高亮样式（默认），“plain” 则为普通静态字幕模式。高亮模式下，会使用 word_color 和 line_color 区分当前词和其余词。
id (字符串，可选)：任务ID。
webhook_url (字符串，可选)：回调URL。

使用示例：

将一个演讲视频加上高亮字幕：

curl -X POST "https://<服务器>/v1/video/caption" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "video_url": "https://videos.example.com/speech.mp4",
        "replace": [
          { "find": "机密", "replace": "****" }
        ],
        "settings": {
          "line_color": "#FFFFFF",
          "word_color": "#00FF00",
          "font_family": "Arial",
          "font_size": 50,
          "bold": true,
          "max_words_per_line": 4,
          "position": "bottom_center",
          "style": "highlight"
        },
        "id": "speech-caption"
      }'

Toolkit 会下载 speech.mp4，自动转录其中的语音（假定语言自动检测为中文），生成对应的字幕，并将字幕以绿色高亮逐字的形式叠加到视频下方。上例中还将出现的“机密”一词替换成“****”。由于整个过程包括转录和视频重编码，较耗时，接口会返回任务ID：

{ "code": 200, "id": "speech-caption", "job_id": "<...>" }

完成后，可获得输出字幕视频链接，如：

{ "status": "completed", "response": "https://<bucket>/speech-caption.mp4" }

下载该视频，即可看到原视频画面上已经烧录了白色字幕，其中当前朗读的文字以绿色高亮逐字呈现。

可能的错误提示： 如果视频里没有语音，转录可能产生空结果，Toolkit 目前仍会生成一个没有字幕的视频，但message可能提示 “No speech detected” 等。转录如果失败（例如音频质量太差），任务可能被标记为失败并在 error 中给出原因。对于样式参数，Toolkit 内有默认值，提供非法值（如字体名不存在）时会回退默认并不会报错，但字体可能不生效。**注意：**生成字幕涉及大量计算，如超过1分钟的视频务必考虑使用 webhook 异步处理，以避免请求超时。部署在 Cloud Run 时，长于5分钟的任务可能被中断。

/v1/video/concatenate

视频拼接合并

功能说明： 将多个视频片段首尾相连，合并输出为一个完整视频。支持格式相同的视频无缝拼接，亦可对不同编码的视频进行重新编码合并。适用于剪辑合并（例如把多段录制合成一条成片）、广告/片头片尾加至正片等操作。

请求参数：

video_urls (数组，必填)：待拼接的视频源URL列表。每个元素为对象：
- video_url (字符串)：视频文件的URL。
id (字符串，可选)：任务ID。
webhook_url (字符串，可选)：回调URL。

使用示例：

将两段 MP4 视频串联：

curl -X POST "https://<服务器>/v1/video/concatenate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "video_urls": [
          { "video_url": "https://example.com/intro.mp4" },
          { "video_url": "https://example.com/main.mp4" }
        ],
        "id": "video-full"
      }'

Toolkit 会获取两个视频并进行合并。成功后，通过结果提供输出视频链接，如：

{ "status": "completed", "response": "https://<bucket>/video-full.mp4" }

可能的错误提示： 如果视频编码参数差异过大（如一个是1080p30fps，另一个720p60fps），Toolkit会自动对齐编码以合并，可能导致重新编码耗时增加。如遇格式不支持，会返回错误消息。其它错误如URL无效同音频拼接类似，不再赘述。

/v1/video/thumbnail

提取视频缩略图

功能说明： 从视频中提取指定时间的帧图像作为缩略图。可用于生成视频封面、预览图等。用户可以指定时间点，获取该时刻的一帧图像。

请求参数：

video_url (字符串，必填)：视频文件URL。
timestamp (字符串或数字，可选)：截取帧的时间点。如果是字符串，可用 “HH:MM:SS” 格式，或秒数（支持小数）。默认截取视频第1秒处帧。
output_format (字符串，可选)：图像格式，如 “jpg”、“png” 等。默认 jpg 压缩图。
id (字符串，可选)：任务ID。
webhook_url (字符串可选)：回调URL。

使用示例：

截取一段视频在 00:00:10.5 处的帧图并保存为 PNG：

curl -X POST "https://<服务器>/v1/video/thumbnail" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "video_url": "https://videos.example.com/movie.mp4",
        "timestamp": "00:00:10.5",
        "output_format": "png",
        "id": "movie-thumb"
      }'

Toolkit 处理后将输出图像文件URL，例如：

{ "status": "completed", "response": "https://<bucket>/movie-thumb.png" }

该图即为指定时间的视频画面截图。

可能的错误提示： 若指定时间超过视频长度，Toolkit可能返回错误：

{ "error": "Timestamp is beyond video duration" }

未指定 timestamp 则默认取1秒，如视频前1秒没有画面（纯黑场），则得到黑帧。通常无严重错误。确保视频URL有效即可。

/v1/video/cut

剪除视频片段

功能说明： 从视频中移除指定的一个或多个时间区间，剪切掉这些片段后输出剩余部分连续的视频。简单说，就是删除掉不需要的片段，保留视频其他部分。适用于去除冗长片段（广告、静默段等），或内容审核场景下剪掉敏感片段。

请求参数：

video_url (字符串，必填)：源视频URL。
cuts (数组，必填)：要剪除的时间段列表。每个元素为对象：
- start (字符串/数字)：剪除片段的开始时间。
- end (字符串/数字)：剪除片段的结束时间。
时间可以用 “HH:MM:SS” 格式或秒数（支持浮点）。**注意：**如果有多个区间，应该确保它们不重叠，Toolkit 会按时间先后剪除这些段。
output_format (字符串，可选)：输出格式，默认与源格式相同（如源是MP4则输出MP4）。可指定如 “mp4”、“mov” 等。
id (字符串可选)：任务ID。
webhook_url (字符串可选)：回调URL。

使用示例：

将视频中0:12.5-0:15.0和1:38.3-1:41.7两个静音段剪掉（对应我们之前检测到的静音片段）：

curl -X POST "https://<服务器>/v1/video/cut" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "video_url": "https://videos.example.com/talk.mp4",
        "cuts": [
          { "start": "00:00:12.5", "end": "00:00:15.0" },
          { "start": "00:01:38.3", "end": "00:01:41.7" }
        ],
        "id": "talk-cut"
      }'

Toolkit 会将源视频这两段时间范围内的画面删除，拼接保留部分输出连续视频。完成后可获得新视频链接：

{ "status": "completed", "response": "https://<bucket>/talk-cut.mp4" }

新视频长度将比原来减少约5.9秒，并无原静音片段。

可能的错误提示： 如果提供的 cuts 区间有交叉或不合法（如 start >= end），Toolkit 会返回错误说明参数无效。若要剪掉的总时长几乎覆盖整个视频，则输出可能为空或返回错误。编码过程中若有问题，也会通过 error 字段提示，比如编码失败等。通常按规范提供参数即可避免错误。

/v1/video/split

拆分视频片段

功能说明： 根据指定的时间点，将一个视频拆分成多个片段。与 /v1/video/cut 不同，split 并不删除内容，而是把视频按给定区间切开，输出为多个独立文件。适用于批量剪辑场景，例如把长视频按章节拆分、按固定时间间隔分段保存等。

请求参数：

video_url (字符串，必填)：源视频URL。
segments (数组，必填)：拆分片段定义列表。每个元素为对象：
- start (字符串/数字)：片段起始时间。
- end (字符串/数字)：片段结束时间。
各片段区间应覆盖所需的视频部分，且通常相邻或有间隔皆可。Toolkit会输出与每个segment对应的视频文件。
output_format (字符串，可选)：输出格式，默认与源一致。
id (字符串可选)：任务ID前缀或标识。输出文件可能会基于此ID命名区分。
webhook_url (字符串可选)：回调URL。

使用示例：

将一段5分钟的视频按每分钟拆分成5段：

curl -X POST "https://<服务器>/v1/video/split" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "video_url": "https://videos.example.com/lecture.mp4",
        "segments": [
          { "start": "00:00:00", "end": "00:01:00" },
          { "start": "00:01:00", "end": "00:02:00" },
          { "start": "00:02:00", "end": "00:03:00" },
          { "start": "00:03:00", "end": "00:04:00" },
          { "start": "00:04:00", "end": "00:05:00" }
        ],
        "id": "lecture-part"
      }'

Toolkit 将按给定的起止时间，输出5个1分钟的视频片段。成功后结果可能包含每个片段的路径，例如：

{
  "status": "completed",
  "parts": [
    "https://<bucket>/lecture-part_1.mp4",
    "https://<bucket>/lecture-part_2.mp4",
    "https://<bucket>/lecture-part_3.mp4",
    "https://<bucket>/lecture-part_4.mp4",
    "https://<bucket>/lecture-part_5.mp4"
  ]
}

这样就拿到了按顺序编号的多个文件。

可能的错误提示： 如果 segments 列表为空或时间不合法，接口会返回错误。若片段之间有重叠，也会报参数错误。需要注意的是，视频拆分会多次编码，处理时间随片段数增加而增加，尽量不要一下子请求拆分过多段，以免超时或占用过多资源（可分批处理）。Toolkit 对同时输出多个文件有一定开销，可能在云端环境受内存限制，如果片段很多可能失败或被强制停止，遇到这种情况可减少 segments 数量重试。

/v1/video/trim

裁剪视频时段

功能说明： 裁剪出视频中的一个区间片段。与 cut 相反，这里是保留指定的片段，丢弃其他内容。其实功能上 trim 相当于只有一个 segment 的 split，但使用更直观。常用于获取长视频中某一段精华，例如截取电影中的一幕、截取监控视频中的关键5分钟等。

请求参数：

video_url (字符串，必填)：源视频URL。
start (字符串/数字，必填)：要保留片段的开始时间。
end (字符串/数字，必填)：要保留片段的结束时间。
output_format (字符串，可选)：输出格式，默认与源一致。
id (字符串可选)：任务ID。
webhook_url (字符串可选)：回调URL。

使用示例：

从一段监控录像中裁剪出 10:00 到 10:05 这5分钟片段：

curl -X POST "https://<服务器>/v1/video/trim" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "video_url": "https://videos.example.com/cctv.mp4",
        "start": "00:10:00",
        "end": "00:15:00",
        "id": "cctv-clip"
      }'

Toolkit 将输出一个长约5分钟的视频文件 cctv-clip.mp4。成功后获取URL类似：

{ "status": "completed", "response": "https://<bucket>/cctv-clip.mp4" }

可能的错误提示： 如果 start 或 end 未提供，会返回400错误要求提供时间。如果 end 超过视频长度，也会返回错误或自动截断至视频末尾（具体行为视实现）。其他错误类似 cut/split。总体而言，trim 是最简单的视频剪辑形式，按照正确的时间参数调用一般不会有问题。

调用实战场景演示

本节通过一个实际例子，展示如何将上述多个接口组合起来实现一个自动化的媒体处理流程。假设我们运营一个自媒体账号，需要定期从 YouTube 获取访谈视频并制作成带字幕的短视频片段，同时提取其中的音频发布播客。可以使用 n8n 或 Make.com 将这一系列操作自动化。下面演示基于 n8n 的流程：

场景：下载 YouTube 视频 -> 转录生成字幕 -> 制作带中英文双语字幕的视频 -> 提取MP3音频 -> 上传所有内容到云端

步骤1 – 下载视频： 使用 HTTP Request 节点 调用 /v1/media/download 接口，将目标 YouTube 视频下载到本地服务器或云存储。例如，在 n8n 的节点配置中，方法选 POST，URL 填入 https://<服务器>/v1/media/download，Body 为：

{
  "source_url": "https://www.youtube.com/watch?v=abc12345",
  "id": "episode-10-video"
}

执行后，该节点会返回一个 JSON，其中包含 job_id。因为下载可能较慢，我们需要等待其完成。

步骤2 – 查询下载状态： 可以在 n8n 中使用轮询机制或等待节点，每隔一段时间调用 /v1/toolkit/job/status 查询上一步的任务状态。当状态变为 “completed” 时，我们从返回数据中获取下载后的视频文件URL。例如响应可能是：

{
  "job_id": "...",
  "status": "completed",
  "response": "https://<bucket>/episode-10-video.mp4"
}

提取其中的 response 字段，得到原始视频文件地址（已在云存储）。

步骤3 – 音频转录（中英文字幕）： 下一步，新增一个 HTTP节点，调用 /v1/media/transcribe 对下载的视频进行语音转录，并让其输出双语字幕。假设访谈语言为英语，我们希望获取英文转录以及中文翻译，于是请求Body如下：

{
  "media_url": "https://<bucket>/episode-10-video.mp4",
  "language": "en",
  "translate_to": "zh",
  "output_format": "srt",
  "id": "episode-10-subs"
}

这里指定输出 SRT 字幕文件，同时翻译成中文。由于转录可能较耗时，我们同样在请求中可以加入 webhook_url 或后续用任务ID查询状态。为简单起见，可以直接提供 webhook_url，例如一个 n8n 自建的 Webhook节点URL。Toolkit 完成转录后会向该URL发送结果，包含字幕文件链接，如：

{
  "id": "episode-10-subs",
  "status": "completed",
  "response": "https://<bucket>/episode-10-subs.srt"
}

通过 n8n 的Webhook触发，我们获取到了字幕文件的URL。这份 SRT 文件内包含英文和译成中文的双语字幕（Whisper可能将翻译结果作为第二语言行写入SRT，具体格式可根据需要调整）。

步骤4 – 制作带字幕的视频： 有了字幕文件，现在调用 /v1/video/caption 给原视频加字幕。这里一个技巧：因为我们已经有人审核/翻译的字幕，更希望直接使用它，而不是让 caption 接口重新自动转录。Toolkit 支持我们提供自己的字幕文本，只需将字幕内容注入 settings 或其他参数中（当前版本可能未直接暴露此功能，但我们可以曲线：将 SRT 文件的内容合并到视频图像上，其实需要 ffmpeg/compose 的复杂用法。如果 caption 接口暂不支持外部字幕输入，我们可以反向使用 ffmpeg接口完成）。

为了演示，我们假定 /v1/video/caption 可以接受一个已经生成的字幕文件URL，例如参数：

{
  "video_url": "...",
  "subtitle_url": "https://<bucket>/episode-10-subs.srt",
  "settings": { ... 样式参数 ... },
  "id": "episode-10-captioned"
}

Toolkit 将把字幕烧录进视频。样式参数可根据品牌风格设定，如中英文字幕不同颜色等（如不支持双语高亮，可选择普通样式，让两行字幕分别显示英文和中文）。调用后获取任务ID并等待完成，得到 episode-10-captioned.mp4 视频文件URL。

（ 当前版本 NCA Toolkit 可能没有直接 subtitle_url 参数，此处为假定。如不支持，可考虑使用 ffmpeg/compose，通过 subtitles 滤镜加字幕。但该过程复杂，这里从简。）

步骤5 – 提取MP3音频： 同时，我们并行使用 /v1/media/convert/mp3** 接口提取音频：**

{
  "media_url": "https://<bucket>/episode-10-video.mp4",
  "bitrate": "128k",
  "id": "episode-10-audio"
}

很快即可得到 MP3 文件的URL（episode-10-audio.mp3）。

步骤6 – 上传结果并发布： 由于Toolkit已经在产生结果时配置了云存储，episode-10-captioned.mp4 和 episode-10-audio.mp3 都已经在我们云端 bucket 中。我们可以在 n8n 后续节点中使用这些URL，例如：

发送消息到团队Slack，附上视频和音频的链接。
在CMS中创建一篇内容，插入字幕视频的链接和音频播客的链接，实现内容多渠道发布。

整个流程自动完成：每当我们有新的YouTube链接，只需触发 n8n 工作流，就能产出带字幕的视频和音频，大大节省了人力。这个实战案例涉及了 媒体下载、语音转录翻译、字幕视频生成、音频转换、云端保存 等多个接口的串联，充分体现了 NCA Toolkit 在无代码自动化工具中的价值。

错误排查与最佳实践

在使用 NCA Toolkit API 时，难免遇到错误或性能问题。本节总结常见的错误信息、排查方法以及提升使用效率的最佳实践，帮助用户更顺畅地调用各接口。

常见错误及排查

API 密钥无效：如果调用返回401 Unauthorized，多半是 x-api-key 错误或未提供。请检查是否在请求头正确添加了 x-api-key: YOUR_API_KEY，以及密钥本身拼写无误、对应当前部署。使用 /v1/toolkit/authenticate 接口可快速验证密钥是否有效。
参数缺失或格式错误：当返回 HTTP 400 或 422 错误时，一般会在响应的 error 或 message 字段给出具体提示。例如：
- “‘media_url’ is required”：表示缺少必填参数 media_url。
- “Invalid value for parameter ‘start'”：表示提供的参数值类型不对或格式非法。 此时应仔细核对接口文档中参数列表，补齐必填项、修正格式（例如时间格式需为字符串 “HH:MM:SS” 或数值秒）。
URL 无法访问：如果返回类似** ** “error”: “Unable to fetch file”** 或 “error”: “Invalid URL”，说明提供的媒体URL有问题。可能原因：
- URL拼写错误或包含空格等非法字符。
- 资源需要授权（比如私有链接）而Toolkit无法直接访问。如果需要处理私有文件，可考虑先将文件上传到Toolkit可访问的位置（如预配置的云存储）再提供URL。
- 目标服务器阻止了Toolkit所在服务器的请求（可以尝试换用代理或下载后再上传）。
建议先在浏览器测试该URL是否能直接下载。如果不行，应更换为可公开访问的链接。
队列满或请求频繁被拒：Toolkit 默认允许的最大并发/队列任务数量由 MAX_QUEUE_LENGTH 环境变量控制（默认0表示不限制）。但在实际应用中，如果并发提交大量任务，Toolkit 可能响应 HTTP 429 Too Many Requests 错误，并提示 “MAX_QUEUE_LENGTH (N) reached”。此时应：
- 减少同时提交的任务数（例如在工作流中加延时，等待前一批任务完成）。
- 或增加服务器实例资源，调高 MAX_QUEUE_LENGTH 配置（需要重启服务生效）。
- 对于批量任务，可考虑使用 /v1/toolkit/jobs/status 分批监控，避免继续提交新任务。
处理超时：如果某些任务长时间无响应，尤其在 Make.com 这样的服务（可能有执行时间上限）中，可能会失败。Toolkit 部署在Cloudflare或Cloud Run等平台时，请求超过100秒Cloudflare会切断连接，超过5分钟 GCP Run可能直接终止进程。解决方法：
- 对于长任务（如大文件转码、长视频转录），务必使用 webhook_url 参数让Toolkit后台处理，并由回调获取结果。这样避免HTTP请求本身超时。
- 或者将任务拆解：例如1小时视频可拆成每10分钟一段并行转录，再拼接结果，从而每段都在允许时间内完成。
外部工具错误：Toolkit 内部依赖FFmpeg、yt-dlp、Whisper模型等，如果这些工具执行失败，会在 error 字段显示其错误信息。例如FFmpeg可能报 “codec not found”、Whisper模型可能报显存不足等。这类错误往往不是API参数问题，而是服务器环境或资源问题：
- 检查部署日志，确认所需的依赖是否完整加载（Toolkit Docker 镜像通常自带，不需担心）。
- 观察错误信息，针对性调整：如 “Out of memory” 则需要更高内存的机器或较小模型；“Unsupported site” 则yt-dlp不支持该链接，可能需要更新Toolkit版本。
云存储相关：常见如 S3 上传报 “InvalidAccessKeyId” 或 “SignatureDoesNotMatch” 等XML错误，这是S3凭据不对。请核对 .env 中的 S3_ACCESS_KEY 和 S3_SECRET_KEY（是否有多余空格等）。上传接口报 bucket 不存在，则检查 S3_BUCKET_NAME。GCP 存储类似，可能是凭据JSON不正确。总之，云存储错误往往在接口的error消息中体现，按提示调整配置，然后重启服务再试 /v1/toolkit/test 直到通过。
结果不理想但非报错：有时接口调用成功但结果不符合预期，例如字幕识别错误、翻译不准、视频画质下降等。这类不是程序错误而是模型/编码效果问题。解决方法包括：
- 提供给模型更多信息：如指定 language 防止识别错语言。
- 使用较高码率/更佳编码参数平衡画质：如转换视频时不要压缩太狠。
- 如果需要更精准转录，可考虑在 code/execute/python 中调用更大的Whisper模型或其他ASR服务，然后将结果用于视频字幕接口。

总之，大部分错误都能通过日志和返回信息定位原因。调用Toolkit应抱着“服务端做了大量处理”的心态，仔细阅读返回信息并检查配置。

使用最佳实践和性能优化

充分利用 id 标识：id 参数在所有接口中可选但推荐使用。为每个任务赋予有意义的ID（如 “project001_partA”），方便在日志和结果文件名中识别。特别地，如果配置了云存储，Toolkit通常会使用 id 作为输出文件名的一部分，这样输出文件易于管理和查找。
使用 webhook_url 异步回调：强烈建议为可能耗时超过1分钟的任务提供 webhook_url。这使Toolkit在后台处理完即可通知，无需前端长时间轮询等待，避免请求超时问题。在 n8n/Make 等平台，可以设定一个Webhook节点URL接收通知，然后继续后续流程，实现完全异步流转。
任务拆分与并行：对于超长或者超高清的媒体处理，考虑拆分处理：
- 例：2小时视频可先用 /v1/video/split 按20分钟切块，各自转码或转录，再用 /v1/video/concatenate 合并结果。这可以绕过平台超时限制，并利用多任务并行处理缩短总时间。
- 又如大型批处理，将100个小任务分批次（比如每次10个并行）发送，避免一次性占满队列造成429错误。
调优环境参数：如果您自托管Toolkit，可根据服务器性能调整一些环境变量：
- MAX_QUEUE_LENGTH：设置为略小于CPU核心数的倍数，防止过载。例如小型实例设为10，避免排太多任务。
- GUNICORN_WORKERS：Toolkit默认Worker数=CPU核数+1 。如果主要任务是CPU密集型（如视频转码），适当增加Workers对性能提升有限，反而会争抢CPU；若任务I/O为主，可增加Workers提升吞吐。
- GUNICORN_TIMEOUT：默认30秒。可根据最长任务时间调大，如处理大文件设置到 300 秒甚至600秒，以免任务虽然在进行却被Gunicorn误判为超时杀掉。
- LOCAL_STORAGE_PATH：临时文件目录，如默认 /tmp 空间不足，可改到挂载的大容量磁盘目录，避免处理大文件时磁盘写满。
充分利用云存储：将输出结果保存到云端的好处是持久化和易于分享。但也要注意清理无用文件。Toolkit不会自动删除上传到云的文件（除了Toolkit/test创建的测试文件可能会清理）。建议定期检查 S3/GCS bucket，把临时/测试文件删除，以节约空间和避免混淆。
保持Toolkit最新：No-Code Architects Toolkit 项目在持续更新新功能和改进。关注其GitHub仓库更新日志，及时升级Docker镜像。有时升级能带来性能优化和新接口（例如近期才新增的音频拼接接口）。升级前注意备份 .env 等配置，按照升级指南操作。
安全考虑：Toolkit开放了强大的代码执行接口，在将其部署为公共服务时，要注意安全：
- 限制访问来源：可通过防火墙或反向代理限制仅内部使用，避免他人滥用您的实例。
- 定期更换API Key：防止密钥泄露后被他人调用。
- 监控资源：启用日志和监控，观察是否有异常大量请求或高负载情况，及时处理（如增加限制或扩容）。

对于 n8n 与 Make.com 用户，使用Toolkit时还有一些贴心建议：

在HTTP节点配置中，勾选“Continue on Fail”选项，可让流程在非致命错误时继续，从而自行处理Toolkit返回的错误而不是整个流程中断。
善用 n8n 的 Function节点来解析Toolkit返回的数据，例如提取文件URL、构造下一个请求的参数（例如根据静音检测结果构造 cuts 列表）。
Make.com 用户则可以用一系列HTTP模块和工具模块串联，并利用Router模块处理并行。如果处理流程复杂，可以考虑拆成多个Scenario，由云端存储作为中间交换（例如先运行下载+转录Scenario，输出结果路径存数据库，然后由定时触发另一个Scenario去取字幕文件并继续后续步骤）。

总之，No-Code Architects Toolkit 作为强大的媒体处理后端，只需遵循其接口规范并结合良好的自动化实践，就能在无代码平台上实现极富创造力的工作流。建议新手从简单接口开始调试，逐步组合更多功能，并充分利用上述技巧优化性能和可靠性。

附录：完整的 curl 示例合集与参数表格

本附录汇总了前文介绍的所有接口的参数详表和对应的 curl 请求示例，方便读者查阅和复制使用。

说明： 以下表格中，“必填”一栏标注该参数是否为必需；“默认值”列给出参数的默认值或默认行为（如适用）；“说明”对参数用途做简述。表格后提供的 curl 示例均包含必要的请求头和示例参数，可直接替换实际值后使用。

音频接口

/v1/audio/concatenate

参数列表

参数名	类型	必填	默认值	说明
audio_urls	Array	是	无	要合并的音频文件URL列表，每项为{“audio_url”: “<链接>”}对象
id	String	否	无	任务自定义ID，用于结果跟踪和命名
webhook_url	String	否	无	异步回调URL，处理完成后向其POST通知结果

示例 curl 请求：

curl -X POST "https://<host>/v1/audio/concatenate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "audio_urls": [
          {"audio_url": "https://example.com/part1.mp3"},
          {"audio_url": "https://example.com/part2.mp3"}
        ],
        "id": "audio-merge-001",
        "webhook_url": "https://yourapp.com/webhook/audio_complete"
      }'

代码执行接口

/v1/code/execute/python

参数列表

参数名	类型	必填	默认值	说明
code	String	是	无	要执行的 Python 源代码
id	String	否	无	任务ID，用于跟踪代码执行任务
webhook_url	String	否	无	回调URL，代码执行完毕后POST结果到此URL

示例 curl 请求：

curl -X POST "https://<host>/v1/code/execute/python" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "code": "print(2+2)",
        "id": "test-code-01",
        "webhook_url": "https://yourapp.com/webhook/code_done"
      }'

FFmpeg 通用接口

/v1/ffmpeg/compose

参数列表

参数名	类型	必填	默认值	说明
inputs	Array	是	无	输入文件列表。每项包含file_url字段指向媒体URL。支持多个。
filters	Array	是	无	滤镜列表。每项filter字段写FFmpeg滤镜graph字符串。
outputs	Array	是	无	输出配置列表。每项含options数组，定义FFmpeg输出参数选项。
metadata	Object	否	无	元数据提取设置，可选字段：thumbnail, filesize, duration, bitrate, encoder (Boolean类型)。
id	String	否	无	任务ID，用于标识任务和命名输出
webhook_url	String	否	无	回调URL，任务完成后POST通知结果

示例 curl 请求：

curl -X POST "https://<host>/v1/ffmpeg/compose" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "inputs": [
          {"file_url": "https://example.com/video1.mp4"},
          {"file_url": "https://example.com/video2.mp4"}
        ],
        "filters": [
          {"filter": "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1[outv][outa]"}
        ],
        "outputs": [
          {"options": [
              {"option": "-map", "argument": "[outv]"},
              {"option": "-map", "argument": "[outa]"},
              {"option": "-c:v", "argument": "libx264"},
              {"option": "-c:a", "argument": "aac"}
          ]}
        ],
        "metadata": { "duration": true },
        "id": "merged-video",
        "webhook_url": "https://yourapp.com/webhook/ffmpeg_done"
      }'

图像接口

/v1/image/convert/video

参数列表

参数名	类型	必填	默认值	说明
image_url	String	是	无	源图像URL
duration	Number	否	~5.0	输出视频时长（秒）
zoom	Boolean	否	true	是否启用图片缓慢缩放效果
id	String	否	无	任务ID
webhook_url	String	否	无	回调URL，处理完成通知

示例 curl 请求：

curl -X POST "https://<host>/v1/image/convert/video" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "image_url": "https://example.com/picture.png",
        "duration": 8,
        "zoom": true,
        "id": "picture-video",
        "webhook_url": "https://yourapp.com/webhook/image_video_done"
      }'

媒体处理接口

/v1/media/convert

参数列表

参数名	类型	必填	默认值	说明
media_url	String	是	无	源媒体文件URL，音频或视频均可
format	String	是	无	目标格式（文件扩展名），如 “mp4”、“mp3” 等
video_codec	String	否	auto	视频编码器，如 “libx264”、“hevc” 等。不指定则自动选择
audio_codec	String	否	auto	音频编码器，如 “aac”、“mp3” 等。不指定自动选择
crf	Number	否	encoder默认	视频质量系数（0-51），仅视频有用
preset	String	否	encoder默认	视频编码预设（fast, medium等），仅视频有用
bitrate	String	否	encoder默认	音频比特率，如 “128k”
id	String	否	无	任务ID
webhook_url	String	否	无	回调URL

示例 curl 请求：

curl -X POST "https://<host>/v1/media/convert" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "media_url": "https://example.com/input.mov",
        "format": "mp4",
        "video_codec": "libx264",
        "audio_codec": "aac",
        "crf": 20,
        "preset": "fast",
        "id": "mov-to-mp4",
        "webhook_url": "https://yourapp.com/webhook/convert_done"
      }'

/v1/media/convert/mp3

参数列表

参数名	类型	必填	默认值	说明
media_url	String	是	无	源媒体URL，可为视频（提取音频）或音频
bitrate	String	否	“128k”	输出MP3比特率
id	String	否	无	任务ID
webhook_url	String	否	无	回调URL

示例 curl 请求：

curl -X POST "https://<host>/v1/media/convert/mp3" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "media_url": "https://example.com/song.wav",
        "bitrate": "192k",
        "id": "song-mp3",
        "webhook_url": "https://yourapp.com/webhook/mp3_done"
      }'

/v1/BETA/media/download

参数列表

参数名	类型	必填	默认值	说明
source_url	String	是	无	要下载的网页视频/音频地址（如YouTube链接）
format	String	否	“best”	下载格式选项，例如 “bestaudio” 仅音频等
id	String	否	无	任务ID
webhook_url	String	否	无	回调URL，下载完成通知

示例 curl 请求：

curl -X POST "https://<host>/v1/media/download" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "source_url": "https://www.youtube.com/watch?v=abc12345",
        "format": "best",
        "id": "yt-video-01",
        "webhook_url": "https://yourapp.com/webhook/download_done"
      }'

/v1/media/feedback

参数列表

参数名	类型	必填	默认值	说明
media_id	String	否	无	要收集反馈的媒体ID（Toolkit生成内容）
file_url	String	否	无	或者直接提供媒体文件URL，用于反馈界面播放
mode	String	否	“rating”	反馈模式：如 “rating”（评分）、“comment”（评论）等，决定界面表单
id	String	否	无	此次反馈会话ID，用于区分不同反馈活动

（注：该接口返回HTML页面，通常不通过curl获取结果，因此这里不提供curl示例，请直接在浏览器访问或通过集成工具获取session链接。）

/v1/media/transcribe

参数列表

参数名	类型	必填	默认值	说明
media_url	String	是	无	源音频/视频URL
language	String	否	auto	语音语言代码，用于更准确识别，不提供则自动检测
translate_to	String	否	无	翻译目标语言代码，如提供则输出翻译后的文本
output_format	String	否	“text”	输出格式：“text” 纯文本，“srt” 字幕等
id	String	否	无	任务ID
webhook_url	String	否	无	回调URL，转录完成通知

示例 curl 请求：

curl -X POST "https://<host>/v1/media/transcribe" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "media_url": "https://example.com/speech.mp3",
        "language": "en",
        "translate_to": "zh",
        "output_format": "srt",
        "id": "speech-subs",
        "webhook_url": "https://yourapp.com/webhook/transcribe_done"
      }'

/v1/media/silence

参数列表

参数名	类型	必填	默认值	说明
media_url	String	是	无	源音频/视频URL
threshold	Number	否	-40.0	静音判定阈值（dB），低于该音量视为静音
min_duration	Number	否	1.0	最短静音持续时间（秒），短于此的不算静音段
id	String	否	无	任务ID
webhook_url	String	否	无	回调URL，检测完成通知

示例 curl 请求：

curl -X POST "https://<host>/v1/media/silence" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "media_url": "https://example.com/meeting.mp4",
        "threshold": -35,
        "min_duration": 2,
        "id": "meeting-silences",
        "webhook_url": "https://yourapp.com/webhook/silence_done"
      }'

/v1/media/metadata

参数列表

参数名	类型	必填	默认值	说明
media_url	String	是	无	媒体文件URL
id	String	否	无	任务ID
webhook_url	String	否	无	回调URL，分析完成通知

示例 curl 请求：

curl -X POST "https://<host>/v1/media/metadata" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "media_url": "https://example.com/video.mp4",
        "id": "video-metadata"
      }'

S3 接口

/v1/s3/upload

参数列表

参数名	类型	必填	默认值	说明
file_url	String	是	无	源文件URL（HTTP/HTTPS）
file_name	String	否	自动解析	上传到S3后的文件名（可含路径），默认用源文件名或随机
bucket	String	否	默认配置	目标存储桶名称，不提供则用环境变量配置的BUCKET
id	String	否	无	任务ID
webhook_url	String	否	无	回调URL，上传完成通知

示例 curl 请求：

curl -X POST "https://<host>/v1/s3/upload" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://example.com/file.mp4",
        "file_name": "2025/01/file.mp4",
        "id": "upload-202501-file",
        "webhook_url": "https://yourapp.com/webhook/upload_done"
      }'

工具箱接口

/v1/toolkit/authenticate

(此接口为 GET 请求，无请求体)

参数名 (查询)	类型	必填	默认值	说明
（无）	–	–	–	无请求参数，使用Header携带x-api-key即可

示例 curl 请求：

curl -X GET "https://<host>/v1/toolkit/authenticate" \
  -H "x-api-key: YOUR_API_KEY"

(成功返回 { “code”: 200, “authenticated”: true })

/v1/toolkit/test

(此接口为 GET 请求，无请求体)

参数名 (查询)	类型	必填	默认值	说明
（无）	–	–	–	无需参数，调用前需配置好存储等，验证服务正常

示例 curl 请求：

curl -X GET "https://<host>/v1/toolkit/test" \
  -H "x-api-key: YOUR_API_KEY"

(成功返回任务ID和测试结果文件路径，如 response 指向 success.txt 文件)

/v1/toolkit/job/status

参数列表

(此接口为 GET 请求)

参数名 (查询)	类型	必填	默认值	说明
job_id	String	是	无	要查询状态的任务ID

示例 curl 请求：

curl -X GET "https://<host>/v1/toolkit/job/status?job_id=YOUR_JOB_ID" \
  -H "x-api-key: YOUR_API_KEY"

(返回指定任务的状态及结果，结构参见正文说明)

/v1/toolkit/jobs/status

参数列表

(此接口为 GET 请求)

参数名 (查询)	类型	必填	默认值	说明
start	String	否	(无，默认最近)	查询的开始时间（ISO8601或时间戳）
end	String	否	当前时间	查询的结束时间（ISO8601或时间戳）

示例 curl 请求：

curl -X GET "https://<host>/v1/toolkit/jobs/status?start=2025-01-01T00:00:00Z&end=2025-01-02T00:00:00Z" \
  -H "x-api-key: YOUR_API_KEY"

(返回指定时间段内任务列表及状态)

视频处理接口

/v1/video/caption

参数列表

参数名	类型	必填	默认值	说明
video_url	String	是	无	源视频URL
replace	Array	否	无	文本替换列表。每项{find, replace}定义替换规则
settings	Object	否	内置默认	字幕样式设置对象（颜色、字体、位置等参数），详见上文
id	String	否	无	任务ID
webhook_url	String	否	无	回调URL，字幕生成完成通知

示例 curl 请求：

curl -X POST "https://<host>/v1/video/caption" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "video_url": "https://example.com/video.mp4",
        "replace": [ { "find": "badword", "replace": "***" } ],
        "settings": {
          "font_family": "Arial",
          "font_size": 60,
          "word_color": "#FFFF00",
          "line_color": "#FFFFFF",
          "all_caps": false,
          "bold": false,
          "italic": false,
          "underline": false,
          "strikeout": false,
          "outline_width": 3,
          "shadow_offset": 4,
          "position": "bottom_center",
          "max_words_per_line": 3,
          "style": "highlight"
        },
        "id": "video-caption-01",
        "webhook_url": "https://yourapp.com/webhook/caption_done"
      }'

/v1/video/concatenate

参数列表

参数名	类型	必填	默认值	说明
video_urls	Array	是	无	视频URL列表，每项为{“video_url”: “<链接>”}对象
id	String	否	无	任务ID，用于标识输出视频
webhook_url	String	否	无	回调URL，合并完成通知

示例 curl 请求：

curl -X POST "https://<host>/v1/video/concatenate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "video_urls": [
          {"video_url": "https://example.com/part1.mp4"},
          {"video_url": "https://example.com/part2.mp4"}
        ],
        "id": "combined-video",
        "webhook_url": "https://yourapp.com/webhook/video_concat_done"
      }'

/v1/video/thumbnail

参数列表

参数名	类型	必填	默认值	说明
video_url	String	是	无	源视频URL
timestamp	String/Number	否	“00:00:01”	截帧时间点，字符串格式HH:MM:SS或秒数
output_format	String	否	“jpg”	输出图像格式，如 “jpg”、“png”
id	String	否	无	任务ID
webhook_url	String	否	无	回调URL，截图完成通知

示例 curl 请求：

curl -X POST "https://<host>/v1/video/thumbnail" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "video_url": "https://example.com/movie.mp4",
        "timestamp": "00:00:10.0",
        "output_format": "png",
        "id": "movie-thumb",
        "webhook_url": "https://yourapp.com/webhook/thumb_done"
      }'

/v1/video/cut

参数列表

参数名	类型	必填	默认值	说明
video_url	String	是	无	源视频URL
cuts	Array	是	无	要剪除的片段列表，每项包含start和end时间
output_format	String	否	源格式	输出视频格式，如需改变可指定（如 “mp4”, “gif”）
id	String	否	无	任务ID
webhook_url	String	否	无	回调URL，剪辑完成通知

示例 curl 请求：

curl -X POST "https://<host>/v1/video/cut" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "video_url": "https://example.com/film.mp4",
        "cuts": [
          {"start": "00:10:00", "end": "00:12:30"},
          {"start": "00:20:00", "end": "00:21:00"}
        ],
        "id": "film-cut",
        "webhook_url": "https://yourapp.com/webhook/cut_done"
      }'

/v1/video/split

参数列表

参数名	类型	必填	默认值	说明
video_url	String	是	无	源视频URL
segments	Array	是	无	拆分片段列表，每项包含start和end时间
output_format	String	否	源格式	输出格式，不指定则与源相同
id	String	否	无	任务ID（可用作输出文件命名前缀）
webhook_url	String	否	无	回调URL，拆分完成通知

示例 curl 请求：

curl -X POST "https://<host>/v1/video/split" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "video_url": "https://example.com/footage.mp4",
        "segments": [
          {"start": "00:00:00", "end": "00:05:00"},
          {"start": "00:05:00", "end": "00:10:00"}
        ],
        "id": "footage-part",
        "webhook_url": "https://yourapp.com/webhook/split_done"
      }'

/v1/video/trim

参数列表

参数名	类型	必填	默认值	说明
video_url	String	是	无	源视频URL
start	String/Number	是	无	保留片段的起始时间
end	String/Number	是	无	保留片段的结束时间
output_format	String	否	源格式	输出格式，不指定则源格式
id	String	否	无	任务ID
webhook_url	String	否	无	回调URL，裁剪完成通知

示例 curl 请求：

curl -X POST "https://<host>/v1/video/trim" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "video_url": "https://example.com/show.mp4",
        "start": "00:10:00",
        "end": "00:15:00",
        "id": "show-clip",
        "webhook_url": "https://yourapp.com/webhook/trim_done"
      }'

以上即为 No-Code Architects Toolkit 项目所有API接口的参数和示例全集。在实际使用中，请根据需要调整参数值和顺序。希望本教程报告能够帮助您在 n8n、Make.com 等平台上快速上手 Toolkit，打造属于自己的强大媒体内容自动化流程！

Make中文教程：自动化基础

小红书自动化：如何利用Make制作个人自媒体中心，批量生成爆款笔记

微信公众号图文混排文章自动化实战：利用Make 批量制作

翔宇工作流

海外AI服务支付解决方案探讨：国内虚拟卡使用教程

小白也能搞懂！从零开始玩转AI大模型全指南

新手必看：用虚拟信用卡 BinGoCard 注册并使用 Google 云服务器