API Documentation

The GenSprite API lets you generate sprites, textures, concept art, rotations, and animations programmatically. All endpoints use JSON requests/responses and require API key authentication.

All API requests require an API key passed in the Authorization header. Generate a key from your Dashboard.

Authorization: Bearer gsk_your_api_key

Errors

The API returns standard HTTP status codes. Error responses include a JSON body with a message field.

Fetch platform configuration for the GenSprite agent. Returns the Anthropic API key (platform-owned, not user-facing), model settings, and the user's current credit balance. Rate limited to 1 request per minute per key.

Response

{
  "anthropic_api_key": "sk-ant-...",
  "model": "claude-opus-4-5",
  "max_tokens": 8096,
  "user_id": "abc123",
  "credits": 142
}

Get your current token balance and pricing information.

Response

{
  "tokens": 47,
  "bonusTokens": 95,
  "totalTokens": 142,
  "tokenCosts": {
    "sprite": 3,
    "texture": 4,
    "rotation": 25,
    "rotationNew": 12,
    "conceptArt": 4,
    "conceptArtRestyle": 6,
    "spin": 25,
    "rotationSingleView": 7
  }
}

Generate a game sprite with transparent background. Costs 3 tokens.

Request Body

curl -X POST https://gensprite.ai/api/assets/generate \
  -H "Authorization: Bearer gsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "medieval knight with sword", "style": "hand-painted"}'

Response

{
  "asset": {
    "id": "abc123",
    "visibleId": "xK9mQ2",
    "status": "pending",
    "prompt": "medieval knight with sword",
    "width": 512,
    "height": 512,
    "tokenCost": 3,
    "createdAt": "2026-03-09T12:00:00.000Z"
  },
  "isGuest": false,
  "tokensUsed": 3,
  "tokensRemaining": 44,
  "bonusTokensRemaining": 95,
  "totalTokensRemaining": 139
}

Poll the status of a sprite generation. When status is "completed", the image URLs are in resultUrls. Poll every 2–5 seconds.

Response

{
  "id": "abc123",
  "status": "completed",
  "progress": 100,
  "resultUrls": {
    "raw": "https://...",
    "processed": "https://..."
  },
  "seed": 4281937,
  "completedAt": "2026-03-09T12:00:30.000Z"
}

Cancel an in-progress sprite generation. Tokens are automatically refunded if the generation hasn't completed.

Response

{
  "success": true,
  "tokensRefunded": 3
}

List your generated sprites with cursor-based pagination.

Query Parameters

Response

{
  "assets": [ ... ],
  "nextCursor": "xyz789"
}

Generate a PBR texture set (basecolor, normal, roughness, metallic maps). Costs 4 tokens.

Request Body

Status & Cancel

Use GET /api/textures/{id}/status and POST /api/textures/{id}/cancel. Completed textures include basecolorUrl, normalUrl, roughnessUrl, metallicUrl.

Generate full-scene concept art. Costs 4 tokens (standard) or 6 tokens (restyle).

Request Body (JSON)

For restyle mode, use multipart/form-data with a compositionImage file, mode=restyle, controlMethod (canny | depth), and controlStrength (0–100).

Status & Cancel

Use GET /api/concept-art/{id}/status and POST /api/concept-art/{id}/cancel. Completed result includes imageUrl.

Generate 8-directional rotations from an input image. Costs 25 tokens. Accepts multipart/form-data (file upload) or JSON (image URL).

Request Body

Status & Cancel

Use GET /api/rotate/{id}/status and POST /api/rotate/{id}/cancel. Completed result includes rotationN, rotationNE, rotationE, etc. (8 direction URLs).

Generate 4-directional rotations (front, right, back, left). Costs 12 tokens. Same request format as 8-dir rotation.

Status & Cancel

Use GET /api/rotate-new/{id}/status and POST /api/rotate-new/{id}/cancel. Completed result includes rotationFront, rotationRight, rotationBack, rotationLeft.

Generate frame-by-frame sprite animation with multi-direction support. Token cost varies by animation type and direction count. Uses multipart/form-data.

Form Fields

Status & Cancel

Use GET /api/animate/{id}/status and POST /api/animate/{id}/cancel. Completed result includes spritesheetUrl, frameCount, tileWidth, tileHeight.

1. 1
   Submit — POST to the generate endpoint. You'll get back a job id with status "pending".
2. 2
   Poll — GET the status endpoint every 2–5 seconds. Watch for status to reach "completed" or "failed".
3. 3
   Download — When completed, fetch the result URLs (images are publicly accessible).

# 1. Generate a sprite
RESPONSE=$(curl -s -X POST https://gensprite.ai/api/assets/generate \
  -H "Authorization: Bearer gsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "fire elemental monster", "style": "anime"}')

ASSET_ID=$(echo $RESPONSE | jq -r '.asset.id')

# 2. Poll until complete
while true; do
  STATUS=$(curl -s \
    -H "Authorization: Bearer gsk_your_key" \
    https://gensprite.ai/api/assets/$ASSET_ID/status)

  STATE=$(echo $STATUS | jq -r '.status')
  echo "Status: $STATE"

  if [ "$STATE" = "completed" ]; then
    IMAGE_URL=$(echo $STATUS | jq -r '.resultUrls.processed')
    echo "Done! $IMAGE_URL"
    break
  elif [ "$STATE" = "failed" ]; then
    echo "Failed: $(echo $STATUS | jq -r '.errorMessage')"
    break
  fi

  sleep 3
done

# 3. Download the image
curl -o sprite.png "$IMAGE_URL"