通过 URL 使用 Dataify 下载 YouTube 音频

通过 Dataify Builder 的 URL 功能提交 YouTube 音频文件采集任务。成功提交后，向用户提供 task_id、返回或推断出的状态，并告知其访问 Dataify 查看结果。

API TOKEN 处理

使用 DATAIFY_API_TOKEN 作为长期保存的令牌名称。

• 若用户在请求中提供了令牌，则本次运行直接使用该令牌。
• 若未提供令牌，首先检查本地环境是否已保存 DATAIFY_API_TOKEN。
• 若 DATAIFY_API_TOKEN 已在本地保存，则直接使用，无需提示用户重新输入令牌。
• 若本地无可用令牌，告知用户需提供 Dataify API TOKEN。
• 若用户尚无 API TOKEN，告知其可前往 Dataify 注册或登录获取。
• 若用户已有 API TOKEN，告知其可在 Dataify 页面右上角找到该令牌。
• 当用户提供了 API TOKEN 且本地尚未保存 DATAIFY_API_TOKEN 时，询问其是否希望将该令牌以 DATAIFY_API_TOKEN 名称本地保存供后续使用。
• 若用户选择保存，请提供适用于其 Shell 的命令并请其手动执行；切勿未经确认静默持久化令牌。
• 禁止在无有效令牌的情况下调用 Builder 接口。
• 面向用户的说明中统一使用 API TOKEN 表述；本地保存场景优先使用环境变量名 DATAIFY_API_TOKEN。

PowerShell 中为当前会话保存令牌的示例：

$env:DATAIFY_API_TOKEN = "YOUR_DATAIFY_API_TOKEN"

在 Windows 上设置持久化的用户级环境变量：

[Environment]::SetEnvironmentVariable("DATAIFY_API_TOKEN", "YOUR_DATAIFY_API_TOKEN", "User")

核心工作流

1. 提交前，向用户展示参数清单中列出的必需参数、共享参数、可选参数及默认值。
2. 对于下拉字段，以 Markdown 表格形式完整列出所有允许选项，表格须包含 Label 和 Value 两列。使用命令 scripts/submit_dataify_youtube_audio_by_url.py --list-options 输出完整的下拉选项表。
3. 询问用户是否要在运行任务前修改任意参数值。
4. 询问用户是否要采集多个 YouTube 音频文件。若为是，请用户输入多个 url 值。
5. 将最终的 url 值规范化为 spider_parameters 对象列表。
6. 将 bitrate、audio_format、subtitles_language、kilohertz、is_subtitles 和 selected_only 规范化为一个共享的 spider_universal 对象。
7. 从显式输入或已保存的 DATAIFY_API_TOKEN 中解析 Dataify 令牌。
8. 若无可用令牌，提示用户输入其 API TOKEN，并询问是否将其保存为 DATAIFY_API_TOKEN。
9. 校验每个 URL、下拉值、kilohertz 方向、bitrate 方向及文件名。
10. 提交 Builder 请求以创建任务。
11. 从 Builder 响应中读取 data.task_id，并在响应中存在时读取 data.status 或 status。
12. Builder 成功后即终止流程。
13. 告知用户前往 Dataify 查看或管理结果。

参数清单

当用户调用本技能时，首先告知其以下参数将被使用。始终以 Markdown 表格形式展示已提交参数；禁止使用纯文本句子或项目符号列表进行参数确认。

随后询问：“您是否要在提交任务前修改其中任意值？”

同时询问：“您是否要采集多个 YouTube 音频文件？若是，请提供多个 url 值。”

对于 kilohertz 和 bitrate，需询问用户所选值应采用 <= 还是 >=；若用户未指定方向，默认采用 <=。

若用户已提供部分参数值，则在参数确认表中显示这些值，仅就剩余未提供或使用默认值的参数询问是否需要修改。

下拉选项

在请用户选择下拉值之前，须以 Markdown 表格形式完整列出所有允许选项，表格须包含 Label 和 Value 两列。

使用以下命令打印完整选项表：

python3 ".scriptssubmit_dataify_youtube_audio_by_url.py" --list-options

若系统中不可用 python3，请使用该机器上可用的 Python 3 命令（例如 python）。

该脚本将输出：

• kilohertz 可选项。
• kilohertz_direction 可选项。
• audio_format 可选项。
• bitrate 可选项。
• bitrate_direction 可选项。
• subtitles_language 可选项，其中 Label 字段使用提供的 cn 值，Value 字段使用 typeValue 值。
• is_subtitles 可选项。
• selected_only 可选项。

参数处理

• url 为必需参数。若用户未提供，仅在参数确认表中展示后才使用默认值 https://www.youtube.com/watch?v=_SdpvpvVrLY。
• 去除 url 前后空白字符。
• url 不得为空。
• url 必须以 https://www.youtube.com/ 开头。
• 多组采集仅在 spider_parameters 内重复 url 字段。
• bitrate、audio_format、subtitles_language、kilohertz、is_subtitles 和 selected_only 为共享参数，须统一置于 spider_universal 中，不得放入每个 spider_parameters 对象内。
• kilohertz 默认值为 48000，kilohertz_direction 默认值为 <=；提交时组合为 <=48000。
• bitrate 默认值为 320，bitrate_direction 默认值为 <=；提交时组合为 <=320。
• audio_format 默认值为 opus；允许值为 opus 和 m4a。
• subtitles_language 默认值为 ab。
• is_subtitles 默认值为 false。
• selected_only 默认值为 false。
• file_name 默认值为 {{TasksID}}；若用户修改，则提交其提供的值。
• file_name 不得为空。

单组采集示例：

spider_parameters=[{"url":"https://www.youtube.com/watch?v=_SdpvpvVrLY"}]
spider_universal={"bitrate":"<=320","audio_format":"opus","subtitles_language":"ab","kilohertz":"<=48000","is_subtitles":"false","selected_only":"false"}

多组采集示例：

spider_parameters=[{"url":"https://www.youtube.com/watch?v=_SdpvpvVrLY"},{"url":"https://www.youtube.com/watch?v=_SdpvpvVrLY"}]
spider_universal={"bitrate":"<=320","audio_format":"opus","subtitles_language":"ab","kilohertz":"<=48000","is_subtitles":"false","selected_only":"false"}

Dataify Builder 请求

使用表单字段而非手动构造的 URL 编码字符串。

• URL：https://scraperapi.dataify.com/builder?platform=1
• 方法：POST
• 认证请求头：Bearer DATAIFY_API_TOKEN
• 内容类型：application/x-www-form-urlencoded
• 固定字段：
  • spider_name=youtube.com
  • spider_id=youtube_audio_by-url
  • spider_errors=true
• 默认字段：
  • file_name={{TasksID}}
• 动态字段：
  • spider_parameters 必须为 JSON 字符串数组，元素为 URL 对象。
  • spider_universal 必须为 JSON 字符串对象，包含共享音频设置。

脚本

为确保稳定执行，建议优先使用 Python 3.6 或更高版本运行 scripts/submit_dataify_youtube_audio_by_url.py，而非重写 Builder 流程。

python3 ".scriptssubmit_dataify_youtube_audio_by_url.py" --url "https://www.youtube.com/watch?v=_SdpvpvVrLY"

如需为单次运行覆盖已保存的环境令牌或默认共享参数：

python3 ".scriptssubmit_dataify_youtube_audio_by_url.py" --api-token "YOUR_DATAIFY_API_TOKEN" --url "https://www.youtube.com/watch?v=_SdpvpvVrLY" --kilohertz "48000" --kilohertz-direction "<=" --audio-format "opus" --bitrate "320" --bitrate-direction "<=" --subtitles-language "ab" --is-subtitles "false" --selected-only "false" --file-name "{{TasksID}}"

提交多个 URL：

python3 ".scriptssubmit_dataify_youtube_audio_by_url.py" --params-json '[{"url":"https://www.youtube.com/watch?v=_SdpvpvVrLY"},{"url":"https://www.youtube.com/watch?v=_SdpvpvVrLY"}]'

脚本将输出包含 task_id、status、parameters、spider_universal、file_name、dashboard_url 和 message 的 JSON 汇总信息。

故障排查

Missing Dataify API TOKEN 表示未显式传入令牌，且本地未保存 DATAIFY_API_TOKEN。此时应告知用户需提供其 Dataify API TOKEN，询问是否要将其保存为 DATAIFY_API_TOKEN，或告知其可前往 Dataify 注册或登录获取。若用户已有令牌，应告知其位于 Dataify 页面右上角。

url cannot be empty 表示必需的 YouTube URL 缺失。

url must start with https://www.youtube.com/ 表示 URL 不在允许的 YouTube 域名范围内。

Unsupported kilohertz、Unsupported audio_format、Unsupported bitrate、Unsupported subtitles_language、Unsupported is_subtitles 或 Unsupported selected_only 表示该值不属于允许的下拉选项之一。

Unsupported kilohertz_direction 或 Unsupported bitrate_direction 表示该值必须为 <= 或 >=。

File name cannot be empty 表示未提供有效的 file_name。

Necessary parameters is empty! 通常表示 Builder 请求未以表单字段方式提交、spider_parameters 未按 JSON 字符串数组格式提供、spider_universal 未按 JSON 字符串对象格式提供，或某个 spider_parameters 对象缺少 url 字段。

缺失 task_id 通常表示认证请求头、令牌、spider_name、spider_id、spider_parameters 或 spider_universal 存在错误。

安全约束

• 禁止将 bitrate、audio_format、subtitles_language、kilohertz、is_subtitles 或 selected_only 放入 spider_parameters 中。
• 禁止遗漏 spider_universal。
• Builder 成功后禁止轮询结果。
• 仅在涉及身份验证时使用 API TOKEN 和 DATAIFY_API_TOKEN。
• 禁止硬编码本地 Python 路径。
• 禁止声称 Builder 响应中包含 YouTube 音频文件。
• 禁止虚构结果字段。
• 任务成功创建后，必须始终引导用户前往 Dataify。