Hypernatural

Ingest uploaded local images into the team's image library. This is the path for scene / location / background / mood / style images — the common case for 'use these images in a video': ingest them here, then pass the resulting assets to create_composition as named static_image_references (do NOT turn generic imagery into products via create_reference_object). Use @-mentions to refer to them inside prompts. Pass the {filename, upload_key} pairs from get_image_upload_urls or upload_file_from_remote_url. For get_image_upload_urls, the PUT of each file's bytes to its upload_url MUST have succeeded first; an upload_key with no uploaded bytes fails ingest. Runs asynchronously: returns a job_id — poll get_job until complete, then check result.errors (files listed there are not ready and are absent from result.assets — fix and retry) and pass each result.assets entry's asset_id with a descriptive name to create_composition as a static_image_reference. Each ingested asset is also analyzed, and its result.assets entry carries the classification category/description — use them to pick fitting reference names.

create_asset

Get a single async job's status and result by job_id. Poll this after any tool that returns a job_id until status is 'complete' (or 'failed'), then read its result. A 'complete' job can still carry per-file failures in result.errors — check it and error_message before proceeding, and follow any guidance the payload includes. A complete export_composition job's result carries the MP4 download_url and a watch_url.

get_job

Create a team-level character through the generation pipeline (vision analysis, attribute extraction, canonical portrait). Provide EXACTLY ONE of `upload_key` (a single source image from get_image_upload_urls or upload_file_from_remote_url) or `bio` (text to generate a portrait from). Runs in the background; returns a job_id — poll get_job until it reports complete, and only then is the character's name @mentionable. Do not send a create_composition / send_chat_message that uses that @Name in the same turn as this call; it fails on the unresolved @Name.

create_character

Create a reusable team reference for ONE specific product or logo that must look identical every time it appears in a video, from one or more images (upload_keys from get_image_upload_urls or upload_file_from_remote_url, and/or asset_ids from list_assets). This is NOT for generic scene / location / background / mood imagery — those are static references: ingest them with create_asset and pass named static_image_references to create_composition instead. An image is REQUIRED — products/logos cannot be generated from text (unlike create_character, which takes a bio). If the user has not given you an image file, do NOT call this — ask them for one, or skip the reference and describe the product in the composition prompt text. Runs in the background; returns a job_id — poll get_job until status is 'complete', then read result.reference_id (and result.images for the ingested asset_ids). Only once that job is complete is its name @mentionable — do not send a create_composition / send_chat_message using that @Name in the same turn as this call; it fails on the unresolved @Name.

create_reference_object

Create a composition, optionally starting background planning with a prompt. The prompt should be a shot list in the user's own words, or one they explicitly approved — if you drafted or expanded it yourself, show it to the user and get approval BEFORE calling this. Use exact @Names for reusable entities and static_image_references for generic imagery; every reference's @Name must appear in the prompt, and inserting those @Names into the user's shots is required binding, not a rewrite that needs approval. An @Name that matches no library entity errors — and an entity does not exist until its creation job reports complete, so NEVER call this in the same message as the create_character / create_reference_object it depends on; poll get_job to complete first. Follow the returned polling delay and next_action.

create_composition

Render a finished composition to an MP4 that you can download. Use it once get_composition's next_action is done: call it when the user asked for the video itself (a file, a download, something to post or send), and offer it otherwise. Returns a job_id at once; poll get_job every ~10 seconds (usually done within a minute) until status is complete, then hand over result.download_url and result.watch_url, which expire at result.expires_time. Until then the export is rendering, not ready. resolution: omit it for the best the plan allows (1080p on paid plans, SD on free). 720p and 1080p need a paid plan; on a free plan they return an upgrade message to relay with an offer of SD, which is a plan limit, not a bug to report. The aspect ratio is the composition's render_size and exporting cannot change it. Exports cost no credits. While the composition is still generating, or before it has any images, this refuses and says what to do first.

export_composition

Mint presigned upload URLs for one or more LOCAL image files. Returns an upload_url + upload_key per file; PUT each file's bytes to its url, then use the upload_key directly in a create tool (e.g. create_reference_object, create_character) — or pass {filename, upload_key} pairs to create_asset only if you want them saved to the team library on their own. If a PUT fails, do not retry it — use upload_file_from_remote_url instead.

get_image_upload_urls

Get a composition's current shots, voiceover, settings, latest reply, actions, and next_action. Poll after creating or messaging. Always follow next_action.guidance.

get_composition

List characters the user can feature: the team's own characters first (most recent first), then Hypernatural's built-in system characters. Only ready-to-use characters are returned — ones whose portrait is still being generated are omitted. Each has a name (use it as an @mention in prompts) and a short description — use the descriptions when picking who to cast. Check here before creating a new character so you reuse an existing one instead of duplicating it.

list_characters

List the team's image library (most recent first). Returns each asset's asset_id, filename, dimensions, classification category/description, and whether it is ready for use in static_image_references.

list_assets