Create a character
create_characterPAID (standard 1K: 60 credits; 2K: 100; 4K: 150; premium models may differ). Generate a NEW character from a text prompt. This is the entry point for building art from nothing — call create_project first if the user has no project. Artwork is strictly text-free by default: no labels, captions, lettering or pseudo-text; only specific intrinsic writing explicitly requested by the user is permitted. IMAGE ONLY: it produces the character still, not animations. Animation is a separate explicit step (generate_character_animation for a walk cycle, generate_character_turn for the 360 rotation), because animating costs several times more and the user should choose it. BY DEFAULT it requests FOUR DESIGN VARIATIONS FOR THE SAME PRICE, matching the dashboard. Set generateFourVariations:false only when the user explicitly wants one character. gridRows:2 + gridCols:2 remain the legacy trigger for the same four-character mode; one image call is split by complete character silhouettes, never fixed cells. Four is the expected count, but any result with at least two separate silhouettes succeeds; every clearly separated full character is preserved whether two, three, or more than four are found. Zero or one means the sheet was not extractable and refunds. Show the user every result and let them pick. Returns { jobId, expectedCharacterCount } — poll get_job; on status:"done" its characterIds and characterPreviews tell you which characters exist and what they look like. gameType defaults from the project but can be overridden for this character. Use topdown for the Top-Down Angled character pipeline, including characters intended for isometric projects. Passing isometric is accepted as an alias and creates a topdown character because that is the measured working directional pipeline. The STORED CHARACTER gameType — not the project gameType — controls every later animation and whether a user-facing 360 turn is available. A topdown character inside a platformer project therefore keeps the top-down directional pipeline and supports generate_character_turn. DEFAULTS TO A COST PREVIEW — see the dryRun argument.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| style | No | Art-style override. Omit to inherit the project's style — usually correct, since a project should look consistent. | |
| 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 the character is, e.g. "a plague doctor with a lantern". Describe the subject, not the art style. | |
| gameType | No | Character perspective override. Omit to inherit the project. Use topdown for Top-Down Angled and isometric projects; isometric is mapped to topdown. The stored value controls later animation behavior and 360-turn eligibility. | |
| gridCols | No | Legacy equivalent of the default four-variation mode: set to 2 together with gridRows:2; extraction follows complete silhouettes. | |
| gridRows | No | Legacy equivalent of the default four-variation mode: set to 2 together with gridCols:2. This is not cut geometry. | |
| projectId | Yes | REQUIRED. The project the character belongs to — it supplies the default gameType and style. | |
| imageModel | No | Override the image model. Omit unless the user asked for a specific one. | |
| cameraAngle | No | Camera elevation in degrees — only meaningful for angled top-down projects. | |
| 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. | |
| characterImageSize | No | Aspect ratio of the generated image. Omit for the game-type default. | |
| referenceAssetUrls | No | URLs of existing images to steer the design. URLs only — base64 is rejected by the API. | |
| generateFourVariations | No | Defaults to true, matching the dashboard: one image call produces four design variations for the cost of one. Set false only when the user explicitly requests a single character. |