Create an asset
create_assetPAID (one image call). Creates a NEW asset from a prompt in any of the six types. The default dry run now returns a strictly text-free artwork brief: no captions, labels, lettering, digits or pseudo-writing unless the user explicitly requests specific intrinsic writing on an object. Environment Kit overlays must not have die-cut sticker borders or backing. It returns both the exact semantic plan (plan.preview, item count/list, camera, project-derived look) and planToken. SHOW that preview to the user. A real call requires the same request plus that planToken; changing the prompt, project settings, type, model, or output settings invalidates it and requires a new dry run. Standard models cost 60 credits at 1K, 100 at 2K, or 150 at 4K per image/sheet, including automatic background removal and fallback; use the dry-run quote. Object (assetType: "static", formerly Static Asset) defaults to four separately editable design alternatives of the requested object, not a state sequence. All four share project style and one of five world cameras; explicitly requested flat inventory/UI icons use front/content_type. Explicit one remains supported. Clean cutouts omit incidental scenery and sticker backing, not real outlines or integral bases. Never automatically reroute asset types. Object States (staged) is one object in exactly four ordered states on a 2×2 sheet; no filler or automatic animation. Preserve identity, shared physical scale and real size changes. Object Collection (tileset) and Environment Kit (terrain) propose 1–25 useful pieces when no count is specified; explicit lists/counts are preserved without grid-filler extras. Object Collections contain independently editable mixed items, variants, matching families, icons/symbols or cards/tokens—not automatic animation stages. World props follow project camera; flat icons/cards use front-facing presentation even in isometric projects, unless the user explicitly requests another view. Preserve requested intrinsic symbols/text, never external captions. Material uses one transparent 1K donor sheet through the configured Material provider route and yields two platformer fill+surface families or four topdown/isometric fills, and background to one image when the user did not specify a count. Explicit counts/semantic sets override defaults, and non-square counts for other grid types are filled to the smallest supported 2×2–5×5 square with disclosed supplemental items. Environment Kit camera follows the project; request a different camera explicitly in the prompt. Kit pieces are placed over Materials, not used as deterministic terrain donors or guaranteed seamless brushes. projectId is REQUIRED — the project supplies gameType, which decides how the art is drawn, and keeps the asset findable in the web app. A fan-out create returns one jobId — the asset ids appear in get_job as gridAssetIds once the job finishes. Environment Kit has NO per-tile edit path: revising a terrain asset regenerates the whole sheet. DEFAULTS TO A PLAN + COST PREVIEW — see dryRun. Returns { jobId, assetId } — poll get_job, then call get_asset. Generated atlases are cut by logical foreground objects, not trusted row geometry; get_asset exposes extraction status/warnings.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Display name (defaults to the prompt). | |
| slug | No | Stable handle used by every /assets/:id call ([a-z0-9-]). Auto-derived from the name when omitted. | |
| style | No | Override the project's art style for this asset only. | |
| bgType | No | REQUIRED for assetType "background" — prefer scene (one opaque full scene), distant_backdrop (one opaque far vista), depth_layer (one scenery layer with transparent gaps), or foreground_overlay (transparent edge framing). All four support every camera. One image per call, no automatic parallax pack, collision/navigation or verified seamless repeat. Angled top-down and strict overhead stay distinct; atmospheric vistas need no forced isometric geometry. Preserve project style. Legacy values remain view-specific: platformer → parallax_far/parallax_mid/parallax_near/platform_scene/static_backdrop/scrolling_backdrop; topdown + topdown_overhead → ground_fill/overhead_map/functional_map/scrolling_floor/parallax_underlay; isometric → iso_ground/iso_scene/iso_far/iso_platform_surface; point_and_click → full_scene/room_stage/parallax_strip/platform_scene_front/vista_backdrop. A mismatch, or omitting it, is rejected with 400. Each sub-type runs a different tuned prompt, so this decides what KIND of image you get — a far parallax sky and a functional platform scene are not interchangeable. Ask the user which layer they want if their request does not make it obvious. | |
| dryRun | No | DEFAULTS TO TRUE. While true this returns only a cost quote ({ estimatedCredits, balance, spendCapDaily, spentLast24h, capRemaining }) and executes nothing. Show the user estimatedCredits, then ask a normal confirmation question. Prefer the client's native question UI with Approve / Decline / Discuss choices when available; otherwise accept any unambiguous conversational approval. Never require a fixed phrase or ask the user to type a magic word. Only after approval, re-call with dryRun:false to actually spend. | |
| prompt | Yes | What to generate. Describe the subject, not the art style — style comes from the project. | |
| gridCols | No | Legacy compatibility only; the confirmed plan decides columns. | |
| gridRows | No | Legacy compatibility only. The confirmed semantic plan owns layout. Object Collection and Environment Kit never add items just to fill cells. | |
| tileSize | No | TERRAIN only — output tile size in px (64, 128 or 256). | |
| assetType | Yes | `static` = Object (formerly Static Asset), four separately editable design alternatives by default (explicit one supported); each may also be animated; tileset = Object Collection, one coordinated set of independently editable items; staged = one subject in N progressive stages (the input animate_asset expects); background = scenery, never a game object; terrain = Environment Kit, individually placed props, surface details or connecting modules; texture = Terrain Material, brushable fill/surface donors (wire names unchanged; editor topology is deterministic). | |
| planToken | No | REQUIRED when dryRun=false. Copy unchanged from the immediately preceding dry-run response. | |
| projectId | Yes | REQUIRED. Owning project (create_project / list_projects). Supplies gameType + default style. | |
| bgViewType | No | BACKGROUND only — which view the background is drawn for. Defaults to the project gameType. | |
| imageModel | No | Override the image model for non-Material assets. Materials use the server-owned MATERIAL_IMAGE_PRIMARY provider route. | |
| runtimeUse | No | OBJECT only (`assetType: "static"`; formerly Static Asset). Material is locked to deterministic brush rendering server-side. Declares how the art is meant to be rendered — particle_emitter, deformable_strip, nine_slice or shader_effect — which changes the prompt AND the export metadata. Anything other than plain_image on a non-Object type is rejected. path_follow remains accepted for legacy clients but must not be used for new assets; path motion is configured per placement in the level editor. It can also be set later with set_asset_runtime_intent, for free. | |
| aspectRatio | No | BACKGROUND only — OPTIONAL, and best left unset: the server applies the recommended ratio for the chosen sub-type (e.g. 21:9 for a parallax layer, 1:1 for a ground fill), which is what the web wizard preselects. Only pass a value if the user asked for a specific shape. 21:9 is the widest and 9:16 the tallest the image model accepts. | |
| perspective | No | Environment Kit only — legacy three-value camera override. Omit to retain the project’s distinct side, angled top-down, overhead, isometric or adventure camera; request finer camera changes in the prompt. | |
| textureKind | No | LEGACY compatibility only. New Materials derive platformer/topdown/isometric projection from the project gameType; this value does not change their donor contract. | |
| idempotencyKey | No | Optional Idempotency-Key for the real (dryRun:false) call. Omit and one is minted per call. Reuse the SAME value when retrying a call that failed with ENTITY_BUSY / 402 / 429 so the retry cannot double-dispatch. | |
| targetTileSize | No | Output tile side in px (16-512). | |
| referenceAssetUrls | No | Up to 4 reference image URLs to condition the generation. URLs only — raw base64 is rejected on this surface. | |
| backgroundResolution | No | BACKGROUND only — output tier (default 2K). 4K costs more. |