Analysis

このガイドでは、analysis profile と report template を保存し、analysis を実行し、semantic result を検証し、自動生成された report を読み、必要な場合に別の presentation を明示的に rerender する方法を説明します。

analysis run は typed answer を生成します。report は保存済み answer から作る presentation output です。API はこの 2 つの関心事を分けているため、report を render または rerender しても動画を再分析しません。

task-first の path は、analysis profile と report template を保存し、両方の resource ID と必要な version で kind: analysis run を開始し、run と answer の semantic result gate を通過させ、自動生成された artifact を読み、別の presentation が必要な場合だけ rerender する流れです。profile は run が生成する内容を定義し、report template は保存済み answer を表示用に投影するだけです。

Analysis profile

analysis profile は instructions と順序付きの answer_specs で構成します。各 answer spec には answer_key、answer_type、field、evidence requirement があります。customer が指定できる prompt surface は analysis profile だけです。instructions は、run が動画内で何を観察するかと answer を synthesis する方法の両方を導きます。各 field の description は、その field の answer を synthesis する方法を導きます。再利用する profile を保存します。

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/profiles" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: profile-create-01" \
  -d '{
    "name": "Inspection timeline",
    "instructions": "Segment the complete video into evidence-backed activity windows.",
    "answer_specs": [
      {
        "answer_key": "inspection_timeline",
        "answer_type": "timeline",
        "temporal_scope": "windowed",
        "temporal_granularity": "semantic_segment",
        "aggregation_level": "video",
        "coverage": "complete",
        "fields": [{"key":"activity","label":"Activity","type":"string","description":"The observable activity in this segment.","required":true}],
        "evidence": {"required":true,"per_field":true,"accepted_types":["clip","frame"]}
      }
    ]
  }'

evidence contract は profile 作成時に確認されます。timeline profile では evidence.required を true にし、evidence.per_field も true にしてください。この admitted shape は profile の保存前に適用されます。形式としては正しくても、別の evidence shape を持つ profile は、失敗した admission_constant と admitted shape を含む 422 unprocessable-entity になります。下記の public evidence value を使ってください。

Profile は version 管理されます。POST /profiles/{profile_id}/versions で immutable version を追加します。GET /profiles/{profile_id}/versions で一覧を取得し、profile_version を省略すると latest を使います。DELETE /profiles/{profile_id} は archive であり、version を削除せず、過去の run の参照を壊しません。

ID と version の理由

POST /api/v1alpha1/runs の analysis は、保存済みの profile_id と report_template_id だけを参照します。正確な immutable revision を使う場合は profile_version と report_template_version を指定します。version を省略すると、server は submit 時点の latest を解決し、その version を run snapshot に記録します。resource に新しい version を追加した後も、完了済み run を再現できます。

/api/v1alpha1 の API version は public contract の revision です。resource version は、その contract 内で選択した analysis instruction、answer specification、presentation の正確な revision です。model や customer-specific branch を表すものではありません。

Field から名前付き answer へ

answer_specs[].answer_key は 1 つの answer の名前です。answer_specs[].fields[].key はその answer 内の typed field の名前です。report block の answer_key は名前付き answer を選び、columns[].key は表示する既存 field を選びます。これらは別の namespace です。

answers collection の top-level key は同じ名前付き answer を表します。report で、選んだ answer が生成していない field を定義することはできません。

timeline answer では、answer_specs[].fields[].key は verbatim の identifier です。同じ key が各 timeline attribute に返され、report の column と client code でも変更せず使う必要があります。field の label は表示用の文字列であり、key の名前を変更しません。synonym や自動的な大文字小文字の変換に依存しないでください。

Report template

report template は answer key に対応する presentation block と label を定義します。名前付き template を /api/v1alpha1/report-templates に POST します。version は immutable で、DELETE /report-templates/{report_template_id} は head を archive します。

{
  "name": "Inspection timeline",
  "language": "ja",
  "blocks": [
    {"type":"timeline","answer_key":"inspection_timeline","label":"工程タイムライン","columns":[{"key":"activity","label":"工程"}]}
  ]
}

POST /report-templates/{report_template_id}/versions で version を追加します。作成 request が返す id と immutable version を保存してください。run は保存済み template と version を参照します。再分析なしで新しい表示を作る場合は、Reports And Templates で説明する別の rerender endpoint を使います。

Analysis admission

OpenAPI schema は request vocabulary を定義します。

これらの enum は admitted language より広く設定されています。現在の public example が示す admitted combination は次のとおりです。

形式は正しくても admitted でない combination は、submit 時に 422 unprocessable-entity になります。problem body の admission_constant に失敗した capability が入り、利用可能な場合は answer_key と admitted_values も返ります。例として ANALYSIS_ADMISSION_CAPABILITIES.timeline.coverage は timeline の coverage を拒否し、complete を返すことがあります。同じ内容をそのまま retry せず、profile を修正してください。

vocabulary は分けて扱います。現在の run kind は workflow と analysis、この tutorial で admitted な answer type は timeline と synthesis、report block type は timeline、narrative、table、value、json です。audit と findings-to-report adapter は planned のため、kind: audit は送信しないでください。

Analysis run を開始する

処理済みで searchable な source_ids、保存済み profile reference 1 つ、保存済み report template reference 1 つ、formats、admitted な execution_profile_ref を送ります。現在提供されている最高位の execution tier は premium-analysis@1 です。この値は opaque な public reference として扱い、内部実装名に依存しないでください。この endpoint は inline profile と inline report template を受け付けません。次の request は上で作成した保存済み resource を使います。example ID は作成 request の response にある ID に置き換えてください。

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/runs" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: analysis-run-create-01" \
  -d '{
    "kind": "analysis",
    "source_ids": ["vid_0190b5d4-7e1f-7a2b-9c3d-1234567890ab"],
    "profile_id": "prof_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
    "profile_version": 1,
    "report_template_id": "tpl_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
    "report_template_version": 1,
    "formats": ["json", "markdown"],
    "execution_profile_ref": "premium-analysis@1",
    "execute_now": true
  }'

202 response は受付を示します。top-level status が terminal になるまで GET /api/v1alpha1/runs/{run_id} を polling してください。その後、Runs And Status の semantic result gate で run と answer を検証してから自動生成された report を使います。run は選択した profile と report template の version を固定し、analysis detail には実際に使った ID と version が記録されます。

Answer を読む

curl --fail-with-body --get "$BASE_URL/api/v1alpha1/runs/$RUN_ID/answers" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  --data-urlencode "expand[]=events" \
  --data-urlencode "expand[]=events.evidence"

Answer は answer_type で typed され、coverage、result_state、limitations、public provenance、evidence reference を保持します。上の request は events と events.evidence の両方を指定しているため、展開した timeline event と event 単位の evidence を取得できます。これらの query value がなければ、summary projection だけになる場合があります。analysis answer には VIEW_INSIGHTS が必要です。Runs And Status の gate を通過するまで answer value を使わないでください。

timeline では、model が instructions と supplied evidence から semantic event の範囲を選びます。

{
  "key": "inspection_timeline",
  "answer_payload": {
    "events": [
      {
        "event_id": "event_0190b5d4-01",
        "label": "Activity",
        "start_ms": 1200,
        "end_ms": 4300,
        "attributes": [
          {"key": "activity", "label": "Activity", "value": "observable activity", "evidence": [{"id": "evidence_0190b5d4-7e1f-7a2b-9c3d-1234567890ab"}]}
        ],
        "evidence": [{"id": "evidence_0190b5d4-7e1f-7a2b-9c3d-1234567890ab"}],
        "result_state": "found"
      }
    ],
    "coverage": {"state": "complete", "scope": "full_video"},
    "result_state": "found",
    "limitations": []
  }
}

start_ms と end_ms は AI が選ぶ semantic interval であり、内部 processing chunk ではありません。DeepFrame は media を implementation chunk 単位で処理することがありますが、その window は user-facing event ではありません。timestamp range や固定 event 数を送らず、profile instruction で event を説明してください。境界が不明確な場合は、precision を作らず uncertain または limitation を保持します。answer と report artifact では found、not_found、uncertain、not_checked を区別してください。

Report を読む、または rerender する

run が選択した保存済み report template は presentation input を固定します。analysis run が完了すると、API は request の formats に従って report を自動的に render し、artifact を保存します。semantic result gate を通過した後、report を一覧して読み取ってください。自動 render は analysis を再実行しません。

curl --fail-with-body --get "$BASE_URL/api/v1alpha1/reports" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  --data-urlencode "run_id=$RUN_ID" \
  --data-urlencode "expand[]=manifest"

curl --fail-with-body --get "$BASE_URL/api/v1alpha1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  --data-urlencode "expand[]=content" \
  --data-urlencode "expand[]=manifest"

GET /api/v1alpha1/reports は必須の run_id に対する persisted artifact だけを一覧します。report は作成しません。GET /api/v1alpha1/reports/{report_id} で 1 件を取得します。rendered artifact には expand[]=content、trust binding には expand[]=manifest を指定します。list が空の場合は run と limitation を確認し、first-view report を fallback として作成しないでください。

同じ保存済み answer から別の presentation を作る場合は、次の明示的な rerender endpoint を使ってください。

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/runs/$RUN_ID/reports" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: report-rerender-01" \
  -d '{
    "report_template": {
      "language": "ja",
      "blocks": [
        {"type":"timeline","answer_key":"inspection_timeline","label":"工程タイムライン","columns":[{"key":"activity","label":"工程"}]}
      ]
    },
    "formats": ["json", "markdown"]
  }'

明示的な rerender response は 201 Created です。保存済み answer を読み、presentation だけを変更します。analysis を再実行しません。rerender で uncertain、not_checked、not_found、または partial な answer data を成功 result に変えてはいけません。report を使う前に manifest binding の result_state、limitations、evidence_refs、evidence_urls、coverage_ref、provenance_refs を確認してください。store または export するときも、これらの field を保持してください。

rendered JSON artifact には、選択した field が次のように含まれます（他の document metadata は省略しています）。

{
  "answerKey": "inspection_timeline",
  "columns": [{"key":"activity","label":"工程"}],
  "events": [{"fields":[{"key":"activity","label":"工程","value":"observable activity"}]}]
}

その trust-manifest binding は /blocks/0/events/0/fields/0/value から events/event_0190b5d4-01/attributes/activity へ結び、result_state: "found"、空の limitations、event の evidence reference を保持します。

Evidence offset と artifact link

各 timeline event の evidence ref に start_ms と end_ms がある場合、answer response は clip-relative な offset_start_ms と offset_end_ms を millisecond で返します。offset は event の時刻から evidence clip の開始時刻を引いた値で、 clip の長さの範囲に clamp されます。古い answer に offset は追加されません。 必要な場合は analysis を再実行してください。

event ごとの evidence は、request で明示した場合だけ返します。answer を読むときは expand[]=events と expand[]=events.evidence を指定してください。expand[]=evidence だけを指定すると answer レベルの representative clip を返しますが、offset と fragment は含みません。指定できる値は events、events.evidence、evidence、provenance です。

answer response の media URL には、秒単位の client-side #t=start,end fragment が署名の後に付く場合があります。署名済み query と HTTP range request は変わらないため、query parameter による seek は使わないでください。

point-in-time の claim で長さが 0 の場合、fragment は #t=7,7 になります。 #t=7 は 7 秒から clip の最後まで再生する意味になるため、省略しないでください。

JSON artifact は数値の clip-relative offset と evidence span を保持します。 Markdown artifact は timeline event の evidence link を持ちます。保存された body は deterministic な placeholder を使い、read 時に解決できる link だけを fresh signed URL に置き換えます。解決できない evidence ref でも read は成功し、link は省略されます。