Poses API

Poses are custom character images generated from a text prompt. Use them as the first frame or last frame of an animation to control exactly how an animation starts or ends.

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

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

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"
      }
    ]
  }'