Prueba creatividades con la API

Resumen#

Una prueba creativa muestra tus anuncios, imágenes, vídeos o audios a los gemelos digitales de tus clientes y pide a cada gemelo que los valore. Puedes ejecutar desde tu propio código la misma prueba que ejecutas desde Studio > Assets > Test existing assets, por ejemplo justo después de que un diseñador exporte un archivo desde Canva o Adobe.

Necesitas una clave de API con acceso de escritura a Research y una audiencia configurada en Point11: un perfil de empresa y sus clientes. Cada solicitud de abajo envía la clave como Authorization: Bearer $POINT11_API_KEY, y cada solicitud que cambia algo envía un UUID nuevo en Idempotency-Key.

Sube cada creatividad#

Sube cada archivo en tres solicitudes. Primero, reserva la subida: envía el nombre del archivo, su tipo, su tamaño exacto en bytes y su SHA-256 (un vídeo no enví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>"}'

Después, envía el archivo como cuerpo de la solicitud upload de la respuesta, con exactamente su método, su URL y sus encabezados, antes de que caduque un minuto después. Por último, termina la subida con el id del adjunto y el etag que devolvió la subida:

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

Las imágenes (PNG, JPEG, WebP) pueden ocupar hasta 3.750.000 bytes, lo máximo que una imagen puede llevar a cualquiera de los modelos de IA en los que puede funcionar un gemelo; los PDF y el audio (MP3, WAV), hasta 4 MiB; y los vídeos (MP4, WebM), hasta 100 MiB y 3 minutos. Los gemelos ven un vídeo como fotogramas con marca de tiempo y su transcripción, así que espera hasta que GET /api/v1/research/study-attachments-v2/{id} muestre su storyboard como listo.

Inicia la prueba#

Indica los archivos subidos, qué quieres averiguar, la audiencia y cómo deben encontrarse los gemelos con la creatividad:

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

• Audiencia. audienceProfileId es el id de tu perfil de empresa, de GET /api/v1/business/profiles. Deja targetedGroupIds vacío para elegir entre todos sus clientes, o indica hasta 20 audiencias guardadas.
• Primeras impresiones o una situación de compra. first_impressions muestra la creatividad a cada gemelo tal como es. buying_scenario con una direction sitúa antes a cada gemelo en la situación de compra que describas.
• Métricas. Cada métrica se convierte en una pregunta de valoración por creatividad en una escala común, más una pregunta de seguimiento, así que una prueba hace creatividades × (métricas + 1) preguntas, como máximo 100. Con 4 métricas puedes probar hasta 20 creatividades. La adecuación a la plataforma necesita al menos una plataforma.

La prueba responde 202 al instante. Guarda la Idempotency-Key que enviaste: a partir de ahora identifica la prueba.

Sigue la prueba#

Mientras Point11 lee tu creatividad y prepara a los gemelos, lee la prueba con esa clave:

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

status es preparing y después launched, failed o unsupported, y phase indica hasta dónde ha llegado. Solo la clave que inició una prueba puede leerla así. Cuando está launched, campaignId y runId identifican sus entrevistas y resultados.

Las entrevistas tardan más, así que, en lugar de leer cada prueba, lee la revisión de actividad de tu organización cada 30 a 60 segundos. Cambia cuando termina cualquier estudio o se publican sus resultados, así que una sola solicitud cubre todas tus pruebas:

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

Cuando cambie products.research, lee los resultados.

Lee la tabla de puntuaciones#

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

Los resultados dan las respuestas a cada pregunta, un resumen con citas, cuántas entrevistas terminaron y la tabla de puntuaciones: cada métrica para cada creatividad y en conjunto. Los resultados son investigación simulada con los gemelos digitales de tus clientes, no clics, ventas ni conversiones medidos.

Costes y límites#

• Una prueba creativa se factura como cualquier estudio de Research: cada entrevista entregada cuenta para tu plan al precio de una entrevista de Research, y leer la creatividad y preparar a los gemelos consume créditos de Alpha a su coste exacto.
• Cada clave tiene 100 solicitudes por minuto entre la API y el servidor MCP. Una clave puede iniciar unas 6 pruebas por minuto y subir 128 archivos por minuto y 300 al día. Cuando se agota un presupuesto recibes 429; espera los segundos de Retry-After.
• Para reintentar una solicitud con seguridad, vuelve a enviarla con la misma Idempotency-Key. Reintentar un inicio te devuelve la misma prueba, y no se cobra nada dos veces.