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 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. Static defaults to four sprites, tileset to 16 items, staged to four stages, terrain to 25 pieces, texture to four samples, and background to one image when the user did not specify a count. Explicit counts/semantic sets override defaults, and non-square counts are filled to the smallest supported 2×2–5×5 square with disclosed supplemental items. 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. Terrain 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" — the sub-type, and it must be legal for the view: 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 and get an explicit yes for that amount, THEN 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. New generations derive a supported square layout from the confirmed semantic plan. | |
| tileSize | No | TERRAIN only — output tile size in px (64, 128 or 256). | |
| assetType | Yes | static = one sprite/prop; tileset = a grid of related tiles; staged = one subject in N progressive stages (the input animate_asset expects); background = scenery, never a game object; terrain = auto-tiling 3×3 ground sheet; texture = seamless tileable material. | |
| 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. | |
| runtimeUse | No | STATIC only (texture is locked to repeat_fill server-side). Declares how the art is meant to be rendered — particle_emitter, deformable_strip, nine_slice, shader_effect, path_follow — which changes the prompt AND the export metadata. Anything other than plain_image on a non-static type is rejected. 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 | TERRAIN only — camera perspective. Defaults from the project gameType. | |
| textureKind | No | TEXTURE only — fill = uniform material tiling in all directions (walls/floors/ground); strip = has a directional top surface and repeats left↔right (platformer platforms). Defaults per gameType. Created cells are RAW: read metadata.seamless.seamMetric.pass from get_asset and only pay fix_asset_seams for the ones that fail. | |
| 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. |