Start Async Generation
start_inference_jobStart a generation as an async job (POST /v2/inferences with async=true) and return a task_id.
Recommended for advanced animations (rd_advanced_animation__*), other animation styles, and batches — they run for tens of seconds and can outlive a synchronous MCP call. Poll the returned task_id with get_inference_job roughly every 2-5 seconds.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"prompt": "<prompt>",
"prompt_style": "<prompt_style>",
"width": "<width>",
"height": "<height>"
},
"name": "start_inference_job"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | Seed for reproducible results; reuse the same seed to iterate on one composition. | |
| width | Yes | Output width in pixels. Each style enforces its own limits; check list_available_styles or get_style_usage. Genre-native sizes per item: Minecraft 16; items/icons/props 32-64; character sprites 16-48 retro or 96-128 showcase; tiles 16-32; portraits 96-128; full scenes 256 (RD Pro's max; 16:9 scenes = 256x144 — pixel art integer-upscales losslessly). | |
| height | Yes | Output height in pixels. Each style enforces its own limits; check list_available_styles or get_style_usage. | |
| prompt | Yes | Describe the SUBJECT only, richly and concretely ('a squat round flask of glowing crimson liquid, cork stopper, bright highlight on the upper-left rim' beats 'a potion'). Never write 'pixel art' — the selected style handles all rendering. For standalone assets, state a flat background color that contrasts the subject (default 'on a plain white background') and pair with remove_bg=true; never write 'transparent background' (that is remove_bg's job), and never leave the background unstated (it drifts to drab dark gray). Scenes instead describe their real environment. For rd_advanced_animation__rotate the prompt is only an optional hint describing the uploaded subject — a few words or an empty string. | |
| tile_x | No | Make the result tile seamlessly on the horizontal axis. | |
| tile_y | No | Make the result tile seamlessly on the vertical axis. | |
| strength | No | How strongly to change input_image, 0-1 (default 0.75). Lower values keep more of the original. | |
| remove_bg | No | Remove the background for transparent output. Use true for standalone assets and pair it with a stated contrasting background in the prompt ('on a plain white background') — removal works best on flat contrasting backdrops. Animations inherit the start frame's transparency automatically. | |
| num_images | No | How many images to generate in one batch; a batch produces varied takes of one prompt (the right way to get N distinct items as individually usable images — never pack N items into a single sheet/grid image unless a sheet IS the deliverable). Style-specific maximums apply. | |
| rd_api_key | No | RetroDiffusion API key (rdpk-...) for this call only; overrides session or header auth. | |
| input_image | No | Base64 PNG used as the main source image for edits, variations, tilesets, animations, or styles that require a starting frame. Raw base64 or a data URL. Send the NATIVE-resolution image: an upscaled display copy (e.g. a 96px sprite exported at 4x = 384px) exceeds style ranges and gets rejected — downscale to the true pixel grid first. For advanced animations the frame's dimensions must equal width/height, and sprites whose opaque pixels touch the canvas edge animate badly (pad onto a larger transparent canvas first, e.g. 48x48 content onto 64x64). | |
| extra_prompt | No | Secondary prompt for styles that use one (e.g. the transition texture in advanced tilesets). | |
| prompt_style | Yes | Style id from list_available_styles (e.g. 'rd_core__default', 'rd_pro__isometric', or a custom 'user__...' style). | |
| input_palette | No | Base64 image of a color palette; output colors are constrained to it. | |
| upload_outputs | No | Host outputs and return URLs in output_urls (recommended for MCP clients) instead of only base64 payloads. | |
| frames_duration | No | Animation frame count for animation styles: 4, 6, 8, 10, 12, or 16. Pick deliberately: 8 is the sweet spot for loops (walking, idle), 6 for a snappy single action, 10-12 for flowing ambient motion. Ignored by rd_advanced_animation__rotate (always 8 views). | |
| timeout_seconds | No | Read-timeout override in seconds for this call; increase for animations or large batches. | |
| reference_images | No | Extra per-inference guidance images (base64), only for styles where supports_reference_images is true. Not for defining custom styles. | |
| extra_input_image | No | Second base64 input image for styles that use one (e.g. the second texture in rd_tile__tileset_advanced). | |
| return_pre_palette | No | Also return the render from before palette constraints were applied. | |
| return_spritesheet | No | For animation styles: return a PNG sprite sheet instead of a GIF (for rd_advanced_animation__rotate, the 3x3 direction sheet whose views face the center). | |
| return_non_bg_removed | No | Also return the render from before background removal was applied. | |
| upscale_output_factor | No | Integer upscale factor for the output image; 1 returns the native pixel size. | |
| bypass_prompt_expansion | No | Skip the automatic LLM prompt enrichment and use the prompt verbatim. | |
| include_downloadable_data | No | Include extra structured assets when available (e.g. tileset atlas JSON, animation frame data). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||