# API로 크리에이티브 테스트하기

광고와 기타 크리에이티브를 업로드하고, 고객의 디지털 트윈으로 테스트한 뒤, 자체 코드에서 스코어카드를 읽으세요.

출처: https://point11.ai/ko/docs/mcp/creative-testing  
업데이트: 2026-10-18

## 개요

크리에이티브 테스트는 광고, 이미지, 동영상, 오디오를 고객의 디지털 트윈에게 보여 주고 각 트윈에게 평가를 요청합니다. **Studio > Assets > Test existing assets**에서 실행하는 것과 같은 테스트를 자체 코드에서 실행할 수 있습니다. 예를 들어 디자이너가 Canva나 Adobe에서 파일을 내보낸 직후에 실행할 수 있습니다.

Research 쓰기 권한이 있는 [API 키](/ko/docs/mcp/overview)와 Point11에 설정한 오디언스(비즈니스 프로필과 그 고객)가 필요합니다. 아래의 모든 요청은 키를 `Authorization: Bearer $POINT11_API_KEY`로 보내고, 무언가를 변경하는 모든 요청은 `Idempotency-Key`에 새 UUID를 넣어 보냅니다.

## 각 크리에이티브 업로드하기

각 파일은 세 번의 요청으로 업로드합니다. 먼저 업로드를 예약하세요. 파일 이름, 형식, 정확한 바이트 크기, 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 모델에 이미지 한 장이 전달할 수 있는 최대 크기입니다. 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`는 각 트윈에게 있는 그대로 크리에이티브를 보여 줍니다. `direction`과 함께 `buying_scenario`를 지정하면 먼저 각 트윈을 설명한 구매 상황에 놓습니다.
- **지표.** 각 지표는 공통 척도에서 크리에이티브마다 하나의 평가 질문과 하나의 후속 질문이 됩니다. 따라서 테스트 질문 수는 크리에이티브 수 × (지표 수 + 1)이며 최대 100개입니다. 지표가 4개이면 크리에이티브를 최대 20개까지 테스트할 수 있습니다. 플랫폼 적합성에는 플랫폼이 하나 이상 필요합니다.

테스트는 즉시 `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`가 인터뷰와 결과를 가리킵니다.

인터뷰는 시간이 더 걸리므로, 테스트를 하나씩 읽는 대신 조직의 활동 리비전을 30~60초마다 읽으세요. 어떤 연구가 끝나거나 결과가 게시되면 바뀌므로, 요청 한 번으로 모든 테스트를 확인할 수 있습니다.

```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 서버를 합쳐 분당 100개의 요청을 사용할 수 있습니다. 키 하나로 분당 약 6개의 테스트를 시작하고, 분당 128개, 하루 300개의 파일을 업로드할 수 있습니다. 한도를 모두 쓰면 `429`가 반환되니 `Retry-After`의 초만큼 기다리세요.
- 요청을 안전하게 재시도하려면 같은 `Idempotency-Key`로 다시 보내세요. 시작을 재시도하면 같은 테스트가 반환되며, 두 번 청구되지 않습니다.