Teste criativos com a API

Envie anúncios e outros criativos, teste-os com os gêmeos digitais dos seus clientes e leia o placar no seu próprio código.

Visão geral#

Um teste criativo mostra seus anúncios, imagens, vídeos ou áudios aos gêmeos digitais dos seus clientes e pede que cada gêmeo os avalie. Você pode executar no seu próprio código o mesmo teste que executa em Studio > Assets > Test existing assets, por exemplo logo depois que um designer exporta um arquivo do Canva ou da Adobe.

Você precisa de uma chave de API com acesso de escrita ao Research e de um público configurado no Point11: um perfil de empresa e seus clientes. Cada solicitação abaixo envia a chave como Authorization: Bearer $POINT11_API_KEY, e cada solicitação que altera algo envia um novo UUID em Idempotency-Key.

Envie cada criativo#

Envie cada arquivo em três solicitações. Primeiro, reserve o envio: mande o nome do arquivo, o tipo, o tamanho exato em bytes e o SHA-256 (um vídeo não envia 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>"}'

Depois, envie o arquivo como corpo da solicitação upload da resposta, com exatamente o método, a URL e os cabeçalhos dela, antes que expire um minuto depois. Por fim, conclua o envio com o id do anexo e o etag que o envio retornou:

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

Imagens (PNG, JPEG, WebP) podem ter até 3.750.000 bytes, o máximo que uma imagem pode levar a qualquer modelo de IA em que um gêmeo possa rodar; PDFs e áudio (MP3, WAV), até 4 MiB; e vídeos (MP4, WebM), até 100 MiB e 3 minutos. Os gêmeos veem um vídeo como quadros com marcação de tempo e sua transcrição, então espere até que GET /api/v1/research/study-attachments-v2/{id} mostre o storyboard como pronto.

Inicie o teste#

Indique os arquivos enviados, o que você quer descobrir, o público e como os gêmeos devem encontrar o criativo:

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}
    ]
  }'
  • Público. audienceProfileId é o id do seu perfil de empresa, de GET /api/v1/business/profiles. Deixe targetedGroupIds vazio para escolher entre todos os clientes dele, ou indique até 20 públicos salvos.
  • Primeiras impressões ou uma situação de compra. first_impressions mostra o criativo a cada gêmeo como ele é. buying_scenario com uma direction coloca antes cada gêmeo na situação de compra que você descrever.
  • Métricas. Cada métrica vira uma pergunta de avaliação por criativo em uma escala comum, mais uma pergunta de acompanhamento, então um teste faz criativos × (métricas + 1) perguntas, no máximo 100. Com 4 métricas você pode testar até 20 criativos. A adequação à plataforma precisa de pelo menos uma plataforma.

O teste responde 202 na hora. Guarde a Idempotency-Key que você enviou: a partir de agora, ela identifica o teste.

Acompanhe o teste#

Enquanto o Point11 lê seu criativo e prepara os gêmeos, leia o teste por essa chave:

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

status é preparing e depois launched, failed ou unsupported, e phase mostra até onde ele chegou. Só a chave que iniciou um teste pode lê-lo assim. Quando ele estiver launched, campaignId e runId identificam suas entrevistas e resultados.

As entrevistas demoram mais, então, em vez de ler cada teste, leia a revisão de atividade da sua organização a cada 30 a 60 segundos. Ela muda quando qualquer estudo termina ou seus resultados são publicados, então uma única solicitação cobre todos os seus testes:

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

Quando products.research mudar, leia os resultados.

Leia o placar#

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

Os resultados trazem as respostas de cada pergunta, um resumo com citações, quantas entrevistas terminaram e o placar: cada métrica para cada criativo e no total. Os resultados são pesquisa simulada com os gêmeos digitais dos seus clientes, não cliques, vendas ou conversões medidos.

Custos e limites#

  • Um teste criativo é cobrado como qualquer estudo do Research: cada entrevista entregue conta para o seu plano pelo preço de entrevista do Research, e ler o criativo e preparar os gêmeos consomem créditos do Alpha pelo custo exato.
  • Cada chave tem 100 solicitações por minuto somando a API e o servidor MCP. Uma chave pode iniciar cerca de 6 testes por minuto e enviar 128 arquivos por minuto e 300 por dia. Quando um limite se esgota, você recebe 429; espere os segundos de Retry-After.
  • Para repetir uma solicitação com segurança, envie-a de novo com a mesma Idempotency-Key. Repetir um início devolve o mesmo teste, e nada é cobrado duas vezes.