浏览文档
开始使用
检查访问权限、修复失败请求,或查找 FlashData 使用问题的答案。
本页内容
先免费检查访问权限
在任务失败的运行环境中检查,并复用已有凭据;这些命令不会提交查询。
使用 CLI 已保存的访问。使用命名配置时,在每条命令后追加 --profile NAME。这些读取不消耗查询 Credits。
flashdata --version
flashdata doctor --offline
flashdata auth status --json在相同终端、容器或定时任务中,使用该任务已有的 FLASHDATA_API_KEY。需要 cURL 7.76+。
(
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
curl --fail-with-body --silent --show-error --max-time 20 \
--header "X-API-Key: $FLASHDATA_API_KEY" \
'https://api.flashdata.dev/v2/api-access/identity' || exit
printf '\n'
)在相同终端、容器或定时任务中,使用该任务已有的 FLASHDATA_API_KEY。
& {
$ErrorActionPreference = 'Stop'
if ([string]::IsNullOrWhiteSpace($env:FLASHDATA_API_KEY)) {
throw 'Set FLASHDATA_API_KEY first'
}
$flashdataHeaders = @{ 'X-API-Key' = $env:FLASHDATA_API_KEY }
$flashdataBase = 'https://api.flashdata.dev/v2'
$flashdataUri = "$flashdataBase/api-access/identity"
Invoke-RestMethod -Uri $flashdataUri `
-Headers $flashdataHeaders -TimeoutSec 20 -MaximumRedirection 0 |
ConvertTo-Json -Depth 20
}检查哪些字段
身份应包含 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 与回执。
找不到命令或配置
401 / 403:密钥、权限或有效期
认领已批准,但智能体仍使用试用访问
在创建认领的同一 CLI 配置中完成凭据交接。所有者在浏览器完成注册、邮箱验证与授权,CLI 接收凭据。
flashdata auth finish --wait --timeout 10m
flashdata auth status --json为已有试用申请新链接,让所有者批准,再执行 auth finish。不要重新运行 init。
flashdata auth claim402:额度不足
将 availableCredits 与所需来源的当前价格比较。试用耗尽时认领并使用所有者余额,或由所有者检查账单后再重试。
使用 CLI 已保存的访问。使用命名配置时,在每条命令后追加 --profile NAME。这些读取不消耗查询 Credits。
flashdata account balance
flashdata account pricing --source google_search --request-count 1在相同终端、容器或定时任务中,使用该任务已有的 FLASHDATA_API_KEY。需要 cURL 7.76+。
(
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
curl --fail-with-body --silent --show-error --max-time 20 \
--header "X-API-Key: $FLASHDATA_API_KEY" \
'https://api.flashdata.dev/v2/api-access/balance' || exit
printf '\n'
curl --fail-with-body --silent --show-error --max-time 20 \
--header "X-API-Key: $FLASHDATA_API_KEY" \
'https://api.flashdata.dev/v2/api-access/pricing?source=google_search&request_count=1' || exit
printf '\n'
)在相同终端、容器或定时任务中,使用该任务已有的 FLASHDATA_API_KEY。
& {
$ErrorActionPreference = 'Stop'
if ([string]::IsNullOrWhiteSpace($env:FLASHDATA_API_KEY)) {
throw 'Set FLASHDATA_API_KEY first'
}
$flashdataHeaders = @{ 'X-API-Key' = $env:FLASHDATA_API_KEY }
$flashdataBase = 'https://api.flashdata.dev/v2'
$flashdataUri = "$flashdataBase/api-access/balance"
Invoke-RestMethod -Uri $flashdataUri `
-Headers $flashdataHeaders -TimeoutSec 20 -MaximumRedirection 0 |
ConvertTo-Json -Depth 20
$flashdataUri = "$flashdataBase/api-access/pricing?source=google_search&request_count=1"
Invoke-RestMethod -Uri $flashdataUri `
-Headers $flashdataHeaders -TimeoutSec 20 -MaximumRedirection 0 |
ConvertTo-Json -Depth 20
}429:等待后重试
读取失败响应的 Retry-After,值为秒数或 HTTP 日期。等待指定时间并降低并发。试用注册限制为每个 IP 每 24 小时窗口三次,应复用原配置与注册凭证。
以下免费读取演示保存响应头、状态及响应体。应使用失败操作返回的 Retry-After;查询、注册和账户读取的限制可能不同。
# 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 limits400 / 422:输入被拒绝或处理失败
任务等待,或 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. CLI receipts use remoteId; HTTP receipts use id.
(
set -e
JOB_ID=$(jq -er '.remoteId // .id' submission.json)
flashdata jobs get "$JOB_ID" --json
)flashdata jobs wait JOB_IDflashdata jobs result JOB_ID --output recovered-result.json# Bash + cURL + jq. Read the saved async submission receipt.
(
set -e
test -n "$FLASHDATA_API_KEY" || { printf 'Set FLASHDATA_API_KEY first\n' >&2; exit 1; }
STATUS_URL=$(jq -er '(.submission // .).links[]
| select(.rel == "self") | .href' submission.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--header 'Accept: application/json' \
"$STATUS_URL" --output job.json
jq '.job | {id, status, error}' job.json
)超时 / 5xx:任务是否已接纳?
CLI output_exists:结果文件已存在
CLI 不会覆盖 --output 文件。读取已有文件,或保留原 --run-id 与请求,仅选择新的输出文件名。不要为了绕过此错误而更换运行 ID。
flashdata runs show RUN_ID搜索为空、字幕缺失或下载不可读
这些命令只读取本地结果文件,而非 CLI 标准输出的封装。
若 status 为 done 且 organic 为空,应放宽筛选,并在任务记录中保留空结果。
jq '{status, usage, resultCount: (.results | length)}' result.json
jq '(.results[0].organic // []) | length' result.json元数据列出语言代码,不区分人工或自动字幕。选择已列出的语言,并明确设置 auto:true 为自动,false 为人工。没有匹配轨道表示该选择无字幕;FlashData 不会生成替代字幕。
jq '.results[0].transcriptLanguages' metadata.json读取已完成的 delivery.json 回执。通过目标存储凭据下载对象,再比较大小与 MD5。私有 file_url 不会因交付完成而变成公开链接。
jq '.results[0] | {file_url, file_size, md5}' delivery.jsonMCP 工具缺失或认证过期
检查执行任务的宿主。列出服务只能证明已有配置,不代表连接成功。若已配置的托管 OAuth 连接提示需要登录,运行对应登录命令并完成浏览器授权,再刷新工具列表。
在 Codex CLI 中打开 /mcp 检查连接状态与工具。在应用中检查已配置服务,并在更改配置后开启新会话。
codex mcp listcodex mcp login flashdata --scopes mcp:researchopenclaw mcp doctor flashdata --probeopenclaw mcp login flashdata
openclaw mcp doctor flashdata --probeOAuth 登录不能修复 API Key 连接。检查宿主环境中的密钥及来源权限。本地 stdio 还需检查 MCP 包的 Node.js 要求,并在更新环境后重启宿主。
node --version已安装技能,但智能体找不到或无法使用
常见问题
接入与连接
必须使用 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 状态。
flashdata auth status --json 2> diagnostic.json# 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.jsonUTC 时间:
客户端及版本:
来源及阶段(认证 / 提交 / 轮询 / 获取):
HTTP 状态及错误码:
请求 ID / 任务 ID / 运行 ID:
提交结果:已接纳 / 已拒绝 / 不确定
预期结果与实际结果: