generate_hooks_batch
Archived source-free batch writer. Use research_hook_evidence instead. Always fails before model, template, provider, job, storage, or billing work. It cannot pad research supply with generated or paraphrased hooks. Errors: unauthorized; invalid_request with reason unsourced_hook_generation_archived.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Generation engine and therefore the price: instant (0 base + 1/hook, deterministic templates, sub-second), smart (0 + 2/hook, one LLM call, seconds), research (10 + 4/hook, brief->draft->judge, tens of seconds). Aliases: template|off|quick->instant, llm|on|fast->smart, search|deep|deep_research->research. Omit (or auto) -> smart when an LLM key is configured, else instant. | |
| 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=...). | |
| stance | No | Optional: what the creator is for or against, selling, or building, so hooks carry a real position instead of a neutral summary. | |
| 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. | |
| clarify | No | Request-sufficiency behaviour: 'ask' returns ONLY clarifying questions (uncharged, nothing generated) - relay them to your human, then re-submit enriched; 'auto' (default) proceeds and the research envelope carries the questions and proposed assumptions as observations; they do not currently change retrieval or writer prompts. 'off' skips the check. Batch and jobs accept only 'auto'/'off'. | |
| creator | No | Optional: who is speaking, free text ('wedding videographer, 40k followers, I talk to camera over b-roll of my shoots'). The more the engine knows about the creator, the more the hooks are theirs rather than a generic narrator's. | |
| audience | No | Optional: who watches ('engaged couples budgeting'). Aims every hook at a real audience instead of an assumed one. | |
| language | No | The language the hooks are WRITTEN in, and the market their evidence is scraped from. en (default) | fr | es | ar (Modern Standard Arabic) | ary (Moroccan Darija, Arabic script). NOT a translation layer: the brief researches the topic as it is actually discussed in that language, the platform evidence is fetched from that language's region with transcripts in that language, and the judge scores register in it rather than against English. Omit for English. Same price in every language. | |
| platform | No | Target platform, which selects the length/format conventions the hooks are written and scored against. Defaults to tiktok when omitted. | tiktok |
| requests | Yes | 1-20 items, each {topic, count?, archetypes?, style?}. Per-item `mode` is rejected: mode, tags, verbosity and idempotency_key are set ONCE for the whole batch. Unknown item keys are invalid_request. | |
| 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. | |
| requested_market | No | Caller-declared target market or locality, up to 100 characters. This is not inferred or verified and does not override today's language-derived evidence region. Recorded in commission identity and retained async-job snapshots. It does not change retrieval, prompts, scoring, pricing, or generated text yet. | |
| requested_dialect | No | Caller-declared desired dialect or register, up to 100 characters. This is not an observed-language or classifier result. Recorded in commission identity and retained async-job snapshots. It does not change retrieval, prompts, scoring, pricing, or generated text yet. | |
| creator_profile_id | No | Exact owned profile id. Send with creator_profile_version and without inline creator/audience/stance/first_person_facts. | |
| first_person_facts | No | Optional: facts TRUE of this creator that hooks may assert first-person ('I have filmed 200+ weddings'). The ONLY sanctioned source of personal claims; without it, hooks never invent a biography. | |
| footage_constraints | No | Up to 10 caller-declared filming or edit constraints, each up to 200 characters. Recorded in commission identity and retained async-job snapshots. It does not change retrieval, prompts, scoring, pricing, or generated text yet. | |
| delivery_constraints | No | Desired spoken performance or cadence, up to 300 characters, distinct from the broader style/voice field. Recorded in commission identity and retained async-job snapshots. It does not change retrieval, prompts, scoring, pricing, or generated text yet. | |
| desired_viewer_action | No | What the viewer should do after hearing the hook, such as keep watching, comment, or reconsider a belief, up to 300 characters. Recorded in commission identity and retained async-job snapshots. It does not change retrieval, prompts, scoring, pricing, or generated text yet. | |
| creator_profile_version | No | Exact immutable profile version paired with creator_profile_id. | |
| hook_length_constraints | No | Desired spoken-hook length, up to 200 characters, for example '8-12 words' or 'under 6 seconds'. Recorded in commission identity and retained async-job snapshots. It does not change retrieval, prompts, scoring, pricing, or generated text yet. | |
| desired_audience_feeling | No | How the audience should feel immediately after the hook, such as understood, curious, or challenged, up to 300 characters. Recorded in commission identity and retained async-job snapshots. It does not change retrieval, prompts, scoring, pricing, or generated text yet. | |
| requested_content_format | No | Desired production format: solo_talking_head, podcast, interview, yapping_monologue, voiceover, skit, montage, or other. This is a request, not a claim about any retrieved source. Recorded in commission identity and retained async-job snapshots. It does not change retrieval, prompts, scoring, pricing, or generated text yet. | |
| caller_confirmed_constraints | No | Up to 10 caller-confirmed request constraints from a prior clarification round, each up to 300 characters. Runtime-generated questions and model assumptions are execution receipts, not copied here or treated as approved automatically. Recorded in commission identity and retained async-job snapshots. It does not change retrieval, prompts, scoring, pricing, or generated text yet. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hint | No | auto_job path only: poll instruction. | |
| engine | No | The generator implementation, or 'mixed' when items diverged. | |
| job_id | No | auto_job path only: poll it with get_job or wait_for_job. | |
| status | No | auto_job path only: the job lifecycle state. | |
| timing | No | {latency_ms} for the whole batch. | |
| results | No | One entry per item, in request order: {topic, hooks, pricing_mode, price_per_hook, base_price, credits, grounding_refund, timing, judge_fallback_reason, count_requested, shortfall, reason, research}. Every per-item key means exactly what the same key means on a single generate. Hook ids live at results[i].hooks[j].id. At standard/full, a judge-ranked smart hook may also carry {shape, phone_test, say_it}; a judge-ranked research hook carries receipts {persona, shape, phone_test, say_it, pattern_source}. pattern_source is null when no measured opener was attributed, otherwise its nested provenance is the authoritative actual platform, source surface, transcript method, language, route, media, and origin-time record. Minimal keeps persona and shape, plus phone_test only when it is the warning value 'fail'. | |
| auto_job | No | Present and true when this key already owns the exact async multi-topic job. On this path `results` is absent; poll job_id/status_url instead. | |
| 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. | |
| requeued | No | auto_job path only: whether the existing job was requeued. | |
| mode_used | No | The engine that ran, after aliases and auto were resolved; 'mixed' when items diverged. | |
| base_price | No | Fixed part of the charge, or null when pricing_mode is mixed. | |
| expires_at | No | auto_job path only: earliest terminal-row prune cutoff, ISO-8601 UTC. | |
| rank_basis | No | verbosity=minimal ONLY, alongside degraded_stages: hoisted out of `research`; what the served ORDER means (llm_judge | judge_order_no_scores | heuristic | unranked). At standard/full read research.rank_basis. | |
| 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. | |
| status_url | No | auto_job path only: REST URL for the same job. | |
| degraded_any | No | Wider signal than judge_fallback_any: true when any item ran off-tier for any reason, including a partial stage that still delivered a full hook count. | |
| llm_fallback | No | true when ANY item fell back to a cheaper engine or a fallback provider. | |
| pricing_mode | No | The tier billed across the batch, or 'mixed' when items fell back to different engines. On 'mixed', base_price/price_per_hook are null and each results[i] carries its own. | |
| expected_wait | No | {mode, p50_ms, p90_ms, source} for the batch's tier. | |
| hook_instances | No | Immutable non-prose served-occurrence identities. Profile-bound queued/running work returns an empty list; a successful result returns one row per served hook. | |
| mode_requested | No | The mode string you sent, before alias/auto resolution. | |
| price_per_hook | No | Per-hook part of the charge, or null when pricing_mode is mixed. | |
| prompt_version | No | Prompt build used, for reproducibility. | |
| credits_charged | No | Credits this call actually cost. | |
| degraded_reason | No | verbosity=minimal ONLY, and only when non-null: hoisted out of `research` so the trimmed envelope still says WHY the run degraded. At standard/full read research.degraded_reason instead. | |
| degraded_stages | No | verbosity=minimal ONLY, and only when non-empty: hoisted out of `research`; which stages to blame. At standard/full read research.degraded_stages. | |
| score_disclaimer | No | The honest limits of the scores above. Absent at verbosity=minimal. | |
| credits_remaining | No | Your balance AFTER this charge. | |
| estimated_seconds | No | auto_job path only: queue-aware estimate of total time to a result. | |
| judge_fallback_any | No | true when at least one item's hooks are HEURISTIC-scale because its judge did not rank them. Then results[i].judge_fallback_reason says which, and you must not rank topics by comparing avg(score.total) across items. At verbosity=minimal this key appears only when true. | |
| poll_after_seconds | No | auto_job path only: wait at least this long before the first poll. | |
| 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 first such fallback happened, or null. | |
| resolved_creator_profile | No | Exact immutable creator-profile binding used by this occurrence. Null/absent for inline or unprofiled generation. |