> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viggle.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits

> Read the current account credit balance.

## Get credit balance

`GET /v1/credits`

Returns the current balance for the API key's account or organization. This endpoint has no parameters and requires `Authorization: Bearer YOUR_API_KEY`.

```bash theme={null}
curl "https://apis.viggle.ai/v1/credits" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

```json theme={null}
{
  "balance": 124.5
}
```

| Field | Type | Description |
| - | - | - |
| `balance` | number | Credits currently available to the caller. |

A missing or expired API key returns `401` with the standard `ErrorBody` — see [Errors and recovery](/v1/production/errors).


## OpenAPI

````yaml openapi.yaml GET /v1/credits
openapi: 3.0.3
info:
  title: Viggle API
  description: Generate AI-powered character animation videos
  version: 2.0.0
  contact:
    name: Viggle Support
    url: https://viggle.ai
servers:
  - url: https://apis.viggle.ai
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Renders
    description: Prepare inputs, create renders, observe progress, and retrieve results.
  - name: Credits
    description: Read the credit balance available to the calling principal.
  - name: Characters
    description: |
      Create, list, inspect, and delete reusable character assets. `type`
      selects whether creation also extracts a 3D vsplat; export its
      download URL separately once ready.
  - name: Motions
    description: |
      Create, list, inspect, and delete reusable motion assets, and import one
      from an official motion template. `type` selects whether creation also
      extracts or generates a 3D animation; export its download URL
      separately once ready.
  - name: Videos
    description: >
      Generate a MiniMax H3 video from text, frames, or references (`vid_`

      prefix) or a character-animation video from a character image and/or
      driving video

      (`anim_` prefix), and read the unified view over every video the

      caller owns — H3 generations, character-animation generations, and

      character+motion Renders (`render_` prefix) — merged into one

      resource.
  - name: Images
    description: |
      Viggle Image — generate 1–6 PNG images from a text prompt with the
      `qwen` model, optionally guided by up to 8 reference images
      (`img_` prefix), and retrieve them by ID.
paths:
  /v1/credits:
    get:
      tags:
        - Credits
      summary: Get the credit balance of the calling principal
      operationId: v1GetCreditBalance
      parameters:
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/SourceChannel'
      responses:
        '200':
          description: The one canonical balance value.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1CreditBalance'
        '401':
          $ref: '#/components/responses/ResourceUnauthorized'
        '500':
          $ref: '#/components/responses/ResourceInternalServerError'
        '503':
          $ref: '#/components/responses/ResourceServiceUnavailable'
components:
  parameters:
    RequestId:
      name: X-Request-Id
      in: header
      required: false
      description: >-
        Optional caller-supplied correlation ID, up to 128 characters. The
        service returns the effective value in the response header for tracing
        and support.
      schema:
        type: string
        minLength: 1
        maxLength: 128
    SourceChannel:
      name: X-Viggle-Source
      in: header
      required: false
      description: >-
        Optional source-channel label, up to 128 characters, used to attribute
        traffic to an SDK, integration, product surface, or internal workflow.
      schema:
        type: string
        minLength: 1
        maxLength: 128
  headers:
    RequestId:
      description: Stable request identifier for support and tracing.
      schema:
        type: string
  schemas:
    V1CreditBalance:
      type: object
      additionalProperties: false
      required:
        - balance
      properties:
        balance:
          type: number
          description: >-
            Current spendable credit balance for the authenticated project or
            OAuth principal.
    ResourceErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          description: Top-level synchronous resource-operation error payload.
          allOf:
            - $ref: '#/components/schemas/ResourceHttpError'
    ResourceHttpError:
      description: |
        The failure envelope of a synchronous resource request. Every code is
        produced by one mapping in the API service, so the set is closed; a
        failure with no published mapping surfaces as `processing_failed`.

        The asynchronous `error` object on a resource carries the wider,
        deliberately open vocabulary of `ResourceError` instead.
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - request_id
      properties:
        code:
          type: string
          description: >-
            Closed, lower_snake_case error code for a synchronous resource
            request; use it for programmatic handling.
          enum:
            - authentication_required
            - invalid_api_key
            - insufficient_credits
            - invalid_request
            - motion_not_ready
            - character_not_found
            - motion_not_found
            - not_found
            - id_already_exists
            - rate_limited
            - service_unavailable
            - task_failed
            - internal_error
            - processing_failed
        message:
          type: string
          description: Human-readable explanation of the synchronous request failure.
        request_id:
          description: |
            Always null on a synchronous failure. Correlate with the
            `X-Request-Id` response header instead.
          type: string
          nullable: true
  responses:
    ResourceUnauthorized:
      description: Missing, invalid, or expired API key.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
    ResourceInternalServerError:
      description: Unexpected server error.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
    ResourceServiceUnavailable:
      description: Service temporarily unavailable.
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 0
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or OAuth access token
      description: |
        Server-side SDK clients use a project API key. Remote MCP clients use
        an OAuth access token. Never expose a project API key in browser code.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.