Tester des créations avec l’API

Vue d’ensemble#

Un test de créations montre vos annonces, images, vidéos ou fichiers audio aux jumeaux numériques de vos clients et demande à chaque jumeau de les noter. Vous pouvez lancer depuis votre propre code le même test que depuis Studio > Assets > Test existing assets, par exemple juste après qu’un graphiste a exporté un fichier depuis Canva ou Adobe.

Il vous faut une clé API avec un accès en écriture à Research, et une audience configurée dans Point11 : un profil d’entreprise et ses clients. Chaque requête ci-dessous envoie la clé en tant que Authorization: Bearer $POINT11_API_KEY, et chaque requête qui modifie quelque chose envoie un nouvel UUID dans Idempotency-Key.

Importer chaque création#

Importez chaque fichier en trois requêtes. D’abord, réservez l’import : envoyez le nom du fichier, son type, sa taille exacte en octets et son SHA-256 (une vidéo n’envoie pas de 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>"}'

Envoyez ensuite le fichier comme corps de la requête upload de la réponse, avec exactement sa méthode, son URL et ses en-têtes, avant son expiration une minute plus tard. Enfin, terminez l’import avec l’id de la pièce jointe et l’etag renvoyé par l’import :

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

Les images (PNG, JPEG, WebP) peuvent peser jusqu’à 3 750 000 octets, le maximum qu’une image peut transmettre à chacun des modèles d’IA sur lesquels un jumeau peut fonctionner, les PDF et l’audio (MP3, WAV) jusqu’à 4 Mio, et les vidéos (MP4, WebM) jusqu’à 100 Mio et 3 minutes. Les jumeaux voient une vidéo sous forme d’images horodatées et de sa transcription : attendez donc que GET /api/v1/research/study-attachments-v2/{id} indique que son storyboard est prêt.

Lancer le test#

Indiquez les fichiers importés, ce que vous voulez apprendre, l’audience et la façon dont les jumeaux découvrent la création :

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

• Audience. audienceProfileId est l’identifiant de votre profil d’entreprise, obtenu avec GET /api/v1/business/profiles. Laissez targetedGroupIds vide pour puiser parmi tous ses clients, ou nommez jusqu’à 20 audiences enregistrées.
• Premières impressions ou situation d’achat. first_impressions montre la création à chaque jumeau tel qu’il est. buying_scenario avec une direction place d’abord chaque jumeau dans la situation d’achat que vous décrivez.
• Indicateurs. Chaque indicateur devient une question de notation par création, sur une échelle commune, plus une question de suivi : un test pose donc créations × (indicateurs + 1) questions, 100 au maximum. Avec 4 indicateurs, vous pouvez tester jusqu’à 20 créations. L’adéquation à la plateforme nécessite au moins une plateforme.

Le test répond aussitôt 202. Conservez l’Idempotency-Key envoyée : elle désigne désormais le test.

Suivre le test#

Pendant que Point11 lit votre création et prépare les jumeaux, lisez le test avec cette clé :

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

status vaut preparing, puis launched, failed ou unsupported, et phase indique où il en est. Seule la clé qui a lancé un test peut le lire ainsi. Une fois qu’il est launched, campaignId et runId désignent ses entretiens et ses résultats.

Les entretiens prennent plus de temps : au lieu de lire chaque test, lisez la révision d’activité de votre organisation toutes les 30 à 60 secondes. Elle change dès qu’une étude se termine ou que ses résultats sont publiés, si bien qu’une seule requête couvre tous vos tests :

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

Quand products.research change, lisez les résultats.

Lire le tableau de scores#

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

Les résultats donnent les réponses à chaque question, un résumé avec des citations, le nombre d’entretiens terminés et le tableau de scores : chaque indicateur pour chaque création, et au global. Les résultats sont une recherche simulée avec les jumeaux numériques de vos clients, et non des clics, des ventes ou des conversions mesurés.

Coûts et limites#

• Un test de créations est facturé comme toute étude Research : chaque entretien livré est décompté de votre forfait au prix d’un entretien Research, et la lecture de la création et la préparation des jumeaux consomment des crédits Alpha à leur coût exact.
• Chaque clé dispose de 100 requêtes par minute, pour l’API et le serveur MCP réunis. Une clé peut lancer environ 6 tests par minute, et importer 128 fichiers par minute et 300 par jour. Lorsqu’un budget est épuisé, vous recevez 429 ; attendez le nombre de secondes indiqué par Retry-After.
• Pour réessayer une requête en toute sécurité, renvoyez-la avec la même Idempotency-Key. Réessayer un lancement vous renvoie le même test, et rien n’est facturé deux fois.