score_hooks_batch
Score many hooks ranked with best, or compare named SETS. Free during beta.
All-or-nothing charge. Plain: texts (1-25, each 3-300 chars). Self-test (E13):
compare=true + sets (2-4 named lists, <=25 texts total) INSTEAD of texts -> per-set
rankings + avg_score + winner + an honest winner_summary (same heuristic scorer
on every set, never view prediction). Also: platform, tags, verbosity, api_key,
idempotency_key. Returns {results, best, ...} or {sets, winner, winner_summary, ...}.
Errors: unauthorized, invalid_request, insufficient_credits, rate_limited.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sets | No | Compare mode input: 2-4 NAMED variant lists, e.g. {"curiosity": ["..."], "contrarian": ["..."]}, each 1-25 texts and <=25 texts across all sets. Requires compare=true and excludes `texts`. Every set is scored by the SAME heuristic scorer, so the winner is a craft comparison, never a view prediction. | |
| tags | No | 1-5 lowercase slug tags ([a-z0-9_-], <=40 chars) stamped on this call's usage event so a fleet can attribute spend per campaign. Omit for no tagging. Filter later with get_usage(tag=...) / list_hooks(tag=...). | |
| texts | No | 1-25 hook lines (3-300 chars each) to score and rank. Use this OR sets, never both: texts is the plain ranked mode, sets is the compare mode. Customer charge is zero during beta. | |
| topic | No | What the hooks are about, 3-200 chars. Supply it to score these lines the way they were generated: the scorer penalises a line that only echoes its own topic back, and it cannot apply that penalty to a topic it was never told. Omit and the scores are topic-blind, so they will not match the numbers a topic-aware call was charged for. | |
| api_key | No | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (the stdio default). No key resolvable -> unauthorized. | |
| compare | No | Switch on compare mode, which requires `sets` and returns per-set rankings + a winner instead of one flat ranking. Leave false for the ordinary texts ranking. | |
| platform | No | Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted. | tiktok |
| verbosity | No | How much of the response envelope to return: minimal (identity, text, score total/source, money, honesty warnings, and any persona/shape), standard (the default, including hook receipts), full (adds per-dimension score numbers, notes, and attribution). A failing phone_test survives minimal; passing phone_test, say_it, and pattern_source are standard/full detail. Shapes the RESPONSE only, never what is generated, persisted, hashed for idempotency, or charged. | standard |
| idempotency_key | No | Caller-chosen replay key (any string, unique per intended effect). A repeat call with the SAME key returns the stored result and is NEVER charged twice; the same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| best | No | Plain mode: the highest-scoring entry. | |
| sets | No | Compare mode: per-set rankings and avg_score, keyed by your set names. | |
| winner | No | Compare mode: the winning set name. | |
| results | No | Plain mode: one scored entry per text, ranked. | |
| replayed | No | true when an idempotency_key replayed a stored result, so nothing was charged again. The credits_charged below is what the ORIGINAL call cost. | |
| request_id | No | Id of this call. Keep it: get_usage(request_id=...) itemises exactly what it charged, and it identifies the call in a support question. | |
| winner_summary | No | Compare mode: an honest reading of the win. The same heuristic scorer runs on every set, so this is a craft comparison, never a view prediction. | |
| credits_charged | No | Credits this call actually cost. | |
| credits_remaining | No | Your balance AFTER this charge. | |
| replayed_at_charge | No | true when the replay was detected at the charge boundary rather than up front; either way you are billed exactly once. |