expand_environment
ChatGPTFill in what one view of a scene is missing: the place is rebuilt with a new image generated from that camera, and the scene's file is replaced by the better one. COSTS 3 CREDITS and takes about ten seconds; returns a task id, not the finished scene. Takes a viewId from suggest_environment_views and nothing else - there is no way to aim a fill by hand here, on purpose, because a pose nobody has looked at is a generation spent on nowhere. ONE AT A TIME: a scene takes one fill at a time and the next is refused until this one lands. After it lands the place has been searched again, so every id from before is refused - call suggest_environment_views for the new list, and keep filling until it comes back empty.
generate_character
ChatGPTGenerate a 3D character from 1-5 photographs of one person OR from a text description (prompt). With a prompt, PINOC generates its own source image first; everything after that is identical, same cost, same result shape. This COSTS CREDITS (6 from one photo or a prompt and 5 from several, which are used as the views; with refine set to true, 10, reference views always included) and takes minutes. Returns a task id immediately and does not wait; poll it with wait_for_tasks. The result is a rigged Gaussian-splat bundle that plays the motion clips from the other tools. If the user ATTACHED photographs to the conversation, pass them as imageFiles and nothing else is needed. Only when you hold files the client cannot attach: upload them with prepare_upload and pass the resulting uploadKeys.
generate_environment
ChatGPTGenerate a SCENE - a place a character can stand in - from a description, a photograph, or a panorama the user already has. COSTS CREDITS: 5 to build it, and then PINOC improves the scene on its own - up to 2 automatic expand passes at 3 each, so a scene settles at UP TO 11. The expands are a CEILING, not a certainty: each pass searches the finished scene first, and a pass that finds nothing worth filling submits nothing and is charged nothing. THE SCENE ITSELF COMES BACK QUICKLY - roughly 10 to 30 seconds - and the expand passes land over the couple of minutes after that, so a scene that already reads as ready keeps improving for a short while. Returns a task id immediately; poll it with wait_for_tasks using kind "environment". IF THE USER HAS AN EQUIRECTANGULAR PANORAMA, hand it over as a panorama rather than as a reference: that path skips synthesis entirely and reconstructs what they actually have, which is both faster and far more faithful. A reference photograph GUIDES a new panorama rather than being used as one, AND NEEDS NO PROMPT: leave the prompt out and the photograph is described for you, which is the right call when the user handed over a picture rather than words. THE AUTOMATIC PASSES ARE A CEILING OF 2 AND NOT THE END OF IT: suggest_environment_views then says whether anything is still worth filling and expand_environment fills a view you choose, for as long as the user wants. IF YOU INTEND TO FILL THE PLACE YOURSELF, pass autoExpand false - the scene then arrives raw, sooner and for 5, and every fill is one you aimed instead of two aimed by a search nobody looked at. The scene can also be previewed and expanded by hand in the PINOC web app (https://viggle.ai/pinoc/app). If the user ATTACHED a panorama to the conversation, pass it as panoramaFile and nothing else is needed; an ordinary photograph they attached goes in referenceImageFile. Only when you hold a file the client cannot attach: call prepare_upload, run the curl it returns, and pass the resulting key as panoramaUploadKey or referenceUploadKey.
generate_motion
ChatGPTGenerate a NEW animation clip from a text description. COSTS CREDITS (1 per second of clip) and takes minutes. Call list_motion_library first and only come here when nothing in it fits - a clip that is nearly right is worse than a generated one that is right, but a library clip that IS right is free. Returns a task id immediately and does not wait; poll it with wait_for_tasks. Produces 4 samples of the prompt for one price. This makes a skeleton animation, never a body - use generate_character for that.
generate_motion_from_video
ChatGPTExtract a NEW animation clip from a video of one person moving - motion capture from footage, so the result is THAT performance rather than an interpretation of a description. COSTS CREDITS: 1 per second of footage extracted, the whole video unless trimmed. Takes minutes. Returns a task id immediately and does not wait; poll it with wait_for_tasks. The video must show one person with their body in frame; a clip with no person in it fails and is refunded. Nothing about the person's appearance is kept - this makes a skeleton animation, never a body. If the user ATTACHED the video to the conversation, pass it as videoFile and nothing else is needed. Only when you hold a file the client cannot attach: call prepare_upload, run the curl it returns, and pass the uploadKey here.
get_asset
ChatGPTLook up a motion or character by its asset id: name, visibility, prompt, and every downloadable format with a signed URL - without downloading anything. Some formats are listed as onDemand WITHOUT a URL, because PINOC builds them on request and keeps them after: a motion's splat-skeleton files. Every character tier it lists is already built. Never tell anyone a format is unavailable because it has no URL here. Pick by purpose: splat-skeleton-glb for the web Splat Engine, splat-skeleton-fbx for Unity (com.viggle.splat-engine 0.2.2+, face included), mixamo-glb or mixamo-fbx for other rigs and DCC tools; on a character high is the default and performance is for crowds and mobile. Use it to see what an asset carries before spending time and disk on a file that can run to tens of megabytes. Present the selected signed URL as a clickable download link. These URLs EXPIRE; call get_asset again if a fresh link is needed. For a download-link request, no shell download is required. Only save a local copy when the user requests it or a workflow needs the file. If local network access is blocked, still provide the returned link; a local fetch failure alone does not show that the user's download link is broken. Do not embed an expiring URL in a permanent page: that workflow needs a saved file. Holding more than one id? Call get_assets with all of them at once instead of calling this repeatedly.
get_assets
ChatGPTLook up SEVERAL assets by id in one call - the same thing get_asset does, for a list. Prefer it whenever you hold more than one id: it fetches them in parallel and says what opens each format ONCE for the whole batch rather than repeating it per asset. Up to 25 ids per call; more than that is refused, so split the list. An id that does not resolve fails on its own and the other assets are still returned - check errors for the misses. The URLs EXPIRE, same as get_asset's.
get_credit_balance
ChatGPTThe user's credit balance and what each paid tool costs. Free and instant. Call it before a generation when the balance matters - being refused mid-way through a multi-asset job is worse than knowing first - and to answer the user when they ask what something will cost.
list_motion_library
ChatGPTList PINOC's curated motion library - hand-cleaned animation clips that are FREE to use and land in seconds. Always call this BEFORE generating a motion: generating costs the user credits and takes minutes, while taking a library clip costs nothing. Returns every clip with its keywords; read the list and judge which one fits, since nothing here searches or ranks on your behalf.
list_my_characters
ChatGPTList Gaussian splat characters from the user's latest 50 character library entries, excluding uploaded meshes. Free, instant, no credits. Returns names, asset ids, and hasMore when older library entries exist.
list_my_environments
ChatGPTList the scenes - the PLACES - this user has made. Free, no credits. A scene is a Gaussian-splat reconstruction of a location that a character can be put in; it is the third asset kind beside motions and characters. Each entry says which way DOWN is in its file (downAxis), which the two eras of this pipeline disagree about.
list_my_motions
ChatGPTList up to 50 of the user's latest motion library entries - the same thing that list_motion_library does, for the user's own motion library. Free, instant, no credits. Returns names, asset ids, keywords, and hasMore when older entries exist
prepare_upload
ChatGPTGet a presigned URL to upload ONE local video or image so a remote PINOC server can use it. Free, instant, no credits. Returns an uploadKey plus a curl command; run the command from your shell, then pass the uploadKey to the generate tool. The upload URL expires in 6 hours; uploaded files are available for 1 day.
search_library
ChatGPTSemantic search over the user's own motions, characters and scenes, by name or description, e.g. "red knight", "sad walk" or "pine forest". Free, no credits. Prefer this over list_my_motions / list_my_characters / list_my_environments when looking for something specific. A matched scene comes back with its splat file and the facts needed to place it, so it needs no second call.
suggest_environment_views
ChatGPTList the camera views worth filling in one of the user's scenes, best first, each with the share of its frame that is MISSING and the share that is too BLURRED to look at. FREE, no credits, and it changes nothing - but the first call on a scene takes a few seconds, because it is the call that measures it. A scene is reconstructed from one viewpoint, so whatever that point could not see is a hole the moment a camera moves; this is where those holes are. Call it before expand_environment, always: it is the only way to aim a fill here, and the ids it prints are what expand_environment takes. AN EMPTY ANSWER IS THE SUCCESS CONDITION, not a failure - only a view worth a generation is kept at all, so nothing on offer means the place is good enough and you should stop.
take_library_motion
ChatGPTTake one named clip from the curated motion library. Free, instant, no credits, no task to poll - it returns an asset id you can download immediately. A name that does not match FAILS and lists near misses rather than generating something similar: a typo should cost you a second, not a paid generation. Taking more than one clip? Call take_library_motions with all the names at once instead of calling this repeatedly.
take_library_motions
ChatGPTTake SEVERAL named clips from the curated motion library in one call - the same thing take_library_motion does, for a list. Prefer it whenever you want more than one clip: it reads the catalogue once instead of once per name, and says the format guidance once instead of once per clip. Up to 25 names per call; more than that is refused, so split the list. A name that does not match fails on its own and the other clips are still returned - check errors for the misses. Free, instant, no credits.
wait_for_tasks
ChatGPTPoll one or more generation tasks for a bounded time and report where they got to. Use this instead of writing your own poll loop or sleeping. It returns within timeoutSeconds with whatever has happened by then. A character or a motion takes MINUTES, so several calls in a row is the normal shape there; a scene is back in roughly 10-30 s and usually needs one. A task still running is never a reason to start another one. Reports each task as ready (with the asset ids it produced), running, or failed (with the error, and those credits already refunded). Also waits on an on-demand export build: pass kind "export" with the exportId that get_asset or download_asset returned; ready reports the built files' URLs. For a ready generation: Call get_asset with the returned assetPublicId (not the taskId), then present the selected signed URL as a clickable download link. This PINOC server is remote: download_asset cannot write to your disk, and a download-link request does not require a local file.