Generate pixel art with SpriteForge
generateDestructive
Start an AI generation that spends the user's SpriteForge credits; the result is saved into their library. Unless the user has said to go ahead without asking, quote_generation first and get their OK on the price. max_cents is required: the job is refused if its price is higher (use the quoted price, or the user's budget). Returns a job_id - call get_job with it to wait for the result (most sprites take 20 s to a few minutes). Pass a request_id to make retries safe: the same request_id never starts or charges a second job.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cols | No | multiterrain: map width in tiles (default 16). | |
| name | No | Name for the new sprite (default: the artist names it). | |
| rows | No | multiterrain: map height in tiles (default 12). The whole map (cols x rows x tile size) must stay under about 160,000 pixels. | |
| tier | Yes | Model x effort. If the user hasn't chosen, choose for them from get_generation_options: Sonnet is the usual default up to 32px, Opus for 48-64px canvases, complex characters and final assets, Haiku for cheap small icons. Low/High variants trade price and time for care. | |
| type | Yes | What to make. single = one sprite. edit = AI-change a library sprite (asset_id + prompt). set = 1-8 sprites sharing one palette (subjects). animation = a looping animation (subject + frame_count; give asset_id to animate a library sprite). phased = one sprite drawn in 2-3 staged passes, the strongest choice for humanoids. terrain = top-down wall / transition / floor tiles. wang = a 16-tile autotile terrain set. platformer = 49 side-view ground tiles incl. slopes. multiterrain = a map of 2-6 terrains blending into each other (terrains, cols, rows). | |
| light | No | Light direction, e.g. "Top-left" (default: the project's). | |
| notes | No | Anything else the artist should know (max 500 characters). | |
| style | No | Art-style line for this generation, e.g. "chunky 16-bit fantasy" (on top of the project's style). | |
| width | No | Canvas width in pixels (1-64). Required except for edit and an animation of a library sprite. Tile types need width = height (the tile size). | |
| height | No | Canvas height in pixels (1-64). | |
| motion | No | animation: the movement, e.g. "walk cycle". Lines starting with a frame number direct that frame ("3: raise the sword"). | |
| passes | No | phased: 2 or 3 passes (default 3). | |
| prompt | No | edit: the change to make, e.g. "give him a red scarf". | |
| outline | No | "Dark-tinted" (optionally "Dark-tinted:<darkness 0-100>"), "Black" or "None" (default: the project's). | |
| subject | No | What to draw - single, phased, animation; the material for terrain (the wall) and wang; for platformer the ground surface on top, e.g. "lush grass". Concrete beats vague: subject, pose, colours, materials, mood. | |
| asset_id | No | edit: the library sprite to change (required). animation: a library sprite to animate - it becomes the loop's rest pose and sets the size. | |
| subjects | No | set: one short description per sprite. | |
| symmetry | No | "Off", or a note such as "horizontal" - mirrored after drawing. | |
| terrains | No | multiterrain: the terrains, e.g. grass, sand, water. | |
| max_cents | Yes | The most this generation may cost, in US cents. | |
| set_theme | No | set: the theme they share, e.g. "medieval armory icons". | |
| subject_b | No | terrain: the floor material (default: same as subject). platformer: the earth fill under the surface, e.g. "dark packed earth" (default: same as subject). | |
| aggression | No | animation: how hard poses are pushed (default normal). | |
| mask_cells | No | edit: limit the change to these [x,y] pixels; everything else is kept. | |
| open_ended | No | animation: a one-shot progression that doesn't loop back to the start. | |
| project_id | No | Project to generate into (default: the most recently used). Its style, description, light, outline and palette steer the result. | |
| references | No | Library sprites (up to 64px) that guide the result: role style (default) copies the look, subject copies what's depicted. Used by single, edit, set, phased, wang and multiterrain; each adds a small surcharge. | |
| request_id | No | Optional idempotency key, unique per intended generation. | |
| detail_tier | No | phased: a second tier for the passes after the silhouette, e.g. tier "Opus High" + detail_tier "Sonnet". | |
| frame_count | No | animation: drawn motion frames (1-8; the rest pose of an animated library sprite isn't counted). | |
| perspective | No | e.g. "side view", "3/4 top-down", "isometric". | |
| save_as_new | No | edit: save the result as a new sprite instead of updating the original (whose old version is otherwise kept in its history). | |
| terrain_map | No | multiterrain: rows x cols of indexes into terrains - a painted layout (default: the server paints one). | |
| lock_palette | No | Snap the result strictly onto the project palette. | |
| terrain_rules | No | multiterrain: optional edge-blend rules. | |
| animation_name | No | animation of a library sprite: the name it's saved under on that sprite (default "idle"). | |
| use_project_style | No | Apply the project's style and description (default true). | |
| use_project_palette | No | Steer toward the project's palette (default true). |