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.

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

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

List the team's product/logo references, most recent first. Optionally filter by kind. Each has a name (use it as an @mention in prompts), kind, and a short description.

list_reference_objects