Poses API | AutoSprite

Generate, upload, or save spritesheet frames as character poses to use as first or last frames in animations.

Poses are character images you can use as the first frame or last frame of an animation to control exactly how it starts or ends. Generate one from a text prompt, upload your own image, or save a frame of a spritesheet you already made.

List Poses

GET /api/v1/characters/:characterId/poses

List all poses for a character, including built-in and custom-generated poses.

Example

curl https://www.autosprite.io/api/v1/characters/char_abc123/poses \
  -H "x-api-key: vspk_your_key_here"

Response

{
  "poses": [
    {
      "id": "pose_001",
      "label": "Original",
      "imageUrl": "https://... (presigned URL)",
      "prompt": null,
      "sourceType": "upload",
      "presetId": null,
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": "pose_002",
      "label": "Sword Raised",
      "imageUrl": "https://... (presigned URL)",
      "prompt": "character holding sword above head",
      "sourceType": "generate",
      "presetId": null,
      "createdAt": "2025-01-15T11:00:00Z"
    }
  ]
}

Generate a Pose

POST /api/v1/characters/:characterId/poses

Generate a new custom pose using AI. The pose preserves the character's appearance while depicting them in the described position.

Cost: 5 credits.

Request Body

Field	Type	Required	Description
`prompt`	string	Yes	Description of the pose (max 600 chars)
`name`	string	No	Display name for the pose (max 40 chars)

Example

curl -X POST https://www.autosprite.io/api/v1/characters/char_abc123/poses \
  -H "x-api-key: vspk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "character holding sword above head in attack stance",
    "name": "Sword Raised"
  }'

Response

Status: 202 Accepted

{
  "jobId": "job_pose_001"
}

Poll the Jobs API with this jobId to check when the pose is ready.

Errors

Status	Code	When
400	Various	Missing or invalid prompt
402	`INSUFFICIENT_CREDITS`	Not enough credits
403	`PLAN_REQUIRED`	Paid subscription required
400	`INVALID_REQUEST`	Character not found

Upload a Pose

POST /api/v1/characters/:characterId/poses

Save your own image as a pose. Send it as multipart/form-data.

Cost: Free.

Form Fields

Field	Type	Required	Description
`image`	file	Yes	PNG, JPEG or WebP, max 4 MB
`name`	string	No	Display name for the pose (max 40 chars, default `"Uploaded Pose"`)

Transparent areas are filled with grey. The image keeps its shape and is scaled to 320–1024 px.

Example

curl -X POST https://www.autosprite.io/api/v1/characters/char_abc123/poses \
  -H "x-api-key: vspk_your_key_here" \
  -F "image=@guard-pose.png" \
  -F "name=Guard"

Response

Status: 201 Created

{
  "pose": {
    "id": "pose_003",
    "label": "Guard",
    "imageUrl": "https://... (presigned URL)",
    "prompt": null,
    "sourceType": "upload",
    "presetId": null,
    "createdAt": "2025-01-15T12:00:00Z"
  }
}

The pose is ready right away, so there's no job to poll.

Save a Spritesheet Frame as a Pose

POST /api/v1/characters/:characterId/poses

Save one frame of one of this character's spritesheets as a pose, for example the last frame of an animation, so the next animations start from exactly that image.

Cost: Free.

Request Body

Field	Type	Required	Description
`spritesheetId`	string	Yes	A spritesheet of this character
`frameIndex`	number	Yes	0-based, counted row by row. `frameCount - 1` from the Spritesheets API is the last frame
`name`	string	No	Display name for the pose (max 40 chars, default `"Frame <frameIndex>"`)

Transparent areas are filled with grey.

Example

curl -X POST https://www.autosprite.io/api/v1/characters/char_abc123/poses \
  -H "x-api-key: vspk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "spritesheetId": "sheet_xyz789",
    "frameIndex": 24,
    "name": "Wind-up End"
  }'

Response

Status: 201 Created, with the same pose object as an upload (sourceType: "spritesheet").

Errors

Status	Code	When
400	`MISSING_IMAGE`	Upload without an `image` file
400	`MISSING_FRAME_INDEX`	`spritesheetId` without a `frameIndex`
400	`INVALID_REQUEST`	Unreadable image, character or spritesheet not found, or `frameIndex` out of range
403	`PLAN_REQUIRED`	Paid subscription required

Using Poses in Animations

Once you have a pose, use its ID as poseId (first frame) or lastFramePoseId (last frame) when generating animations:

curl -X POST https://www.autosprite.io/api/v1/characters/char_abc123/spritesheets \
  -H "x-api-key: vspk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "animations": [
      {
        "kind": "attack",
        "poseId": "pose_001",
        "lastFramePoseId": "pose_002"
      }
    ]
  }'

ℹ️

Using lastFramePoseId or loop: true automatically upgrades the animation to legendary quality for better results.

✨

Pro Tip:

Create a "sword raised" pose, then use it as the lastFramePoseId for an attack animation. The animation will smoothly transition from the idle position to the attack stance.

Branching animations

To link animations, save the last frame of one animation as a pose and start the next ones from it. For example, a boss wind-up that leads into either an attack or a stunned loop:

Generate the wind-up animation and note its spritesheetId and frameCount.
Save its last frame: { "spritesheetId": "sheet_windup", "frameIndex": 24, "name": "Wind-up End" } returns pose_windup_end.
Generate both follow-ups from it:

{
  "animations": [
    { "kind": "attack", "poseId": "pose_windup_end" },
    { "kind": "custom", "prompt": "stunned, swaying in place", "poseId": "pose_windup_end", "lastFramePoseId": "pose_windup_end" }
  ]
}