spritecook-ai Animation API

openapi: 3.2.0
info:
  title: SpriteCook Animation API
  description: 'Generate and animate 2D game art (pixel art and detailed/HD) from code.


    Authenticate with an API key in the `Authorization: Bearer sc_live_...` header.

    Create keys on the API Keys page (https://app.spritecook.ai/api-keys); each key

    carries a set of scopes (see the `apiKey` security scheme). New accounts get

    free credits, no card needed.


    Long-running work is asynchronous: submit a job, then poll

    `GET /v1/api/jobs/{job_id}` with the returned `poll_url`. The `*-sync`

    variants wait up to 90 seconds and return the finished job.


    Errors use one envelope: `{"detail": {"error": {"code": "...", "message": "..."}}}`.


    Prefer the MCP server (https://api.spritecook.ai/mcp) when you are an agent

    that speaks MCP; it exposes the same capabilities as tools.'
  version: 1.0.0
  summary: AI pixel art and 2D game asset generation API.
  termsOfService: https://www.spritecook.ai/terms
  contact:
    name: SpriteCook support
    email: support@spritecook.ai
    url: https://www.spritecook.ai/contact
servers:
- url: https://api.spritecook.ai
  description: Production
security:
- apiKey: []
tags:
- name: Animation
  description: Animate existing assets and characters.
paths:
  /v1/api/characters/{character_id}/animations:
    post:
      summary: Submit a guided animation run for a base character asset
      description: Submit a guided animation run for a base character asset.
      operationId: generateCharacterAnimations
      parameters:
      - name: character_id
        in: path
        required: true
        schema:
          type: string
          title: Character Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCharacterAnimationsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiCharacterAnimationRun'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '400':
          description: The request is invalid. `detail.error.code` says why (for example `invalid_request`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: Not enough credits (`insufficient_credits`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: The API key lacks the required scope (`scope_denied`) or the account cannot use this feature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: The asset, job or run was not found or does not belong to you.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Rate limit or queue limit reached. Retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Animation
      security:
      - apiKey:
        - generate
      x-required-scope: generate
  /v1/api/character-animation-runs/{run_id}:
    get:
      summary: Check the status of a guided character animation run
      description: Check the status of a guided character animation run.
      operationId: getCharacterAnimationRun
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiCharacterAnimationRun'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '400':
          description: The request is invalid. `detail.error.code` says why (for example `invalid_request`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: Not enough credits (`insufficient_credits`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: The API key lacks the required scope (`scope_denied`) or the account cannot use this feature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: The asset, job or run was not found or does not belong to you.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Rate limit or queue limit reached. Retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Animation
      security:
      - apiKey:
        - generate
      x-required-scope: generate
  /v1/api/animate:
    post:
      summary: Submit an animation job
      description: Submit an animation job. Returns immediately with a job ID for polling.
      operationId: animate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiAnimateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiJobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '400':
          description: The request is invalid. `detail.error.code` says why (for example `invalid_request`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: Not enough credits (`insufficient_credits`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: The API key lacks the required scope (`scope_denied`) or the account cannot use this feature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: The asset, job or run was not found or does not belong to you.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Rate limit or queue limit reached. Retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Animation
      security:
      - apiKey:
        - generate
      x-required-scope: generate
  /v1/api/animate-sync:
    post:
      summary: Generate an animation and wait up to 90 seconds for the result
      description: Generate an animation and wait up to 90 seconds for the result.
      operationId: animateSync
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiAnimateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiJobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '400':
          description: The request is invalid. `detail.error.code` says why (for example `invalid_request`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: Not enough credits (`insufficient_credits`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: The API key lacks the required scope (`scope_denied`) or the account cannot use this feature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: The asset, job or run was not found or does not belong to you.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Rate limit or queue limit reached. Retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Animation
      security:
      - apiKey:
        - generate
      x-required-scope: generate
components:
  schemas:
    ApiAnimationOutputMetadata:
      properties:
        frame_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Frame Count
        fps:
          anyOf:
          - type: integer
          - type: 'null'
          title: Fps
        frame_width:
          anyOf:
          - type: integer
          - type: 'null'
          title: Frame Width
        frame_height:
          anyOf:
          - type: integer
          - type: 'null'
          title: Frame Height
        animation_mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Animation Mode
      type: object
      title: ApiAnimationOutputMetadata
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ApiCharacterAnimationRun:
      title: ApiCharacterAnimationRun
      type: object
      required:
      - status
      properties:
        id:
          type:
          - string
          - 'null'
          description: Run ID. Poll GET /v1/api/character-animation-runs/{run_id}.
        status:
          type: string
          description: queued, running, completed, failed or cancelled.
        character_id:
          type:
          - string
          - 'null'
        source_asset_id:
          type:
          - string
          - 'null'
        preset_pack_id:
          type:
          - string
          - 'null'
        preset_ids:
          type: array
          items:
            type: string
        items:
          type: array
          items:
            type: object
            additionalProperties: true
          description: One entry per requested animation.
        result_asset_ids:
          type: array
          items:
            type: string
        credits_reserved:
          type:
          - integer
          - 'null'
        credits_remaining:
          type:
          - integer
          - 'null'
        error_message:
          type:
          - string
          - 'null'
      additionalProperties: true
    ApiJobResponse:
      properties:
        job_id:
          type: string
          title: Job Id
        status:
          type: string
          title: Status
        progress:
          anyOf:
          - type: integer
          - type: 'null'
          title: Progress
        character_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Character Id
        assets:
          anyOf:
          - items:
              $ref: '#/components/schemas/ApiAssetInfo'
            type: array
          - type: 'null'
          title: Assets
        output:
          anyOf:
          - $ref: '#/components/schemas/ApiAnimationOutput'
          - type: 'null'
        file:
          anyOf:
          - $ref: '#/components/schemas/ApiBackgroundRemovalFile'
          - type: 'null'
        error:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Error
        credits_used:
          anyOf:
          - type: integer
          - type: 'null'
          title: Credits Used
        credits_remaining:
          anyOf:
          - type: integer
          - type: 'null'
          title: Credits Remaining
        poll_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Poll Url
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        finished_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Finished At
        service_notice:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Service Notice
      type: object
      required:
      - job_id
      - status
      title: ApiJobResponse
    ApiError:
      title: ApiError
      type: object
      required:
      - detail
      properties:
        detail:
          type: object
          required:
          - error
          properties:
            error:
              type: object
              required:
              - code
              - message
              properties:
                code:
                  type: string
                  description: Stable machine-readable error code, for example `insufficient_credits`.
                message:
                  type: string
                  description: Human-readable explanation.
                details:
                  type: object
                  additionalProperties: true
    ApiBackgroundRemovalFile:
      properties:
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
        media_kind:
          type: string
          enum:
          - image
          - animation
          title: Media Kind
        width:
          anyOf:
          - type: integer
          - type: 'null'
          title: Width
        height:
          anyOf:
          - type: integer
          - type: 'null'
          title: Height
        frame_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Frame Count
        fps:
          anyOf:
          - type: integer
          - type: 'null'
          title: Fps
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
          description: When this temporary file stops being available (ISO 8601). Download it before then.
        expired:
          type: boolean
          title: Expired
          description: True once the file is no longer available; url is then null.
          default: false
      type: object
      required:
      - media_kind
      title: ApiBackgroundRemovalFile
    ApiCharacterAnimationsRequest:
      properties:
        perspective:
          type: string
          enum:
          - platformer
          - isometric
          - topdown
          title: Perspective
          description: Perspective workflow used for the base character
        animation_ids:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Animation Ids
          description: Preset animation ids for this perspective
        custom_animations:
          anyOf:
          - items:
              $ref: '#/components/schemas/ApiCustomCharacterAnimationRequest'
            type: array
          - type: 'null'
          title: Custom Animations
          description: Prompt-driven custom animations
        bg_removal_provider:
          anyOf:
          - type: string
            pattern: ^(basic|photoroom)$
          - type: 'null'
          title: Bg Removal Provider
          default: basic
        photoroom_mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Photoroom Mode
          description: Reserved for photoroom mode; currently forced to per_frame
      type: object
      required:
      - perspective
      title: ApiCharacterAnimationsRequest
    ApiAnimationOutput:
      properties:
        asset_id:
          type: string
          title: Asset Id
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
        spritesheet_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Spritesheet Url
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
        metadata:
          $ref: '#/components/schemas/ApiAnimationOutputMetadata'
      type: object
      required:
      - asset_id
      - metadata
      title: ApiAnimationOutput
    ApiCustomCharacterAnimationRequest:
      properties:
        id:
          anyOf:
          - type: string
            maxLength: 80
          - type: 'null'
          title: Id
          description: Optional stable id suffix for the custom animation
        label:
          anyOf:
          - type: string
            maxLength: 80
          - type: 'null'
          title: Label
          description: Display label for the custom animation
        prompt:
          type: string
          maxLength: 3000
          minLength: 1
          title: Prompt
          description: Animation prompt
        source_view:
          anyOf:
          - type: string
          - type: 'null'
          title: Source View
          description: Source view to animate from. Defaults to front_idle
        output_frames:
          type: integer
          multipleOf: 2.0
          maximum: 16.0
          minimum: 2.0
          title: Output Frames
          description: Output frame count, 2 to 16, even counts only (pixel-engine-v1.1)
          default: 8
      type: object
      required:
      - prompt
      title: ApiCustomCharacterAnimationRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ApiAnimateRequest:
      properties:
        image:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Image
          description: Deprecated inline image field. Animate now requires a SpriteCook asset_id.
        asset_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Asset Id
          description: Existing SpriteCook asset ID to animate. The asset must belong to the authenticated user.
        prompt:
          type: string
          maxLength: 3000
          minLength: 1
          title: Prompt
          description: Describe the desired animation
        auto_enhance_prompt:
          type: boolean
          title: Auto Enhance Prompt
          description: When true, SpriteCook inspects the source asset and expands short prompts like 'Idle' into a fuller animation prompt.
          default: true
        edge_margin:
          type: integer
          maximum: 25.0
          minimum: 0.0
          title: Edge Margin
          description: Spacing added before animation as a percentage of the trimmed source size. The subject stands on the bottom edge as a ground line, so the margin goes on the sides and top; set vertical_align='center' to also add room below.
          default: 6
        vertical_align:
          anyOf:
          - type: string
            enum:
            - bottom
            - center
          - type: 'null'
          title: Vertical Align
          description: Pixel art only. Omit to keep the ground line (bottom). 'center' centers the subject so edge_margin applies on all sides, for flying, floating or bouncing subjects.
        pixel:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Pixel
          description: Animation mode override. If asset_id is provided and pixel is omitted, mode is inferred from the asset.
        model:
          anyOf:
          - type: string
            enum:
            - pixel-engine-v1.1
            - frame-engine-v1.1
            - pixel-engine-v1.5
          - type: 'null'
          title: Model
          description: 'Animation model: pixel-engine-v1.1, frame-engine-v1.1, pixel-engine-v1.5. Omit to use pixel-engine-v1.1 for pixel art or frame-engine-v1.1 for detailed art.'
        output_frames:
          type: integer
          maximum: 24.0
          minimum: 2.0
          title: Output Frames
          description: 'Output frame count. Frame count rules by model: pixel-engine-v1.1: pixel 2 to 16 (even counts); frame-engine-v1.1: detailed 2 to 24 (even counts); pixel-engine-v1.5: pixel 3 to 16 (any whole number), detailed 3 to 16 (any whole number). When model is omitted, pixel defaults to pixel-engine-v1.1, detailed defaults to frame-engine-v1.1.'
          default: 8
        output_format:
          type: string
          enum:
          - webp
          - gif
          - spritesheet
          title: Output Format
          description: Provider output format
          default: webp
        negative_prompt:
          anyOf:
          - type: string
            maxLength: 1000
          - type: 'null'
          title: Negative Prompt
          description: Optional negative prompt
          default: ''
        outline_repair:
          type: boolean
          title: Outline Repair
          description: 'Repair pixel art outlines after background removal: restores clipped outline pixels and removes background fringe (only applies to pixel art with a transparent background)'
          default: true
        matte_color:
          anyOf:
          - type: string
          - type: 'null'
          title: Matte Color
          description: Hex matte color used to flatten alpha before processing
          default: '#808080'
        removebg:
          type: string
          title: Removebg
          description: 'Background removal mode: None, Basic, or Pro'
          default: Basic
        colors:
          type: integer
          maximum: 256.0
          minimum: 2.0
          title: Colors
          description: Pixel palette size. Only valid when pixel=true
          default: 24
        use_random_seed:
          type: boolean
          title: Use Random Seed
          description: When true, the server generates a fresh random seed for this animation.
          default: true
        seed:
          anyOf:
          - type: integer
          - type: 'null'
          title: Seed
          description: Custom reproducibility seed. Required when use_random_seed is false.
        runpod_alpha_threshold_enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Runpod Alpha Threshold Enabled
          description: Alpha threshold toggle for Basic background removal during cleanup. Defaults to true for the public API. When false, runpod_alpha_cutoff is ignored.
        runpod_alpha_cutoff:
          anyOf:
          - type: integer
            maximum: 255.0
            minimum: 0.0
          - type: 'null'
          title: Runpod Alpha Cutoff
          description: Binary alpha cutoff for Basic background removal during cleanup. Defaults to 96 for the public API when runpod_alpha_threshold_enabled is true.
      type: object
      required:
      - prompt
      title: ApiAnimateRequest
    ApiAssetInfo:
      properties:
        id:
          type: string
          title: Id
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
        sprite_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Sprite Url
        spritesheet_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Spritesheet Url
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
        file_name:
          anyOf:
          - type: string
          - type: 'null'
          title: File Name
        width:
          anyOf:
          - type: integer
          - type: 'null'
          title: Width
        height:
          anyOf:
          - type: integer
          - type: 'null'
          title: Height
        prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        asset_kind:
          anyOf:
          - type: string
          - type: 'null'
          title: Asset Kind
        tilesetKind:
          anyOf:
          - type: string
          - type: 'null'
          title: Tilesetkind
        tilesetPieceSet:
          anyOf:
          - type: string
          - type: 'null'
          title: Tilesetpieceset
        tilesetPerspective:
          anyOf:
          - type: string
          - type: 'null'
          title: Tilesetperspective
        tilesetElevation:
          anyOf:
          - type: string
          - type: 'null'
          title: Tilesetelevation
        tilesetTileSize:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tilesettilesize
        tilesetStyleMode:
          anyOf:
          - type: string
          - type: 'null'
          title: Tilesetstylemode
        tilesetGridSize:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tilesetgridsize
        tilesetGridWidth:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tilesetgridwidth
        tilesetGridHeight:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tilesetgridheight
        tilesetOutputSize:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tilesetoutputsize
        tilesetOutputWidth:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tilesetoutputwidth
        tilesetOutputHeight:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tilesetoutputheight
        tilesetAtlasColumns:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tilesetatlascolumns
        tilesetAtlasRows:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tilesetatlasrows
        tilesetEdges:
          anyOf:
          - type: string
          - type: 'null'
          title: Tilesetedges
      type: object
      required:
      - id
      title: ApiAssetInfo
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: sc_live_ API key
      description: 'SpriteCook API key sent as `Authorization: Bearer sc_live_...`. Create one at https://app.spritecook.ai/api-keys and grant only the scopes you need. Each operation lists its required scope in `security`.


        - `generate`: Create, animate, import, slice and clean up assets, and manage the jobs they start. Spends credits.

        - `read_assets`: Read metadata and download URLs for assets you own.

        - `read_credits`: Read your credit balance.

        - `report_errors`: Send integration error reports to SpriteCook (used by the MCP server).'
externalDocs:
  description: API guide with examples
  url: https://www.spritecook.ai/api-docs
x-spritecook-scopes:
  generate: Create, animate, import, slice and clean up assets, and manage the jobs they start. Spends credits.
  read_assets: Read metadata and download URLs for assets you own.
  read_credits: Read your credit balance.
  report_errors: Send integration error reports to SpriteCook (used by the MCP server).