Testuj kreacje przez API

Przegląd#

Test kreacji pokazuje twoje reklamy, obrazy, filmy lub nagrania audio cyfrowym bliźniakom twoich klientów i prosi każdego bliźniaka o ocenę. Ten sam test, który uruchamiasz w Studio > Assets > Test existing assets, możesz uruchomić z własnego kodu, na przykład zaraz po tym, jak projektant wyeksportuje plik z Canvy lub Adobe.

Potrzebujesz klucza API z uprawnieniem zapisu w Research oraz grupy odbiorców skonfigurowanej w Point11: profilu firmy i jego klientów. Każde żądanie poniżej wysyła klucz jako Authorization: Bearer $POINT11_API_KEY, a każde żądanie, które coś zmienia, wysyła nowy UUID w Idempotency-Key.

Prześlij każdą kreację#

Prześlij każdy plik trzema żądaniami. Najpierw zarezerwuj przesłanie: wyślij nazwę pliku, typ, dokładny rozmiar w bajtach i SHA-256 (film nie wysyła SHA-256):

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>"}'

Następnie wyślij plik jako treść żądania upload z odpowiedzi, z dokładnie jego metodą, adresem URL i nagłówkami, zanim wygaśnie minutę później. Na koniec zakończ przesyłanie, podając id załącznika i etag zwrócony przez przesłanie:

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>"}'

Obrazy (PNG, JPEG, WebP) mogą mieć do 3 750 000 bajtów, czyli najwięcej, ile jeden obraz może przekazać każdemu modelowi AI, na którym może działać bliźniak; pliki PDF i dźwięk (MP3, WAV) do 4 MiB, a filmy (MP4, WebM) do 100 MiB i 3 minut. Bliźniaki widzą film jako klatki z oznaczeniem czasu oraz jego transkrypcję, więc poczekaj, aż GET /api/v1/research/study-attachments-v2/{id} pokaże jego scenorys jako gotowy.

Uruchom test#

Wskaż przesłane pliki, czego chcesz się dowiedzieć, grupę odbiorców i to, jak bliźniaki mają zetknąć się z kreacją:

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}
    ]
  }'

• Grupa odbiorców. audienceProfileId to id profilu twojej firmy z GET /api/v1/business/profiles. Zostaw targetedGroupIds puste, aby wybierać spośród wszystkich jego klientów, albo wskaż do 20 zapisanych grup odbiorców.
• Pierwsze wrażenie lub sytuacja zakupowa. first_impressions pokazuje kreację każdemu bliźniakowi takiemu, jaki jest. buying_scenario z direction najpierw umieszcza każdego bliźniaka w opisanej przez ciebie sytuacji zakupowej.
• Wskaźniki. Każdy wskaźnik staje się jednym pytaniem z oceną dla każdej kreacji na wspólnej skali oraz pytaniem uzupełniającym, więc test zadaje kreacje × (wskaźniki + 1) pytań, najwyżej 100. Przy 4 wskaźnikach możesz przetestować do 20 kreacji. Dopasowanie do platformy wymaga co najmniej jednej platformy.

Test od razu odpowiada 202. Zachowaj wysłany Idempotency-Key: od teraz oznacza on test.

Śledź test#

Gdy Point11 odczytuje twoją kreację i przygotowuje bliźniaki, odczytuj test po tym kluczu:

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

status ma wartość preparing, potem launched, failed lub unsupported, a phase pokazuje, jak daleko jest test. W ten sposób test może odczytać tylko klucz, który go uruchomił. Gdy ma status launched, campaignId i runId wskazują jego wywiady i wyniki.

Wywiady trwają dłużej, więc zamiast odczytywać każdy test, odczytuj co 30–60 sekund rewizję aktywności swojej organizacji. Zmienia się, gdy dowolne badanie się kończy lub publikuje wyniki, więc jedno żądanie obejmuje wszystkie twoje testy:

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

Gdy products.research się zmieni, odczytaj wyniki.

Odczytaj tabelę wyników#

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

Wyniki zawierają odpowiedzi na każde pytanie, podsumowanie z cytatami, liczbę zakończonych wywiadów oraz tabelę wyników: każdy wskaźnik dla każdej kreacji i łącznie. Wyniki to symulowane badanie z cyfrowymi bliźniakami twoich klientów, a nie zmierzone kliknięcia, sprzedaż czy konwersje.

Koszty i limity#

• Test kreacji jest rozliczany jak każde badanie Research: każdy dostarczony wywiad wlicza się do twojego planu w cenie wywiadu Research, a odczytanie kreacji i przygotowanie bliźniaków zużywają kredyty Alpha po ich dokładnym koszcie.
• Każdy klucz ma 100 żądań na minutę łącznie dla API i serwera MCP. Jeden klucz może uruchomić około 6 testów na minutę i przesłać 128 plików na minutę oraz 300 dziennie. Gdy budżet się wyczerpie, otrzymasz 429; odczekaj liczbę sekund z Retry-After.
• Aby bezpiecznie ponowić żądanie, wyślij je ponownie z tym samym Idempotency-Key. Ponowienie uruchomienia zwróci ten sam test i nic nie zostanie naliczone dwa razy.