← All docs

API Art Maker

This is the API for generating art programmatically. It uses the same models and processes as the Art Maker tool in the app. See Art & Token Generation for what that tool does. Art generation is asynchronous. You submit a request and receive a request_id to poll until your image is ready.

This endpoint requires an API token. See API Authentication. For plan-level processing priority, see Pricing & Limits.

There's no daily cap on image generation. Paid plans get priority processing, so requests complete faster.

Generate art

POST /api/art_maker

Submit an art generation request. The same endpoint is used to poll for results by passing the request_id from a previous response.

  • Name
    mode
    Type
    string
    Description

    Required. "animation" to generate an animated sprite sheet, or "doodad" to generate static scene objects.

  • Name
    art_style
    Type
    string
    Description

    Required. One of: "Pixel Art", "Cartoon", "Vector Art", "Manga-Inspired", or "Custom". Matches the Style selector in the Art Maker tool.

  • Name
    custom_art_style
    Type
    string
    Description

    Required when art_style is "Custom". Describe the style freely, e.g. "8-bit NES" or "Cel Shaded toon".

  • Name
    perspective
    Type
    string
    Description

    Required. One of: "Top Down", "Isometric", or "Side View Scroller 2D". Matches the Perspective selector in the Art Maker tool.

  • Name
    animated_object
    Type
    string
    Description

    Required when mode is "animation". The character or object to animate, e.g. "knight" or "goblin". Matches the Animated Object field.

  • Name
    animated_action
    Type
    string
    Description

    Required when mode is "animation". The action to perform, e.g. "walking" or "casting a spell". Matches the Action field.

  • Name
    doodad_items
    Type
    string
    Description

    Required when mode is "doodad". The items to generate, e.g. "treasure chest, wooden table". Matches the Doodad Items field.

  • Name
    doodad_theme
    Type
    string
    Description

    Required when mode is "doodad". The visual theme, e.g. "high fantasy" or "steampunk". Matches the Theme field.

  • Name
    world_slug
    Type
    string
    Description

    Optional. Associate the generated image with a specific world by its slug. Defaults to your current world, or creates one if you have none.

  • Name
    request_id
    Type
    integer
    Description

    When polling: the request_id from a prior response. All other params are ignored when this is present.

On success, the initial request returns a request_id. Poll the same endpoint with that ID until status is "finished", at which point an image_url is included. We recommend a 30s polling interval; excessive polling may result in your requests being rate limited.

Possible status values: pending, in_progress, finished, failed, moderated.

Animation example

Step 1: Submit the request

curl -X POST https://www.finalparsec.com/api/art_maker \
  -H "Authorization: Token token={token}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "animation",
    "art_style": "Pixel Art",
    "perspective": "Top Down",
    "animated_object": "knight",
    "animated_action": "walking"
  }'

Response

{ "request_id": 42 }

Step 2: Poll for the result

curl -X POST https://www.finalparsec.com/api/art_maker \
  -H "Authorization: Token token={token}" \
  -H "Content-Type: application/json" \
  -d '{ "request_id": 42 }'

Response when finished

{
  "status": "finished",
  "image_url": "https://www.finalparsec.com/rails/active_storage/blobs/..."
}

Doodad example

Request

curl -X POST https://www.finalparsec.com/api/art_maker \
  -H "Authorization: Token token={token}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "doodad",
    "art_style": "Pixel Art",
    "perspective": "Top Down",
    "doodad_items": "treasure chest, wooden table",
    "doodad_theme": "high fantasy"
  }'