start_generate_job
Idempotent
Archived source-free writer job. Use research_hook_evidence instead. Always fails before a job, model, provider, storage, or billing work. Async execution cannot bypass source-video, view, link, and excerpt proof. 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=...). | |
| count | No | Hooks per topic, 1-25. With `topics` this applies to every subject, so the job's cost scales with count * len(topics). | |
| style | No | Voice/tone to match, <=200 chars. Honored as a real instruction by smart and research; on instant it only varies which deterministic template fillers are drawn, so it cannot change the voice there. Omit for the engine's default register. | |
| topic | No | Single subject for the job, 3-200 chars. Pass EITHER this or `topics`, never both and never neither. | |
| stance | No | Optional: what the creator is for or against, selling, or building, so hooks carry a real position instead of a neutral summary. | |
| topics | No | 1-20 subjects run as ONE job with ONE atomic charge; the result is the batch envelope instead of a single generate body. Pass EITHER this or `topic`. | |
| 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 |
| archetypes | No | Restrict generation to these archetype ids (see list_archetypes). Omit to let the engine spread across archetypes, which is what you want unless you are deliberately narrowing a deck. | |
| 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 |
|---|---|---|---|
| job_id | No | Pass this to get_job. | |
| status | No | Lifecycle state; 'queued' immediately after submit. | |
| warning | No | Present only alongside worker_alive:false; says what to do instead. | |
| replayed | No | true when an idempotency_key returned an EXISTING job rather than queuing a new one. Poll the returned job_id either way. | |
| requeued | No | true when an idempotent resubmit revived an existing job. | |
| expires_at | No | Earliest terminal-row prune cutoff, ISO-8601 UTC. Queued/running rows are not deleted solely because this time passed. | |
| status_url | No | REST URL for the same status (HTTP clients only). | |
| worker_alive | No | Present and FALSE only when no job worker will ever run this job. Then read `warning` and use generate_hooks instead of polling. | |
| 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. | |
| estimated_seconds | No | Queue-aware estimate of total time to a result. | |
| poll_after_seconds | No | Wait at least this long before the first get_job. Honor it. | |
| resolved_creator_profile | No | Exact immutable creator-profile binding used by this occurrence. Null/absent for inline or unprofiled generation. |