agent-download 接口文档

POST /api/download — 提交下载

立即返回任务列表（异步执行）；用 /api/job/:id 轮询结果。

参数

请求示例

curl -X POST https://agent-download.kukukala.com/api/download \
  -H "x-auth-token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","resolution":"1080p"}'

响应示例

{ "jobs": [ { "jobId": "j_a1b2c3d4", "status": "queued", "platform": "youtube" } ] }

批量且含无效 URL 时逐个处理，无效项原样带回：

{ "jobs": [
  { "jobId": "j_a1b2c3d4", "status": "queued", "platform": "youtube" },
  { "url": "https://v.douyin.com/xxx", "rejected": true, "errorCode": "platform_not_supported" }
] }

GET /api/job/:id — 查询任务

curl -H "x-auth-token: $TOKEN" https://agent-download.kukukala.com/api/job/j_a1b2c3d4

{
  "jobId": "j_a1b2c3d4", "platform": "youtube", "status": "done", "progress": 100,
  "title": "…", "sizeBytes": 104857600, "durationS": 245.3,
  "error": null,
  "downloadUrl": "/file/j_a1b2c3d4?token=…",
  "expiresAt": 1759286400000, "attempt": 1
}

状态机：queued → dispatched → downloading → uploading → done | failed，另有 expired（48h 到期）。progress 为 0–1 浮点。error 形如 {"code":"youtube_blocked","message":"…","retryable":true}（见错误码表）。downloadUrl 仅 done 时返回，随查询实时签发、48h 内有效。

GET /api/status — 服务状态

curl -H "x-auth-token: $TOKEN" https://agent-download.kukukala.com/api/status

{
  "capacity": { "maxInstances": 1, "jobsPerInstance": 2, "globalInflightCap": 2,
                "inflight": 2, "queued": 3,
                "note": "预算值（软约束）：实际并发由派发闸控制，实例布局由 FC 决定" },
  "channels": { "youtube": { "target": 5, "current": 5, "inflight": 2, "queued": 3, "recentFailRate": 0.1 } },
  "instances": [ { "instanceId": "i_x", "startedAt": 1759200000000, "lastHeartbeatAt": 1759200090000, "activeJobs": ["j_a1b2c3d4"] } ],
  "jobs": [ /* 最近 50 条，元素同 /api/job 响应 */ ]
}

实例 90 秒内心跳视为存活；current 是频道并发池的当前上限（服务按失败自动降半、成功回升，介于 1 与 target 之间）。

GET / PUT /api/settings — 运行时设置

curl -X PUT https://agent-download.kukukala.com/api/settings \
  -H "x-auth-token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"maxInstances": 2, "jobsPerInstance": 2, "channelLimits": {"youtube": {"target": 3}}}'

GET /file/:jobId?token=… — 下载成品

downloadUrl 自带签名 token，无需再带 x-auth-token。支持 HEAD、Range 断点（206/416）、Content-Length，可直接喂给播放器。

# 整段下载
curl -OJ "https://agent-download.kukukala.com/file/j_a1b2c3d4?token=…"
# 断点续传（Range）
curl -H "Range: bytes=1048576-" -o part.mp4 "https://agent-download.kukukala.com/file/j_a1b2c3d4?token=…"

生命周期

48 小时计时从任务完成时开始（不是提交时）。到期后：410 Gone；URL token 失效同样 410；任务不存在 404。已开始的下载不会被主动中断，但过期后无法发起新请求。