Kreativmaterial mit der API testen

Laden Sie Anzeigen und anderes Kreativmaterial hoch, testen Sie es mit den digitalen Zwillingen Ihrer Kunden und lesen Sie die Scorecard in Ihrem Code.

Überblick#

Ein Kreativtest zeigt Ihre Anzeigen, Bilder, Videos oder Audiodateien den digitalen Zwillingen Ihrer Kunden und bittet jeden Zwilling, sie zu bewerten. Denselben Test, den Sie unter Studio > Assets > Test existing assets starten, können Sie aus Ihrem eigenen Code ausführen, etwa direkt nachdem ein Designer eine Datei aus Canva oder Adobe exportiert hat.

Sie brauchen einen API-Schlüssel mit Schreibzugriff auf Research und eine in Point11 eingerichtete Zielgruppe: ein Unternehmensprofil und seine Kunden. Jede Anfrage unten sendet den Schlüssel als Authorization: Bearer $POINT11_API_KEY, und jede Anfrage, die etwas ändert, sendet eine neue UUID in Idempotency-Key.

Jedes Kreativmaterial hochladen#

Laden Sie jede Datei mit drei Anfragen hoch. Reservieren Sie zuerst den Upload: Senden Sie Dateiname, Typ, genaue Größe in Bytes und SHA-256 (ein Video sendet keinen 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>"}'

Senden Sie die Datei dann als Body der upload-Anfrage aus der Antwort, mit genau deren Methode, URL und Headern, bevor sie eine Minute später abläuft. Schließen Sie den Upload zum Schluss mit der id des Anhangs und dem etag ab, das der Upload zurückgegeben hat:

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

Bilder (PNG, JPEG, WebP) dürfen bis zu 3.750.000 Byte groß sein, das Maximum, das ein Bild an jedes KI-Modell übertragen kann, auf dem ein Zwilling laufen kann; PDFs und Audio (MP3, WAV) bis zu 4 MiB und Videos (MP4, WebM) bis zu 100 MiB und 3 Minuten. Zwillinge sehen ein Video als zeitlich versetzte Einzelbilder mit seinem Transkript; warten Sie daher, bis GET /api/v1/research/study-attachments-v2/{id} sein Storyboard als fertig zeigt.

Den Test starten#

Nennen Sie die hochgeladenen Dateien, was Sie erfahren möchten, die Zielgruppe und wie die Zwillinge dem Kreativmaterial begegnen sollen:

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}
    ]
  }'
  • Zielgruppe. audienceProfileId ist die ID Ihres Unternehmensprofils aus GET /api/v1/business/profiles. Lassen Sie targetedGroupIds leer, um aus allen seinen Kunden zu wählen, oder nennen Sie bis zu 20 gespeicherte Zielgruppen.
  • Erster Eindruck oder Kaufsituation. first_impressions zeigt jedem Zwilling das Kreativmaterial so, wie er ist. buying_scenario mit einer direction versetzt jeden Zwilling zuerst in die Kaufsituation, die Sie beschreiben.
  • Kennzahlen. Jede Kennzahl wird zu einer Bewertungsfrage pro Kreativmaterial auf einer gemeinsamen Skala, plus einer Nachfrage; ein Test stellt also Kreativmaterialien × (Kennzahlen + 1) Fragen, höchstens 100. Mit 4 Kennzahlen können Sie bis zu 20 Kreativmaterialien testen. Plattformeignung braucht mindestens eine Plattform.

Der Test antwortet sofort mit 202. Behalten Sie den gesendeten Idempotency-Key: Er benennt den Test von nun an.

Den Test verfolgen#

Während Point11 Ihr Kreativmaterial liest und die Zwillinge vorbereitet, lesen Sie den Test über diesen Schlüssel:

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

status ist preparing, dann launched, failed oder unsupported, und phase zeigt, wie weit er ist. Nur der Schlüssel, der einen Test gestartet hat, kann ihn so lesen. Sobald er launched ist, benennen campaignId und runId seine Interviews und Ergebnisse.

Die Interviews dauern länger. Lesen Sie deshalb statt jedes einzelnen Tests alle 30 bis 60 Sekunden die Aktivitätsrevision Ihrer Organisation. Sie ändert sich, sobald eine Studie endet oder ihre Ergebnisse veröffentlicht werden, sodass eine Anfrage alle Ihre Tests abdeckt:

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

Wenn sich products.research ändert, lesen Sie die Ergebnisse.

Die Scorecard lesen#

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

Die Ergebnisse enthalten die Antworten auf jede Frage, eine Zusammenfassung mit Zitaten, wie viele Interviews abgeschlossen wurden, und die Scorecard: jede Kennzahl für jedes Kreativmaterial und insgesamt. Die Ergebnisse sind simulierte Forschung mit den digitalen Zwillingen Ihrer Kunden, keine gemessenen Klicks, Verkäufe oder Conversions.

Kosten und Grenzen#

  • Ein Kreativtest wird wie jede Research-Studie abgerechnet: Jedes gelieferte Interview zählt zum Interviewpreis von Research für Ihren Tarif, und das Lesen des Kreativmaterials und die Vorbereitung der Zwillinge verbrauchen Alpha-Guthaben zu ihren genauen Kosten.
  • Jeder Schlüssel hat 100 Anfragen pro Minute für API und MCP-Server zusammen. Ein Schlüssel kann etwa 6 Tests pro Minute starten und 128 Dateien pro Minute sowie 300 pro Tag hochladen. Ist ein Kontingent aufgebraucht, erhalten Sie 429; warten Sie die Sekunden aus Retry-After.
  • Um eine Anfrage sicher zu wiederholen, senden Sie sie mit demselben Idempotency-Key erneut. Ein wiederholter Start liefert denselben Test zurück, und nichts wird doppelt berechnet.