开发者文档

一个视频。一次API调用。

提交视频，跟踪分析，将结构化发现结果引入工作流。

快速开始

基础URL为 https://api.artlint.com。响应为JSON，成功结果放在 data，失败响应则放在 error.

1. 创建密钥

打开账户 → API密钥在Artlint控制台创建一个 完整访问权限 密钥提交视频，或创建一个只读密钥读取结果。显示密钥时请复制，并存放在服务器的密钥管理器中。

发送 Authorization: Bearer $ARTLINT_API_KEY 于每次请求中。密钥限定于工作区，不能用于登录应用。会话Cookie及登录令牌不能认证API请求。

2. 提交文件或URL

文件请通过multipart form data发送，并包含JSON options 部分须先放置，然后放置 file 部分:

curl https://api.artlint.com/v1/analyses \
  -H "Authorization: Bearer $ARTLINT_API_KEY" \
  -H "Idempotency-Key: video-job-8812" \
  -F 'options={"max_credits":20,"client_reference":"video-job-8812"};type=application/json' \
  -F '[email protected]'

提交URL时请发送JSON。支持预签名URL，请确保Artlint下载视频期间URL持续有效。

curl https://api.artlint.com/v1/analyses \
  -H "Authorization: Bearer $ARTLINT_API_KEY" \
  -H "Idempotency-Key: video-job-8813" \
  -H "Content-Type: application/json" \
  -d '{"video_url":"https://your-media.example/video.mp4","max_credits":20}'

新请求返回 202 Accepted。响应包含一个 id 开头为 ana_、状态及余额。文件提交的初始状态为 preparing；URL提交的初始状态为 fetching.

3. 跟踪分析

curl https://api.artlint.com/v1/analyses/ana_YOUR_ANALYSIS_ID \
  -H "Authorization: Bearer $ARTLINT_API_KEY"

分析将依次经历 fetching, preparing，以及 analyzing。最终状态为 completed, completed_with_gaps, failed，或 canceled。以下字段: stage 字段提供更细的进度信息，包括 queued 以及 finalizing.

完成后，请读取 summary 于分析对象上，并使用 links.findings 以分页获取发现结果。请结合覆盖缺口复核发现；分析完成并不意味着视频的每一部分都已评估。

开发者API当前未启用完整报告检索和证据下载链接，相关请求返回 404。仍可通过Artlint应用访问报告和证据。发现结果中的证据ID是标识符，并非下载链接。

安全重试

请使用一个 Idempotency-Key 每个作业一个，长度1至200个可打印ASCII字符，不含空格。在同一工作区重复相同请求，将返回已有分析和 200 OK，即使套餐的并行额度已满也是如此。同一密钥搭配不同选项将返回 409 idempotency_key_reused。重试时不会比较上传的字节，因此不同视频须使用新密钥。

提交选项

POST /v1/analyses选项
字段	必填	含义
`max_credits`	必填	0至1,000,000,000的整数。仅当整个片段的费用在此上限内时才启动检查。
`client_reference`	可选	您的作业参考值：1至128个字符，不得含控制字符。随分析和Webhook返回。
`mode`	可选	analysis为默认值，也是唯一支持的模式。
`analysis_level`	可选	standard（默认）或 max。Max 包含 Standard 的全部检查，并更深入地审核运动与物理交互。
`filename`	可选	1至255字节，不得含斜杠或控制字符。默认使用文件名或URL的最后一段路径。
`project_id`	可选	密钥所在工作区中的项目。默认使用该工作区的API项目。
`video_url`	仅JSON	公开主机上的HTTPS URL，最长2,048个字符，不能含用户名或密码。

未知字段或无效值将返回 422 invalid_request，其中包含 error.details.field 指明选项。JSON选项大小限制为16 KiB。

API参考

以下所有端点均需要API密钥。读取需要 api.read；提交、取消和删除需要 api.write.

下载OpenAPI规范

POST`/v1/analyses`

提交文件或URL。返回202及分析对象；幂等重试返回200。

GET`/v1/analyses`

List analyses in the key’s workspace, newest first. Filter by client_reference or status. limit is 1–100 (default 50); pass next_cursor as cursor.

GET`/v1/analyses/{analysis_id}`

读取状态、阶段、积分、余额、来源和结果链接。

GET`/v1/analyses/{analysis_id}/findings`

Read paginated findings. limit is 1–100 (default 50); pass next_cursor as cursor. Optionally filter by category.

POST`/v1/analyses/{analysis_id}/cancel`

取消未完成的分析。返回202，已取消检查的积分将退回。

DELETE`/v1/analyses/{analysis_id}`

Delete the video, report, and evidence. Returns 202 with deletion state; subsequent reads return 410 analysis_deleted.

GET`/v1/balance`

Read the organization’s shared credit balance and configured Standard and Max pricing.

GET`/v1/key`

描述当前密钥、访问权限及工作区。密钥值将隐藏。

通过Webhook获取结果

请在以下位置注册端点: 账户 → Webhooks。每次分析只记录一个终结事件: artlint.analysis.completed, artlint.analysis.failed，或 artlint.analysis.canceled，端点订阅该事件。投递可能重试，请使用以下值去重: webhook-id.

处理事件前，请使用端点的签名密钥，针对原始请求正文验证Standard Webhooks签名。请求头为 webhook-id, webhook-timestamp，以及 webhook-signature。请验证时间戳是否在有效时间内。

完成事件包含摘要、能容纳的最严重发现，以及已扣积分和余额。如果 findings_truncated 为true时，请通过API获取完整发现结果。若不使用Webhook，也可轮询分析状态。

积分与计费

应用和API分析使用同一组织积分余额。请读取 GET /v1/balance 以查看当前费率，单位为 pricing.standard.credits_per_second 以及 pricing.standard.minimum_credits Max价格见 pricing.max。默认使用Standard，每秒1积分，最低10积分。Max每秒5积分，最低150积分（30秒）。不足1秒按1秒计。

Artlint在准备完成后计算整个片段的费用，仅在费用不超过以下上限时启动: max_credits。否则将以以下状态结束: failed 与 max_credits_exceeded ，不会扣费。检查开始时扣除积分，未提供报告时退回。请读取 credits.quoted, credits.charged，以及 credits.refunded 于分析对象上。

比较套餐

文件与套餐限制

所有套餐支持每文件不超过2 GiB（2,147,483,648字节）的MP4、MOV和WebM。实际时长和媒体兼容性将在准备阶段检查。

应用与API分析共享的套餐限制
套餐	文件大小	视频时长	同时分析数
Free	2 GiB	1分钟	1
Creator	2 GiB	5分钟	1
Pro	2 GiB	10分钟	2
Studio	2 GiB	30分钟	3

并行分析上限由组织内全部工作区共享，包括从应用启动的任务。下载、准备和排队检查也会占用名额，取消、失败或完成后释放。积分包及无限积分不会提高套餐限制；订阅过期后恢复为Free。

每个密钥一次上传一个文件。每个API进程的默认请求额度为：每密钥每分钟120次请求和20次提交，每工作区每分钟600次请求。重试和被拒绝的提交也计数。请遵循 Retry-After 日期 429 以及可重试的 503 响应。工作区存储额度与服务容量可能施加其他限制。

URL下载最多允许5次重定向，总时间30分钟，空闲超时60秒。拒绝私有主机和非HTTPS来源。

处理错误

被拒绝的请求会返回错误对象：

{
  "error": {
    "code": "invalid_request",
    "message": "…",
    "details": { "field": "max_credits" },
    "request_id": "…"
  }
}

请求错误

请求错误
HTTP 状态	错误代码	含义与处理方法
401	`unauthorized`	请使用有效的 API 密钥。密钥缺失、已过期、已撤销或无效。
403	`insufficient_scope`	提交、取消或删除分析的请求需使用完全访问权限的密钥。
403	`developer_api_disabled`	此部署尚未启用 API 访问。
409	`idempotency_key_reused`	选项或视频更改后，请使用新的任务密钥。
413	`file_too_large`	上传文件超过 2 GiB。请提交较小的文件。
422	`invalid_request`	请通过 details.field 查看无效选项。分段上传时，请先发送 options，再发送 file。
429	`plan_concurrency_limit`	请等待可用的分析名额，检查 details.plan_limits，并遵循 Retry-After。
429	`too_many_active_analyses`	已达工作区服务上限。请在容量可用时重试。

分析失败

已接受的分析也可能异步失败。请检查其 error 字段或失败Webhook。

分析失败
错误代码	含义与处理方法
`source_too_large`	从 URL 下载的视频超过 2 GiB。请使用较小的源文件。
`plan_duration_limit`	已接受的视频超过套餐的时长限制。请缩短视频或选择上限更高的套餐。
`credits_insufficient`	检查未开始，也未扣费。请添加点数后重试。
`max_credits_exceeded`	检查未开始，也未扣费。请提高 max_credits，以覆盖片段的费用。

更喜欢使用应用？

登录并打开视频。选择 分析视频，然后选择不超过2 GiB的MP4、MOV或WebM文件。单个视频时长上限为Free 1分钟、Creator 5分钟、Pro 10分钟、Studio 30分钟。余额还须足以支付检查。分析完成后，请查看发现的问题、原始帧证据及未覆盖的部分。详情参见数据与隐私以了解处理及保留详情。

打开工作区