跳转到正文
中文
获取 API 密钥
浏览文档

开始使用

常见问题与故障排查

检查访问权限、修复失败请求,或查找 FlashData 使用问题的答案。

本页内容

先免费检查访问权限

在任务失败的运行环境中检查,并复用已有凭据;这些命令不会提交查询。

使用 CLI 已保存的访问。使用命名配置时,在每条命令后追加 --profile NAME。这些读取不消耗查询 Credits。

免费账户读取
flashdata --version
flashdata doctor --offline
flashdata auth status --json

检查哪些字段

身份应包含 access: ready,且 scopes 含所需来源。CLI JSON 的身份位于 data.identity.identity,还需确认 data.accessVerified: true。命令成功但 accessVerified: false 不表示访问已验证。

若使用命名 CLI 配置,在下方每条命令后追加 --profile NAME,并保持原 --state-dir 和系统用户。FLASHDATA_API_KEY 会覆盖 CLI 保存的密钥;SDK 与 MCP 宿主使用各自的凭据配置。

按问题修复

展开与错误对应的现象,使用原任务的 ID 与回执。

找不到命令或配置

找不到程序:安装匹配系统/CPU 的版本,将目录加入 PATH。缺少配置:使用原系统用户与状态目录。也要在调度器或容器内检查。

定位可执行文件
command -v flashdata
flashdata --version
flashdata doctor --offline

401 / 403:密钥、权限或有效期

替换已保存的所有者密钥时,将已授权密钥粘贴到隐藏提示。若已设置 FLASHDATA_API_KEY,应更新运行环境中的该密钥;保存另一个 CLI 密钥不会覆盖它。

  1. 401:检查密钥是否过期、被撤销或配置错误。403:将请求来源与身份的 scopes 比较。
  2. REST 与 SDK 使用 X-API-Key。MCP OAuth Token 不能代替 API Key。临时访问请使用下方认领恢复方法。
替换并验证已保存的所有者密钥
flashdata auth login --replace
flashdata auth status --json

认领已批准,但智能体仍使用试用访问

在创建认领的同一 CLI 配置中完成凭据交接。所有者在浏览器完成注册、邮箱验证与授权,CLI 接收凭据。

完成并验证
flashdata auth finish --wait --timeout 10m
flashdata auth status --json

402:额度不足

将 availableCredits 与所需来源的当前价格比较。试用耗尽时认领并使用所有者余额,或由所有者检查账单后再重试。

使用 CLI 已保存的访问。使用命名配置时,在每条命令后追加 --profile NAME。这些读取不消耗查询 Credits。

免费账户读取
flashdata account balance
flashdata account pricing --source google_search --request-count 1

429:等待后重试

读取失败响应的 Retry-After,值为秒数或 HTTP 日期。等待指定时间并降低并发。试用注册限制为每个 IP 每 24 小时窗口三次,应复用原配置与注册凭证。

以下免费读取演示保存响应头、状态及响应体。应使用失败操作返回的 Retry-After;查询、注册和账户读取的限制可能不同。

保存响应 · Bash / cURL / jq
# Bash + cURL + jq. This is a free account read.
(
test -n "$FLASHDATA_API_KEY" || { printf 'Set FLASHDATA_API_KEY first\n' >&2; exit 1; }
curl --silent --show-error --max-time 20 \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --dump-header diagnostic-headers.txt --output diagnostic.json \
  --write-out '%{http_code}\n' \
  'https://api.flashdata.dev/v2/api-access/identity' > diagnostic-status.txt || exit
printf 'HTTP '; cat diagnostic-status.txt
awk 'tolower($1) == "retry-after:" {
  $1=""; sub(/^ /, ""); sub(/\r$/, ""); print "Retry-After: " $0
}' diagnostic-headers.txt
if jq -e 'type == "object"' diagnostic.json >/dev/null 2>&1; then
  jq '{access, scopes, status, code, requestId}
    | with_entries(select(.value != null))' diagnostic.json
else
  printf 'Non-JSON response saved in diagnostic.json; check the HTTP status.\n'
fi
)
检查账户容量
flashdata account limits

400 / 422:输入被拒绝或处理失败

读取 HTTP 错误的 code、detail 与 fieldErrors,修正请求体并保存为 request.json,再执行校验。下载存储凭据需保存在私有输入文件中。若 422 来自已有任务的结果,应先检查 job.error。

校验而不提交付费任务
flashdata query --input request.json --mode async --dry-run --json

任务等待,或 HTTP 200 但任务失败

读取 submission.json(已保存的异步回执)对应的任务。HTTP 200 表示状态读取成功,job.status 才是任务结果(CLI JSON 中为 data.status)。Batch 请将 queries 中对应的一项保存为 submission.json。

状态或错误下一步
pending / processing等待同一任务,不要重新提交。
completed获取并保存已有结果。
failed检查 job.error 后再提交修正后的任务。
404检查任务 ID 与提交任务的账户。
409结果尚未就绪,继续轮询同一任务。
410保存的 JSON 在 24 小时后到期。使用本地副本;已交付媒体采用目标存储的保留策略。
检查已保存任务 · Bash / jq
# Bash + jq. CLI receipts use remoteId; HTTP receipts use id.
(
set -e
JOB_ID=$(jq -er '.remoteId // .id' submission.json)
flashdata jobs get "$JOB_ID" --json
)
仍在运行 · 使用返回的 JOB_ID
flashdata jobs wait JOB_ID
已完成 · 使用新的输出文件名
flashdata jobs result JOB_ID --output recovered-result.json

超时 / 5xx:任务是否已接纳?

重试 POST 前检查原运行与请求历史,恢复已确认接纳的任务。如果接纳状态不明,保留运行 ID 并联系支持;更换 ID 重提可能重复收费。

先检查 · 替换 RUN_ID
flashdata runs show RUN_ID
恢复已确认接纳的任务
flashdata runs recover RUN_ID

CLI output_exists:结果文件已存在

CLI 不会覆盖 --output 文件。读取已有文件,或保留原 --run-id 与请求,仅选择新的输出文件名。不要为了绕过此错误而更换运行 ID。

检查原运行
flashdata runs show RUN_ID

搜索为空、字幕缺失或下载不可读

这些命令只读取本地结果文件,而非 CLI 标准输出的封装。

MCP 工具缺失或认证过期

检查执行任务的宿主。列出服务只能证明已有配置,不代表连接成功。若已配置的托管 OAuth 连接提示需要登录,运行对应登录命令并完成浏览器授权,再刷新工具列表。

在 Codex CLI 中打开 /mcp 检查连接状态与工具。在应用中检查已配置服务,并在更改配置后开启新会话。

检查配置
codex mcp list
仅在需要 OAuth 登录时
codex mcp login flashdata --scopes mcp:research

已安装技能,但智能体找不到或无法使用

检查相同项目、宿主配置及安装位置,然后开启新的智能体会话。CLI 任务技能需要 CLI,flashdata-mcp 需要已连接的 MCP 服务。安装技能不会连接服务或授予账户权限。

检查默认 CLI 技能包
flashdata skills verify --agent codex

常见问题

接入与连接

必须使用 AI 智能体吗?

不需要,可直接使用 HTTP API、Go/Python/TypeScript SDK、CLI 或控制台。MCP 和技能是智能体可选的额外接入方式。

应该选择哪种接入方式?

应用内使用 SDK 或 HTTP API,终端任务使用 CLI,支持 MCP 的宿主使用 MCP。技能提供 CLI 任务或已连接 MCP 工具的使用指令,不代替认证。

定时任务能复用凭据吗?

可以。使用所有者访问,并保留相同的受保护 CLI 配置、运行环境密钥或 MCP 连接。API Key 访问需检查 recurringAllowed: true。计划由宿主或调度器执行。

删除本地配置会撤销访问吗?

不会。应在控制台撤销 API Key 或连接;删除本地配置仅移除本地副本。

试用与额度

智能体能在注册前试用 FlashData 吗?

可以,通过 CLI 或接入 API 获取符合资格的临时访问。复用相同配置和注册凭证。继续使用需要认领,或使用已有所有者 API Key。

认领会再赠送一份试用额度吗?

认领本身不额外赠送试用额度。后续请求使用所有者账户余额,未用完的临时额度不转入。新创建的账户遵循正常注册赠送额度政策。

我的额度能支持多少次请求?

检查账户余额与来源价格。请求数量取决于来源,不同来源的任务共用同一余额。YouTube 下载按下载字节计价,而不是固定请求次数。

来源与结果

为什么智能体能搜索但不能下载?

下载需要所有者访问、youtube_download 权限与目标存储。临时试用及 mcp:research OAuth 不含下载。已授权的所有者 API Key 可通过 CLI、HTTP 或 MCP 使用下载。

Google 搜索返回完整网页吗?

返回搜索结果及摘要,由应用或智能体读取选定 URL。

FlashData 会生成视频摘要或字幕吗?

获取元数据及现有字幕,不生成缺失字幕;模型可根据可用结果撰写摘要。

仍未解决?提供最小支持信息

将 HTTP 错误响应体,或 CLI 标准错误流中的 JSON 错误保存为 diagnostic.json,仅在命令失败后提取标识。报告中不提供密钥、私密查询或签名 URL。非 JSON 响应则报告 diagnostic-status.txt 中的 HTTP 状态。

保存免费 CLI 访问检查的错误 · Bash
flashdata auth status --json 2> diagnostic.json
提取错误标识 · Bash / jq
# A saved HTTP error or CLI --json error; local files only.
date -u '+%Y-%m-%dT%H:%M:%SZ'
jq '(.error // .) as $e | {
  status: ($e.httpStatus // $e.status),
  code: $e.code,
  requestId: $e.requestId,
  runId: (.runId // $e.runId),
  jobId: $e.remoteId,
  retryAfter: $e.retryAfter
} | with_entries(select(.value != null))' diagnostic.json
支持报告
UTC 时间:
客户端及版本:
来源及阶段(认证 / 提交 / 轮询 / 获取):
HTTP 状态及错误码:
请求 ID / 任务 ID / 运行 ID:
提交结果:已接纳 / 已拒绝 / 不确定
预期结果与实际结果: