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

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

出典: https://point11.ai/ja/docs/mcp/creative-testing  
更新日: 2026-10-18

## 概要

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

Research への書き込み権限を持つ [API キー](/ja/docs/mcp/overview)と、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` で送り直します。開始を再試行すると同じテストが返り、二重に課金されることはありません。