Creative Scoring API Guide: Rank Ad Creative with REST

The Kettio Rank API accepts a matched batch of ad creative and returns an audience-specific order with scores, written rationales, and confidence information. Use it when an agent, script, or internal tool needs to decide which finished assets deserve the next live test.

This is a comparative decision signal, not a guaranteed CTR or revenue forecast. Hold the offer, audience, platform, and objective steady within a batch, then reconcile the frozen ranking against live campaign outcomes. This guide covers authentication, request structure, response fields, and a working REST integration.

How AI Creative Scoring Works

Most attempts at AI ad scoring fail because they ask an LLM to rate an ad on a numerical scale. LLMs are terrible at this — they regress to the mean, produce inconsistent scores, and can't differentiate between a mediocre ad and a great one.

Kettio's SSR (Semantic Similarity Rating) pipeline takes a fundamentally different approach:

1. Persona construction. Your target audience demographics are used to build a detailed synthetic persona — a rich behavioral profile that specifies how this person browses, what triggers their skepticism, how price-sensitive they are, and what kind of visual messaging resonates with them.
2. Ensemble evaluation. Multiple AI models (Gemini Flash and Claude Haiku) independently evaluate each creative from the persona's perspective. Each model writes a natural-language rationale explaining what works and what doesn't. Using multiple models prevents any single model's biases from dominating.
3. Semantic calibration. The rationales are compared with calibrated anchor texts representing different response levels. This converts structured language into a numerical distribution that can be compared across evaluations.
4. Score aggregation. The embedding similarities are aggregated into a final score (1-5 scale) with confidence metrics. Assets are ranked from best to worst.

The result is a directional ranking with confidence information. Kettio publishes retrospective results on external datasets in its methodology; those bounded evaluations are not guarantees of prospective campaign performance.

Getting Started

Step 1: Get Your API Key

Sign up at kettio.com/login and navigate to your dashboard. Generate an API key — it will look like agk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. Store it securely. The raw key is shown only once.

Step 2: Your First Rank Call

Here's the simplest possible scoring call — two ads, one audience, ranked by purchase intent:

curl -X POST https://kettio.com/api/v1/rank   -H "Authorization: Bearer agk_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "assets": [
      {
        "url": "https://your-cdn.com/ad-variant-a.png",
        "id": "variant-a",
        "copy_context": {
          "pageName": "Pawbox",
          "adBody": "First box free for new subscribers. Fresh treats picked for picky dogs.",
          "adHeadline": "Healthy treats your dog will actually want",
          "adCaption": "Cancel anytime"
        }
      },
      { "url": "https://your-cdn.com/ad-variant-b.png", "id": "variant-b" }
    ],
    "audience": {
      "name": "Millennial pet owners",
      "description": "Dog owners aged 25-34, mid-income, active on Instagram",
      "demographics": {
        "ageRange": "25-34",
        "incomeLevel": "50k-75k",
        "priceSensitivity": "moderate",
        "shoppingIntent": "researching",
        "platformFatigue": "high"
      }
    },
    "goal": "purchase-intent",
    "platform": "meta",
    "refine_close_pairs": true
  }'

Step 3: Understand the Response

The API returns assets ranked from best to worst:

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "ranked": [
    {
      "rank": 1,
      "asset_url": "https://your-cdn.com/ad-variant-a.png",
      "asset_id": "variant-a",
      "score": 4.23,
      "score_before_refine": 4.23,
      "score_layer": "full-ad-package",
      "asset_type": "Social Media Post",
      "copy_context_included": true,
      "image_only_score": 3.81,
      "copy_lift": 0.42,
      "rationale": "This ad immediately communicates value with a clear product shot and a relatable lifestyle context. The warm color palette and casual dog-owner imagery would resonate with millennial pet owners who are browsing Instagram. The price point is visible but not aggressive, which works well for a researching audience with moderate price sensitivity.",
      "product_read": "A promotional image showing a person with a golden retriever, featuring a subscription box for dog treats. Price shown as $29/month with a 'First box free' callout.",
      "panel_outcome": null,
      "confidence": "high",
      "confidence_details": {
        "entropy": 0.38,
        "top_margin": 0.35,
        "sample_std_dev": 0.06
      },
      "details": {
        "probabilities": [0.02, 0.06, 0.18, 0.46, 0.28],
        "similarities": [0.12, 0.21, 0.35, 0.47, 0.41]
      }
    },
    {
      "rank": 2,
      "asset_url": "https://your-cdn.com/ad-variant-b.png",
      "asset_id": "variant-b",
      "score": 2.87,
      "score_before_refine": 2.87,
      "score_layer": "image-only",
      "asset_type": "Social Media Post",
      "copy_context_included": false,
      "image_only_score": 2.87,
      "copy_lift": 0,
      "rationale": "The ad relies heavily on text-based value propositions without showing the actual product. For an audience with high platform fatigue, this format feels too similar to generic DTC ads they scroll past daily. The stock photography undermines authenticity.",
      "product_read": "A text-heavy banner ad for a dog treat subscription with stock photography of a generic dog. Lists three bullet points of benefits.",
      "panel_outcome": null,
      "confidence": "high",
      "confidence_details": {
        "entropy": 0.45,
        "top_margin": 0.28,
        "sample_std_dev": 0.09
      }
    }
  ],
  "errors": [],
  "summary": {
    "goal": "purchase-intent",
    "asset_type": "Social Media Post",
    "audience": "Millennial pet owners",
    "assets_ranked": 2,
    "assets_failed": 0,
    "scoring_evaluations": 3,
    "close_pair_refinement": {
      "enabled": true,
      "pairs_evaluated": 0,
      "results": []
    },
    "credits_used": 3,
    "credits_remaining": 48
  }
}

Key fields to pay attention to:

• score — 1 to 5 scale. 4+ is strong. Below 3 needs work.
• image_only_score and copy_lift — When you include copy_context, Kettio also runs an image-only ablation so you can separate visual strength from copy contribution.
• score_before_refine and panel_outcome — Shows whether close-pair refinement changed the final ordering for near ties.
• rationale — Natural language explanation of why the score is what it is. This is written from the persona's perspective, which means it reflects how your target audience would actually react.
• product_read — What the AI saw in your ad. Useful for verifying the model understood your creative correctly.
• confidence — high, medium, or low. If confidence is low, consider running a Champion-Challenger test for a more rigorous comparison.

JavaScript / TypeScript Integration

Here's a typed function you can drop into your agent or application:

interface RankRequest {
  assets: Array<{
    url: string;
    id?: string;
    asset_type?: string;
    copy_context?: {
      pageName?: string;
      adBody?: string;
      adHeadline?: string;
      adCaption?: string;
      adDescription?: string;
      primaryText?: string;
      headline?: string;
      caption?: string;
      description?: string;
    };
  }>;
  audience?: {
    name: string;
    description?: string;
    demographics?: Record<string, string>;
  };
  audience_id?: string;
  goal?: string;
  asset_type?: string;
  platform?: string;
  campaign_type?: string;
  refine_close_pairs?: boolean;
}

interface RankedAsset {
  rank: number;
  asset_url: string;
  asset_id: string | null;
  score: number;
  score_before_refine: number;
  score_layer: 'image-only' | 'copy-only' | 'full-ad-package';
  asset_type: string;
  copy_context_included: boolean;
  image_only_score: number | null;
  copy_lift: number | null;
  rationale: string;
  product_read: string;
  panel_outcome: {
    winnerAssetId: string;
    loserAssetId: string;
    flipped: boolean;
    votesFor: number;
    votesTotal: number;
    consistency: number;
  } | null;
  confidence: 'high' | 'medium' | 'low';
  confidence_details: {
    entropy: number;
    top_margin: number;
    sample_std_dev: number;
  };
  details: {
    probabilities: number[];
    similarities: number[];
  };
}

interface RankResponse {
  request_id: string;
  ranked: RankedAsset[];
  errors: Array<{ asset_url: string; error: string }>;
  summary: {
    goal: string;
    asset_type: string;
    platform: string | null;
    audience: string;
    assets_ranked: number;
    assets_failed: number;
    scoring_evaluations: number;
    close_pair_refinement: {
      enabled: boolean;
      pairs_evaluated: number;
      results: Array<Record<string, unknown>>;
    };
    credits_used: number;
    credits_remaining: number | null;
  };
}

async function rankCreatives(
  apiKey: string,
  request: RankRequest
): Promise<RankResponse> {
  const response = await fetch('https://kettio.com/api/v1/rank', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(request),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Rank API error: ${error.error}`);
  }

  return response.json();
}

Python Integration