Kreatifleri API ile test edin

Genel bakış#

Bir kreatif testi reklamlarınızı, görsellerinizi, videolarınızı veya seslerinizi müşterilerinizin dijital ikizlerine gösterir ve her ikizden bunları puanlamasını ister. Studio > Assets > Test existing assets üzerinden çalıştırdığınız testin aynısını kendi kodunuzdan çalıştırabilirsiniz; örneğin bir tasarımcı Canva veya Adobe'dan bir dosyayı dışa aktardıktan hemen sonra.

Research'e yazma erişimi olan bir API anahtarına ve Point11'de kurduğunuz bir kitleye ihtiyacınız var: bir işletme profili ve onun müşterileri. Aşağıdaki her istek anahtarı Authorization: Bearer $POINT11_API_KEY olarak gönderir ve bir şeyi değiştiren her istek Idempotency-Key içinde yeni bir UUID gönderir.

Her kreatifi yükleyin#

Her dosyayı üç istekle yükleyin. Önce yüklemeyi ayırın: dosyanın adını, türünü, bayt cinsinden tam boyutunu ve SHA-256 değerini gönderin (video SHA-256 göndermez):

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

Ardından dosyayı, yanıttaki upload isteğinin gövdesi olarak, tam olarak onun yöntemi, URL'si ve başlıklarıyla, bir dakika sonra süresi dolmadan gönderin. Son olarak yüklemeyi ekin id değeri ve yüklemenin döndürdüğü etag ile tamamlayın:

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

Görseller (PNG, JPEG, WebP) en fazla 3.750.000 bayt olabilir; bu, bir görselin bir ikizin çalışabileceği her yapay zekâ modeline taşıyabileceği en büyük boyuttur. PDF'ler ve ses (MP3, WAV) en fazla 4 MiB, videolar (MP4, WebM) en fazla 100 MiB ve 3 dakika olabilir. İkizler bir videoyu zaman damgalı kareler ve dökümü olarak görür; bu yüzden GET /api/v1/research/study-attachments-v2/{id} storyboard'unun hazır olduğunu gösterene kadar bekleyin.

Testi başlatın#

Yüklenen dosyaları, öğrenmek istediğiniz şeyi, kitleyi ve ikizlerin kreatifle nasıl karşılaşacağını belirtin:

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

• Kitle. audienceProfileId, GET /api/v1/business/profiles ile aldığınız işletme profilinizin kimliğidir. Tüm müşterileri arasından seçmek için targetedGroupIds alanını boş bırakın veya en fazla 20 kayıtlı kitle belirtin.
• İlk izlenim veya bir satın alma durumu. first_impressions kreatifi her ikize olduğu haliyle gösterir. direction ile birlikte buying_scenario önce her ikizi tarif ettiğiniz satın alma durumuna yerleştirir.
• Metrikler. Her metrik, ortak bir ölçekte kreatif başına bir puanlama sorusuna ve bir takip sorusuna dönüşür; bu yüzden bir test kreatif × (metrik + 1) soru sorar, en fazla 100. 4 metrikle en fazla 20 kreatif test edebilirsiniz. Platform uyumu en az bir platform gerektirir.

Test hemen 202 ile yanıt verir. Gönderdiğiniz Idempotency-Key değerini saklayın: bundan sonra testi o adlandırır.

Testi takip edin#

Point11 kreatifinizi okuyup ikizleri hazırlarken testi bu anahtarla okuyun:

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

status önce preparing, sonra launched, failed veya unsupported olur; phase ise ne kadar ilerlediğini söyler. Bir testi bu şekilde yalnızca onu başlatan anahtar okuyabilir. launched olduğunda campaignId ve runId görüşmelerini ve sonuçlarını adlandırır.

Görüşmeler daha uzun sürer; bu yüzden her testi okumak yerine kuruluşunuzun etkinlik revizyonunu 30 ila 60 saniyede bir okuyun. Herhangi bir çalışma bittiğinde veya sonuçları yayımlandığında değişir; böylece tek bir istek tüm testlerinizi kapsar:

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

products.research değiştiğinde sonuçları okuyun.

Puan tablosunu okuyun#

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

Sonuçlar her sorunun yanıtlarını, alıntılarla bir özeti, kaç görüşmenin tamamlandığını ve puan tablosunu verir: her kreatif için ve genel olarak her metrik. Sonuçlar, müşterilerinizin dijital ikizleriyle yapılan simüle edilmiş araştırmadır; ölçülmüş tıklama, satış veya dönüşüm değildir.

Maliyetler ve sınırlar#

• Bir kreatif testi her Research çalışması gibi faturalandırılır: teslim edilen her görüşme Research görüşme fiyatı üzerinden planınıza sayılır; kreatifi okumak ve ikizleri hazırlamak ise Alpha kredilerini tam maliyetleriyle kullanır.
• Her anahtarın API ve MCP sunucusu genelinde dakikada 100 isteği vardır. Bir anahtar dakikada yaklaşık 6 test başlatabilir; dakikada 128, günde 300 dosya yükleyebilir. Bir bütçe tükendiğinde 429 alırsınız; Retry-After kadar saniye bekleyin.
• Bir isteği güvenle yeniden denemek için aynı Idempotency-Key ile tekrar gönderin. Bir başlatmayı yeniden denemek size aynı testi geri verir ve hiçbir şey iki kez ücretlendirilmez.