跳至正文

Fileverity API 文档

图片鉴别

通过 POST /images/detections 判断整张图片是否由 AI 生成。一次同步调用:请求与响应字段、结论取值、限制和计费。

查看 Markdown更新于 2026-11-11

POST /images/detections 运行 AI生成图片鉴别。它用 vereye-2-detect 判断整张图片是否由 AI 生成,所依据的模型、内容凭证、AI 标识和水印与图片核验报告(vereye-2)相同,因此两者在 AI 生成这一问题上给出相同的结论。该调用是同步的:结果就在响应中。

它不检查局部编辑,包括对照片局部的 AI 编辑,也不返回报告编号或 PDF。如需编辑痕迹、来源和任何人都能核验的记录,请用 vereye-2 创建分析。

curl https://api.fileverity.com/v1/images/detections \  -H "Authorization: Bearer $FILEVERITY_API_KEY" \  -H "Idempotency-Key: 6b9d1c1e-3b0f-4c0a-9a53-2d1c9d6b7e11" \  -F file=@photo.jpg

请求体

以 multipart/form-data 把图片放在 file 字段中发送,最大 4 MB。更大的图片(最大 10 MB)请先用 POST /files 上传,再改为发送 JSON:

字段类型必填说明
filefile 或 string是multipart 请求中的图片,或 JSON 请求中已上传图片的 ID。支持 JPEG、PNG、WEBP,最大 4000 万像素。文件 ID 在检测后即被消耗。
modelstring否默认为 vereye-2-detect。接受模型 ID 或其快照 ID vereye-2-detect-2026-10-30。

未知字段会被拒绝,并返回 invalid_parameter。

响应

{  "id": "idet_8Hk2pQ4vN9sL1xR7cW3mY6zB",  "object": "image.detection",  "created": 1794096000,  "model": "vereye-2-detect-2026-10-30",  "livemode": true,  "verdict": "ai_generated",  "ai": {    "key": "very_likely",    "basis": "detected",    "strength": "strong",    "likelihood": 100  },  "generator": null,  "signals": [    {      "id": "model_1",      "state": "ai"    },    {      "id": "model_2",      "state": "ai"    },    {      "id": "credentials",      "state": "none"    },    {      "id": "watermark",      "state": "none"    },    {      "id": "label",      "state": "none"    },    {      "id": "tool_data",      "state": "none"    },    {      "id": "camera",      "state": "none"    }  ],  "regions": [    {      "x": 0,      "y": 0,      "w": 576,      "h": 512,      "level": 3    },    {      "x": 576,      "y": 0,      "w": 384,      "h": 512,      "level": 3    },    {      "x": 960,      "y": 0,      "w": 576,      "h": 512,      "level": 2    },    {      "x": 0,      "y": 512,      "w": 576,      "h": 512,      "level": 3    },    {      "x": 576,      "y": 512,      "w": 384,      "h": 512,      "level": 3    },    {      "x": 960,      "y": 512,      "w": 576,      "h": 512,      "level": 3    }  ],  "candidates": [    {      "name": "Midjourney",      "score": 0.65    },    {      "name": "OpenAI",      "score": 0.25    }  ],  "quality": {    "overall": "fair",    "resolution": "good",    "compression": "fair",    "metadata": "fair",    "distribution": "good"  },  "limits": [    "no_metadata"  ],  "image": {    "width": 1536,    "height": 1024,    "format": "jpeg",    "jpeg_quality": 85  },  "usage": {    "credits": 4  }}
字段类型说明
idstring鉴别 ID,前缀为 idet_。
objectstring始终为 image.detection。
createdintegerUnix 时间戳。
modelstring生成该结果的快照。
livemodeboolean测试密钥为 false。
verdictstringai_generated:图片由 AI 生成。no_ai_signs:没有任何迹象指向 AI 生成。inconclusive:证据不足以判定。
aiobject关于 AI 生成的结论,取值与图片报告中的 questions.ai 相同。
generatorobject 或 null文件通过内容凭证、元数据或水印声明的生成器,包含 name 和 basis。文件未声明时为 null。
signalsarray答案所依据的各项检查,每项包含 id 和 state。参见信号。
regions数组或 null覆盖图片的粗网格。每个单元格包含以所显示图片的像素为单位的 x、y、w 和 h,以及表示生成特征强度的 level(0 到 3)。图片太小、无法划分网格时为 null。
candidatesarray像素特征与该图片最接近的生成模型,最多三个,每个包含 name 和 0 到 1 的 score。仅当结论为 ai_generated 时有内容。
qualityobject 或 null文件对分析的支持程度:overall、resolution、compression、metadata 和 distribution,取值均为 good、fair 或 poor。
limitsarray影响结果的因素:low_resolution、heavy_compression、platform_copy、no_metadata 或 models_disagree。
imageobject显示时的 width 和 height、format,以及 jpeg_quality(估计的 JPEG 质量,或 null)。
usageobject扣除的 credits。

如何解读结论

`ai.key``verdict`含义
labelledai_generated内容凭证、AI 标识或水印声明了 AI 生成。可信凭证的 ai.basis 为 verified,否则为 declared 或 detected。
very_likely, suspectedai_generated像素显示出 AI 生成的迹象,证据较强,或各信号之间略有分歧。
undecidedinconclusive信号较弱,或相互矛盾。
low, very_lowno_ai_signs像素和元数据中均未发现指向 AI 生成的迹象。

ai.strength 为 strong、moderate 或 limited,表示证据对该结论的支持强度。ai.likelihood 以 5 为步长,取值 0 到 100;结论为 labelled 时为 null。

no_ai_signs 并不说明照片真实或未经编辑。AI生成图片鉴别不检查编辑痕迹。如果决定取决于此,请运行图片核验报告,并由人工复核结果。

信号

signals 列出已执行的每一项检查,便于了解答案的依据。state 为 ai 表示该项指向 AI 生成。

`id``state`检查项
model_1, model_2ai, unclear, clear, unavailable两套独立训练的模型,对像素进行分析。
credentialsai, ai_unverified, other, none内容凭证(C2PA)。ai_unverified:凭证声明为 AI 生成,但签发方未能核验。other:凭证存在,且未声明 AI 生成。
watermarkai, none, unavailable开源生成工具嵌入像素的不可见水印。
labelai, none元数据中的 AI 生成声明,例如 IPTC 数字来源类型。
tool_dataai, none保存在文件中的提示词、参数或生成工具名称。
camerapresent, none相机品牌、型号和曝光参数。这些信息可以被修改,本接口不对其进行核验。

regions 展示生成特征最强的位置。3 级的单元格带有明显的生成特征。当结论为 no_ai_signs 而部分单元格为 3 级时,图片的局部可能由 AI 生成或经 AI 编辑:本接口不检查局部编辑,请使用图片核验报告。

candidates 仅供参考,不代表确认。它按像素特征的相似程度对生成模型排序,参考范围之外的生成工具会显示为与它最相近的一类。文件自身写明生成工具时,请以 generator 为准。

计费

  • AI生成图片鉴别每张图片 4 积分。
  • 同一工作区内,同一张图片在 7 天内做过 AI生成图片鉴别的,其图片核验报告为 36 积分,而不是 40 积分:鉴别所用的积分只计一次。分析会在 usage.credits 中报告实际扣费。
  • 评估前即被拒绝的请求不收费:参数无效、文件不受支持或已损坏、超出大小限制等。在服务内部失败的检测(service_unavailable、analysis_failed)会被释放,不收费。
  • 积分不足时返回 insufficient_balance(402)。

存储的内容

图片在检测后即被删除。Fileverity 会保留不含图片的结果(结论、答案、生成器、信号、区域、候选、质量、尺寸、文件的 SHA-256 指纹和用量)7 天,以便控制台展示,并便于计费与审计。使用相同 Idempotency-Key 重试的请求,24 小时内会得到已保存的结果。图片鉴别是同步的:它们不会出现在 GET /analyses 中,也不会发送 Webhook 事件。测试密钥不记录任何内容。参见数据保留与安全。

错误

错误码状态原因
missing_parameter400缺少 file 字段。
invalid_parameter400字段类型错误、发送了未知字段、模型不是图片鉴别模型,或 Idempotency-Key 无效。
file_not_found400文件 ID 未知、已过期或已被使用。
unsupported_file, invalid_file415, 422文件不是 JPEG、PNG 或 WebP 图片,或已损坏。
file_too_large, too_many_pixels413multipart 文件超过 4 MB,上传的文件超过 10 MB,或图片超过 4000 万像素。
unsupported_media_type, invalid_json415, 400请求体既不是 multipart/form-data,也不是 JSON 对象。
model_not_found404model 未知。
insufficient_balance, spend_limit_reached402余额或密钥的每月上限不足以支付该请求。
idempotency_mismatch, idempotency_in_progress409该 Idempotency-Key 曾用于不同的请求体,或其首次请求仍在运行。
service_unavailable, analysis_failed503, 502检测服务暂时不可用或繁忙。未扣费,请重试。service_unavailable 会带有 retry-after 响应头。

请发送 Idempotency-Key,这样超时后重试就不会重复计费。参见幂等性。