Testa le creatività con l’API

Panoramica#

Un test creativo mostra i tuoi annunci, immagini, video o audio ai gemelli digitali dei tuoi clienti e chiede a ogni gemello di valutarli. Puoi eseguire dal tuo codice lo stesso test che esegui da Studio > Assets > Test existing assets, per esempio subito dopo che un designer ha esportato un file da Canva o Adobe.

Ti servono una chiave API con accesso in scrittura a Research e un pubblico configurato in Point11: un profilo aziendale e i suoi clienti. Ogni richiesta qui sotto invia la chiave come Authorization: Bearer $POINT11_API_KEY, e ogni richiesta che modifica qualcosa invia un nuovo UUID in Idempotency-Key.

Carica ogni creatività#

Carica ogni file con tre richieste. Prima prenota il caricamento: invia nome del file, tipo, dimensione esatta in byte e SHA-256 (un video non invia lo 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>"}'

Poi invia il file come corpo della richiesta upload della risposta, con esattamente metodo, URL e intestazioni, prima che scada un minuto dopo. Infine completa il caricamento con l’id dell’allegato e l’etag restituito dal caricamento:

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

Le immagini (PNG, JPEG, WebP) possono arrivare a 3.750.000 byte, il massimo che un’immagine può portare a ogni modello di IA su cui può funzionare un gemello; PDF e audio (MP3, WAV) fino a 4 MiB; i video (MP4, WebM) fino a 100 MiB e 3 minuti. I gemelli vedono un video come fotogrammi con indicazione del tempo e la sua trascrizione, quindi aspetta che GET /api/v1/research/study-attachments-v2/{id} mostri lo storyboard come pronto.

Avvia il test#

Indica i file caricati, cosa vuoi scoprire, il pubblico e come i gemelli devono incontrare la creatività:

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

• Pubblico. audienceProfileId è l’id del tuo profilo aziendale, da GET /api/v1/business/profiles. Lascia vuoto targetedGroupIds per attingere a tutti i suoi clienti, oppure indica fino a 20 pubblici salvati.
• Prime impressioni o una situazione d’acquisto. first_impressions mostra la creatività a ogni gemello così com’è. buying_scenario con una direction colloca prima ogni gemello nella situazione d’acquisto che descrivi.
• Metriche. Ogni metrica diventa una domanda di valutazione per creatività su una scala comune, più una domanda di approfondimento, quindi un test pone creatività × (metriche + 1) domande, al massimo 100. Con 4 metriche puoi testare fino a 20 creatività. L’adeguatezza alla piattaforma richiede almeno una piattaforma.

Il test risponde subito 202. Conserva l’Idempotency-Key che hai inviato: da ora in poi identifica il test.

Segui il test#

Mentre Point11 legge la tua creatività e prepara i gemelli, leggi il test con quella chiave:

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

status è preparing, poi launched, failed o unsupported, e phase indica a che punto è. Solo la chiave che ha avviato un test può leggerlo in questo modo. Quando è launched, campaignId e runId identificano le sue interviste e i risultati.

Le interviste richiedono più tempo, quindi invece di leggere ogni test leggi la revisione dell’attività della tua organizzazione ogni 30-60 secondi. Cambia quando uno studio termina o ne vengono pubblicati i risultati, quindi una sola richiesta copre tutti i tuoi test:

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

Quando products.research cambia, leggi i risultati.

Leggi la scheda dei punteggi#

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

I risultati riportano le risposte a ogni domanda, un riepilogo con citazioni, quante interviste si sono concluse e la scheda dei punteggi: ogni metrica per ogni creatività e nel complesso. I risultati sono ricerca simulata con i gemelli digitali dei tuoi clienti, non clic, vendite o conversioni misurati.

Costi e limiti#

• Un test creativo è fatturato come qualsiasi studio Research: ogni intervista consegnata conta per il tuo piano al prezzo di un’intervista Research, e la lettura della creatività e la preparazione dei gemelli usano crediti Alpha al loro costo esatto.
• Ogni chiave ha 100 richieste al minuto tra API e server MCP. Una chiave può avviare circa 6 test al minuto e caricare 128 file al minuto e 300 al giorno. Quando un budget si esaurisce ricevi 429; aspetta i secondi indicati da Retry-After.
• Per riprovare una richiesta in sicurezza, inviala di nuovo con la stessa Idempotency-Key. Riprovare un avvio ti restituisce lo stesso test, e nulla viene addebitato due volte.