# Testa le creatività con l’API

Carica annunci e altre creatività, testale con i gemelli digitali dei tuoi clienti e leggi la scheda dei punteggi dal tuo codice.

Fonte: https://point11.ai/it/docs/mcp/creative-testing  
Aggiornato: 2026-10-18

## 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](/it/docs/mcp/overview) 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):

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

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:

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

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à:

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

- **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:

```bash
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:

```bash
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

```bash
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.