動画1本。API呼び出し1回。

クイックスタート

ベースURL: https://api.artlint.com。応答はJSONで、成功結果は次に格納されます: data、失敗時は error.

1. キーを作成

開く アカウント → APIキー Artlintコンソールで次のキーを作成: フルアクセス キーで動画を送信、または次のキーを作成: 読み取り専用 キーで結果を取得します。表示時にシークレットをコピーし、サーバーのシークレット管理に保存してください。

送信 Authorization: Bearer $ARTLINT_API_KEY を各リクエストに指定します。キーはワークスペースに限定され、アプリのサインインには使えません。セッションCookieやログイントークンはAPI認証に使えません。

2. ファイルまたはURLを送信

ファイルはJSONを含むmultipart form dataで送信します: 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も利用できますが、ダウンロード中は有効である必要があります。

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は識別子であり、ダウンロードリンクではありません。

安全な再試行

1つ使用してください: Idempotency-Key をジョブごとに使用します。空白のない印字可能ASCII文字1〜200文字です。同じワークスペースで同じ要求を再送すると、既存の分析と共に次を返します: 200 OK。プランの同時実行枠が埋まっている場合も同様です。同じキーで異なるオプションを送ると次が返ります: 409 idempotency_key_reused。再送時にアップロードのバイト列は比較しないため、別の動画には新しいキーを使ってください。

送信オプション

不明なフィールドや無効な値は次を返します: 422 invalid_request、以下を含みます: error.details.field でオプション名を示します。JSONオプションは16 KiBまでです。

APIリファレンス

以下の全エンドポイントにはAPIキーが必要です。読み取りに必要な権限: api.read。送信、キャンセル、削除には次が必要です: api.write.

Webhookで結果を取得

次の場所でエンドポイントを登録します: アカウント → Webhooks。分析ごとの終了イベントは1つです: artlint.analysis.completed, artlint.analysis.failed、または artlint.analysis.canceledをエンドポイントが購読します。配信は再試行されるため、次で重複を排除してください: webhook-id.

イベント処理前に、エンドポイントの署名用シークレットで元のリクエスト本文のStandard Webhooks署名を検証してください。ヘッダー: webhook-id, webhook-timestamp、および webhook-signature。タイムスタンプが新しいことを検証してください。

完了イベントには概要、収容できる最も重大な指摘事項、使用クレジットと残高が含まれます。次の値が findings_truncated 真の場合、APIで全ての指摘事項を取得してください。Webhookを使わない場合は分析をポーリングできます。

クレジットと請求

アプリとAPIの分析は同じ組織のクレジット残高を使います。参照: GET /v1/balance で現在の料金を確認: pricing.standard.credits_per_second および pricing.standard.minimum_credits Maxの料金は次の項目で確認できます pricing.max。標準はStandardで、1秒につき1クレジット、最低10クレジットです。Maxは1秒につき5クレジット、最低150クレジット（30秒）です。端数の秒は切り上げます。

Artlintは準備後にクリップ全体の料金を計算し、次の上限以内の場合のみ開始します: max_credits。それ以外は次の状態で終了します: failed と max_credits_exceeded で、課金されません。検査開始時にクレジットを使用し、レポートを提供できない場合は返還します。参照: credits.quoted, credits.charged、および credits.refunded を分析で確認してください。

ファイルとプランの制限

全プランで1ファイル2 GiB（2,147,483,648バイト）までのMP4、MOV、WebMに対応します。実際の長さと互換性は準備中に確認します。

同時分析数はアプリの作業を含め、組織の全ワークスペースで共有されます。ダウンロード、準備、待機中も枠を使用し、キャンセル・失敗・完了で解放されます。パックや無制限クレジットでプラン制限は増えず、期限切れの契約はFreeに戻ります。

キーごとに同時アップロードは1つにしてください。APIプロセスごとの既定上限は、キーあたり毎分120リクエスト・20送信、ワークスペースあたり毎分600リクエストです。再送と拒否された送信も数えます。次に従ってください: Retry-After 日付 429 および再試行可能な 503 応答に従ってください。ストレージ枠とサービス容量により追加制限が適用される場合があります。

URLダウンロードは最大5回のリダイレクト、合計30分、アイドル60秒までです。非公開ホストと非HTTPSの元データは拒否されます。

エラー処理

拒否されたリクエストはエラーオブジェクトを返します：

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

リクエストのエラー

分析の失敗

受け付けた分析も非同期に失敗することがあります。確認するフィールド： error フィールドまたは失敗Webhookを確認してください。

アプリを使いますか？

サインインし、動画を開いて次を選択: 動画を分析を選択し、2 GiB以下のMP4、MOV、WebMファイルを選びます。動画の上限はFreeが1分、Creatorが5分、Proが10分、Studioが30分です。検査に必要なクレジットも必要です。分析後は指摘事項、元フレームの根拠、未検査部分を確認してください。詳細は データとプライバシー で処理と保存の詳細をご確認ください。