remix_hook
Archived source-free remix writer. Use research_hook_evidence instead. Always fails before rewriting, model, storage, or billing work. An extracted source hook cannot be replaced by generated or paraphrased copy. Errors: unauthorized; invalid_request with reason unsourced_hook_generation_archived.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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=...). | |
| text | No | The existing hook to rewrite, 3-300 chars. Its subject is kept; only the angle moves to target_archetype. Pass this OR `hook_id`, never both and never neither. | |
| count | No | Archived compatibility count, 1-5. Remix fails before work or customer charge. | |
| topic | No | The subject the hook was written FOR, scored as on score_hook: the verbatim-echo penalty only fires when the scorer is told the topic, so a hook (or a variant) that repeats its own subject scores up to 8 points higher without it and the rank order of the pack can differ. Only needed with `text`: a remix by `hook_id` reads the topic off the hook you bought. Sending both is fine when they are equal and a disagreement is a typed invalid_request rather than a silent winner. Omit for unchanged behaviour. | |
| 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. | |
| hook_id | No | Remix a hook you ALREADY bought, by the id a generate/batch/remix response returned (also listed by list_hooks): the stored text is looked up for you, so you do not have to carry it back. Account-scoped, so an unknown or foreign id is the same not_found get_hook returns. Pass this OR `text`, never both and never neither. | |
| platform | No | The platform whose SCORING WINDOW grades these variants, as on generate_hooks and score_hook: LinkedIn's ideal hook length is 10-18 words against 8-14 elsewhere, so it moves both score.total and the rank order. Each variant's total is then reproducible through score_hook with the SAME platform, and the scale used is echoed back as `platform`. Omit for tiktok (unchanged behaviour). | |
| archetype | No | Alias for `target_archetype`, spelled the way every hook object in every response spells it. Send either one; sending both is fine only if they are equal, and a disagreement is a typed invalid_request rather than a silent winner. | |
| 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. | |
| target_archetype | No | Archetype id to rewrite INTO (see list_archetypes for ids and their psychology). `archetype` is an accepted alias for this argument; one of the two is required, there is no default angle. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Why these rewrites fit the target archetype, or null. | |
| remixes | No | The variants: {id, text, archetype, score, rank}. Billed per variant RETURNED, so this can be shorter than count. | |
| original | No | {text, score} of what you passed in. | |
| platform | No | The platform scoring window every total above was produced on. Score a variant through score_hook with this SAME platform to reproduce its number; a different window gives a different total and a different rank. null when the request named none, which means the tiktok default. | |
| 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. | |
| topic_core | No | The subject the remixer preserved from the original. | |
| llm_fallback | No | true when the LLM remixer was unavailable and the deterministic one ran; llm_fallback_reason says why. You are billed for what RAN. | |
| remix_engine | No | Which remixer produced the variants. | |
| credits_charged | No | Credits this call actually cost. | |
| score_disclaimer | No | The honest limits of the score attached above. | |
| 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. | |
| llm_fallback_reason | No | Why the fallback happened, or null. |