API 接入文档

如何调用 dogdog 的站点、提示词、图片和视频检测。

最近更新: 2026-10-09

基础地址

使用 dogdog 实际运行的域名。本地是 http://localhost:3000。

每次检测都记在 API Key 所属账号下。一个账号读不到另一个账号的历史。

鉴权

在控制台 /settings/apikeys 创建密钥，每次请求带上：

Authorization: Bearer sk_your_key

也可以用 x-api-key: sk_your_key。浏览器控制台走当前登录会话，不需要这个请求头。

密钥缺失或无效时返回 HTTP 401：

{ "code": -1, "message": "Unauthorized" }

返回结构

检测完成时，即使内容被拦截，HTTP 也是 200。以 data.allowed 为准，不要把 HTTP 200 当成通过。

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "记录 id",
    "allowed": false,
    "decision": "block",
    "categories": ["explicit_sexual_content"],
    "code": "policy_violation",
    "message": "Content does not meet the configured moderation policy.",
    "summary": "一句话结论",
    "findings": []
  }
}

allow / allowed: true / approved — 检测完成，没有命中类别
block / allowed: false / policy_violation — 至少命中一个类别
review / allowed: false / manual_review — 模型不确定，或没有看完
review / allowed: false / moderation_unavailable — 模型超时或服务调用失败
error / allowed: false / invalid_input — 请求内容不可用
error / allowed: false / invalid_provider_response — 模型返回无法解析
error / allowed: false / crawl_failed — 网站抓取失败

模型失败不会自动变成 allow。

提示词检测

POST /api/v1/moderate/prompt

curl -X POST "$BASE/api/v1/moderate/prompt" \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A paper boat floats across a quiet pond."}'

prompt 是字符串，最长 20000 个字符。空字符串返回 invalid_input。

没有关键词表。Grok 按下面的策略审这段文字：

minor_sexual_exploitation — 涉及未成年人的性内容
explicit_sexual_content — 明确的性行为、裸露或色情
celebrity_sexual_likeness — 用真人（含名人）肖像做性相关内容
nonconsensual_intimate — 非自愿私密影像
graphic_violence — 血腥暴力
self_harm_encouragement — 鼓励自残或自杀
hate_or_threats — 仇恨或暴力威胁
dangerous_instructions — 可执行的暴力或危险操作说明
privacy_abuse — 人肉、泄露隐私

findings 始终是空数组，命中类别在 categories。新闻、医疗、预防语境里仅仅提到某个话题，本身不算违规。

图片检测

POST /api/v1/moderate/image

curl -X POST "$BASE/api/v1/moderate/image" \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"imageUrl":"https://example.com/photo.jpg","prompt":"可选说明"}'

imageUrl 必须是公网 http 或 https 地址。data: 地址返回 invalid_input。要直接上传文件，用 multipart/form-data，字段名是 file。支持 JPEG、PNG、WebP、GIF，最大 8 MB。

curl -X POST "$BASE/api/v1/moderate/image" \
  -H "Authorization: Bearer sk_your_key" \
  -F "file=@photo.jpg" \
  -F "prompt=可选说明"

prompt 是可选说明，最长 2000 个字符。

策略与提示词检测相同。图片必须能被读到。模型看不到图片时，结论是 review。

视频检测

POST /api/v1/moderate/video

curl -X POST "$BASE/api/v1/moderate/video" \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"videoUrl":"https://example.com/clip.mp4","prompt":"可选说明"}'

videoUrl 必须是公网 http 或 https 地址，指向 mp4、webm 或 mov，最大 32 MB。frames 取 1、3、5 或 10。能读到时长时，dogdog 在整段视频上均匀抽取这么多帧，再按图片检测的同一套策略筛查。响应里列出抽帧时间。读不到时长时只抽开头一帧，按实际送进模型的帧数收费：2 点再加每帧 1 点。不转写音轨。内网地址和 data: 地址返回 invalid_input。文件抓不到、解不了，或画面无法判定时，结论是 review 或 error。

要直接上传文件，用 multipart/form-data，字段名是 file。支持 MP4、WebM、MOV，最大 32 MB。

curl -X POST "$BASE/api/v1/moderate/video" \
  -H "Authorization: Bearer sk_your_key" \
  -F "file=@clip.mp4" \
  -F "prompt=可选说明"

prompt 是可选说明，最长 2000 个字符。

站点检测

POST /api/v1/scans

curl -X POST "$BASE/api/v1/scans" \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","scope":"page","providers":["stripe","paypal"]}'

url 必填。scope 是 page 或 site。page 只检测这一个地址。site 还会读取 sitemap 和同站页面；不传 scope 时默认是 site。providers 可以是 stripe、paypal，或两个都传。不传则两个都查。

POST /api/v1/scans/discover，正文 {"url":"https://example.com"}，从首页、robots.txt 的 sitemap、/sitemap.xml 和同站链接列出公开页面。没有页数上限。首页、定价页和政策页标记为 key 和 checked。这一步不扣额度。truncated 为 true 时，这次请求还有 sitemap 文件没打开。

POST /api/v1/scans/estimate 一次最多 8 个页面。页面更多时分批请求，把 chars 加总。不调用模型，不扣额度。超过 12,000 个字符会拆成多次模型调用，每次请求只跑几段，再合并命中项。

POST /api/v1/scans 在 scope 为 site 时一次最多检测 8 个页面。用返回的 scanId 和 chunkOffset 继续，直到 nextChunkOffset 到达 chunksTotal。scope 为 page 时只检测你提交的网址。文本额度是 2 点，加上整次扫描实际送进模型的每 2,000 个字符 1 点。每次调用模型之前会预扣差额，余额不会变成负数。页面抓取失败不扣额度。

只抓同一站点上的公网 http / https 页面。本机、内网，以及跳到其他域名，返回 crawl_failed。

可见文字先过固定关键词，再把压缩后的页面交给模型。高严重程度关键词或模型给出 block，结果就是 block。只有模型给出 allow 且没有任何关键词命中时，才是 allow。中等严重程度关键词、模型不确定或模型不可用，都是 review。

站点类别是 adult_content、minor_sexual_content、celebrity_sexual_likeness、gambling、illegal_drugs、weapons、counterfeit、get_rich_quick、hate_or_violence、other_restricted。

data.pages 是实际读过的地址。data.findings 是命中项：

{
  "provider": "stripe",
  "category": "gambling",
  "severity": "high",
  "url": "https://example.com/pricing",
  "evidence": "附近原文"
}

历史记录

GET /api/v1/records

GET /api/v1/records?kind=site

kind 可以是 site、prompt、image、video。只返回该密钥所属账号最近 50 条。

GET /api/v1/records/{id}

返回这一条，包含保存的详情。别人的记录返回 HTTP 404：{ "code": -1, "message": "Not found" }。