APIでクリエイティブをテストする

広告などのクリエイティブをアップロードし、顧客のデジタルツインでテストして、自分のコードからスコアカードを読み取ります。

概要#

クリエイティブテストでは、広告、画像、動画、音声を顧客のデジタルツインに見せ、各ツインに評価してもらいます。Studio > Assets > Test existing assets から実行するのと同じテストを、自分のコードから実行できます。たとえば、デザイナーが Canva や Adobe からファイルを書き出した直後に実行できます。

Research への書き込み権限を持つ API キーと、Point11 で設定済みのオーディエンス（ビジネスプロフィールとその顧客）が必要です。以下のすべてのリクエストはキーを Authorization: Bearer $POINT11_API_KEY として送り、何かを変更するリクエストは Idempotency-Key に新しい UUID を入れて送ります。

各クリエイティブをアップロードする#

各ファイルは3つのリクエストでアップロードします。まずアップロードを予約し、ファイル名、種類、正確なバイト数、SHA-256 を送ります（動画は SHA-256 を送りません）。

bash
curl https://point11.ai/api/v1/research/study-attachments/reserve-upload-v4 \
  -H "Authorization: Bearer $POINT11_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"filename": "summer-ad.png", "mediaType": "image/png", "byteLength": 482113, "sha256": "<hex sha-256>"}'

次に、レスポンスにある upload リクエストの本文としてファイルを送ります。メソッド、URL、ヘッダーはそのまま使い、1分後に期限が切れる前に送ってください。最後に、添付ファイルの id と、アップロードが返した etag でアップロードを完了します。

bash
curl https://point11.ai/api/v1/research/study-attachments/complete-upload-v3 \
  -H "Authorization: Bearer $POINT11_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"id": "<attachment id>", "etag": "<etag>"}'

画像（PNG、JPEG、WebP）は最大 3,750,000 バイトです。これは、ツインが動作しうるすべての AI モデルに 1 枚の画像として渡せる上限です。PDF と音声（MP3、WAV）は最大 4 MiB、動画（MP4、WebM）は最大 100 MiB・3分までです。ツインは動画を、時刻付きのフレームと文字起こしとして見ます。そのため、GET /api/v1/research/study-attachments-v2/{id} でストーリーボードの準備完了が表示されるまで待ってください。

テストを開始する#

アップロードしたファイル、知りたいこと、オーディエンス、ツインがクリエイティブに触れる状況を指定します。

bash
curl https://point11.ai/api/v1/research/creative-tests/start \
  -H "Authorization: Bearer $POINT11_API_KEY" \
  -H "Idempotency-Key: $TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer ads",
    "brief": "Which ad makes people want to book a visit, and why?",
    "sellerProfileId": null,
    "contentLanguage": "en",
    "audience": {
      "audienceProfileId": "<business profile id>",
      "targetedGroupIds": null,
      "targetedCustomerIds": null,
      "targetInterviewCount": 50
    },
    "studyMode": {"kind": "first_impressions"},
    "metrics": ["stopping_power", "clarity", "appeal", "intent_to_act"],
    "platforms": ["Facebook", "Instagram"],
    "attachments": [
      {"artifactId": "<attachment id>", "filename": "summer-ad.png", "mediaType": "image/png", "byteLength": 482113}
    ]
  }'
  • オーディエンス。 audienceProfileId は、GET /api/v1/business/profiles で取得するビジネスプロフィールの ID です。targetedGroupIds を空にするとそのすべての顧客から選び、保存済みオーディエンスを最大20件まで指定することもできます。
  • 第一印象か購入場面か。 first_impressions は、各ツインにありのままの状態でクリエイティブを見せます。buying_scenario に direction を指定すると、まず各ツインを説明どおりの購入場面に置きます。
  • 指標。 各指標は、共通の尺度でクリエイティブごとに1つの評価質問になり、さらにフォローアップ質問が1つ付きます。そのため、テストの質問数はクリエイティブ数 ×（指標数 + 1）で、上限は100です。指標が4つなら最大20件のクリエイティブをテストできます。プラットフォーム適合度には少なくとも1つのプラットフォームが必要です。

テストはすぐに 202 を返します。送った Idempotency-Key は控えておいてください。以降はこのキーでテストを指定します。

テストを追跡する#

Point11 がクリエイティブを読み取ってツインを準備している間は、このキーでテストを読み取ります。

bash
curl https://point11.ai/api/v1/research/creative-tests/$TEST_KEY \
  -H "Authorization: Bearer $POINT11_API_KEY"

status は preparing の後、launched、failed、unsupported のいずれかになり、phase は進み具合を示します。この方法でテストを読み取れるのは、テストを開始したキーだけです。launched になると、campaignId と runId がインタビューと結果を指します。

インタビューには時間がかかるため、テストを1件ずつ読む代わりに、組織のアクティビティリビジョンを30〜60秒ごとに読み取ってください。どれかの調査が終わるか結果が公開されると変わるので、1回のリクエストですべてのテストを確認できます。

bash
curl https://point11.ai/api/v1/campaigns/activity-revisions/organization \
  -H "Authorization: Bearer $POINT11_API_KEY"

products.research が変わったら、結果を読み取ります。

スコアカードを読む#

bash
curl "https://point11.ai/api/v1/research/results-v7/$CAMPAIGN_ID?runId=$RUN_ID" \
  -H "Authorization: Bearer $POINT11_API_KEY"

結果には、各質問の回答、引用付きの要約、完了したインタビュー数、そしてスコアカード（クリエイティブごと・全体の各指標）が含まれます。結果は顧客のデジタルツインによるシミュレーション調査であり、実測のクリック、売上、コンバージョンではありません。

費用と上限#

  • クリエイティブテストは通常の Research 調査と同じく課金されます。完了したインタビューごとに Research のインタビュー料金でプランに計上され、クリエイティブの読み取りとツインの準備には実費どおりの Alpha クレジットを使います。
  • 各キーは、API と MCP サーバーを合わせて1分あたり100リクエストまで使えます。1つのキーで開始できるテストは1分あたり約6件、アップロードできるファイルは1分あたり128件、1日あたり300件です。上限に達すると 429 が返るので、Retry-After の秒数だけ待ってください。
  • リクエストを安全に再試行するには、同じ Idempotency-Key で送り直します。開始を再試行すると同じテストが返り、二重に課金されることはありません。