# 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. Fonte: https://point11.ai/pt/docs/mcp/creative-testing Atualizado: 2026-10-18 ## 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](/pt/docs/mcp/overview) 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": ""}' ``` 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": "", "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": "", "targetedGroupIds": null, "targetedCustomerIds": null, "targetInterviewCount": 50 }, "studyMode": {"kind": "first_impressions"}, "metrics": ["stopping_power", "clarity", "appeal", "intent_to_act"], "platforms": ["Facebook", "Instagram"], "attachments": [ {"artifactId": "", "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.