start_inference_job

{
  "properties": {
    "prompt": {
      "description": "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.",
      "type": "string"
    },
    "prompt_style": {
      "description": "Style id from list_available_styles (e.g. 'rd_fast__default', 'rd_pro__isometric', or a custom 'user__...' style).",
      "type": "string"
    },
    "width": {
      "description": "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).",
      "type": "integer"
    },
    "height": {
      "description": "Output height in pixels. Each style enforces its own limits; check list_available_styles or get_style_usage.",
      "type": "integer"
    },
    "num_images": {
      "default": 1,
      "description": "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.",
      "type": "integer"
    },
    "input_image": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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)."
    },
    "reference_images": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Extra per-inference guidance images (base64), only for styles where supports_reference_images is true. Not for defining custom styles."
    },
    "extra_input_image": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Second base64 input image for styles that use one (e.g. the second texture in rd_tile__tileset_advanced)."
    },
    "input_palette": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Base64 image of a color palette; output colors are constrained to it."
    },
    "strength": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "How strongly to change input_image, 0-1 (default 0.75). Lower values keep more of the original."
    },
    "extra_prompt": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Secondary prompt for styles that use one (e.g. the transition texture in advanced tilesets)."
    },
    "frames_duration": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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)."
    },
    "return_spritesheet": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "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_pre_palette": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Also return the render from before palette constraints were applied."
    },
    "return_non_bg_removed": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Also return the render from before background removal was applied."
    },
    "bypass_prompt_expansion": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Skip the automatic LLM prompt enrichment and use the prompt verbatim."
    },
    "include_downloadable_data": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Include extra structured assets when available (e.g. tileset atlas JSON, animation frame data)."
    },
    "upscale_output_factor": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Integer upscale factor for the output image; 1 returns the native pixel size."
    },
    "seed": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Seed for reproducible results; reuse the same seed to iterate on one composition."
    },
    "remove_bg": {
      "default": false,
      "description": "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.",
      "type": "boolean"
    },
    "tile_x": {
      "default": false,
      "description": "Make the result tile seamlessly on the horizontal axis.",
      "type": "boolean"
    },
    "tile_y": {
      "default": false,
      "description": "Make the result tile seamlessly on the vertical axis.",
      "type": "boolean"
    },
    "upload_outputs": {
      "default": true,
      "description": "Host outputs and return URLs in output_urls (recommended for MCP clients) instead of only base64 payloads.",
      "type": "boolean"
    },
    "timeout_seconds": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Read-timeout override in seconds for this call; increase for animations or large batches."
    },
    "rd_api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "RetroDiffusion API key (rdpk-...) for this call only; overrides session or header auth."
    }
  },
  "required": [
    "prompt",
    "prompt_style",
    "width",
    "height"
  ],
  "type": "object"
}