> For the complete documentation index, see [llms.txt](https://shortgenius.gitbook.io/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shortgenius.gitbook.io/api/guides/usage-credits.md).

# Usage & Credits

ShortGenius operates on a **credit-based system** to manage resource-intensive AI processes (video creation, image generation, text-to-speech, etc.). This section explains how to retrieve your current credit balances and interpret usage details.

***

## Get Usage (Credits)

**Endpoint**: `GET /credits`

Use this endpoint to see your current balance of credits.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import { ShortGenius } from 'shortgenius'

const client = new ShortGenius({
  bearerAuth: 'YOUR_API_TOKEN'
})

const usage = await client.getUsage()

console.log('Credit Balance:')
console.log(`  Credits: ${usage.balance.credits}`)
```

{% endtab %}

{% tab title="Python" %}

```python
from shortgenius import Shortgenius

client = Shortgenius(api_key="YOUR_API_TOKEN")

usage = client.usage.get()

print("Credit Balance:")
print(f"  Credits: {usage.balance.credits}")
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET \
  --url "https://api.shortgenius.com/v1/credits" \
  --header "Authorization: Bearer YOUR_API_TOKEN"
```

{% endtab %}
{% endtabs %}

**Sample Response**:

```json
{
  "balance": {
    "credits": 217
  }
}
```

### Understanding the Credit Balance

| Field     | Description                                                                                   |
| --------- | --------------------------------------------------------------------------------------------- |
| `credits` | Your available credits. A single credit pool funds video creation, image generation, and TTS. |

***

## When Are Credits Deducted?

Credits are deducted whenever you:

1. **Generate a new video** (drafting may or may not consume minimal credits, but final creation deducts the majority).
2. **Generate images** (each request uses at least one image credit).
3. **Create text-to-speech audio** (some usage policies may apply, depending on length or voice type).

The exact cost per request may vary based on your plan and the complexity of the task. Check your [ShortGenius dashboard](https://shortgenius.com) for detailed pricing.

***

## Best Practices for Credit Management

1. **Check Your Balance Regularly**\
   Use `GET /credits` before launching large-scale generation tasks.
2. **Batch Your Requests**\
   Instead of multiple small calls, sometimes it's more cost-effective to batch generation (e.g., series or bulk topics).
3. **Optimize Drafts**\
   **Draft** your video scripts first, then carefully finalize them to avoid accidental re-renders that use up credits.
4. **Monitor Renewal Cycles**\
   If you're on a subscription plan with monthly credit resets, align your bigger projects when credits refresh.

***

## Error Handling with Insufficient Credits

If you attempt an operation but don't have enough credits, you'll typically see:

```json
{
  "message": "Insufficient credits"
}
```

or a **400/402** status code, depending on how the system classifies the shortfall.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import { APIError } from 'shortgenius'

// Check credits before expensive operations
const usage = await client.getUsage()

if (usage.balance.credits < 10) {
  console.warn('Low on credits!')
}

// Handle insufficient credit errors
const video = await client
  .createVideo({
    // ... video parameters ...
  })
  .catch(error => {
    if (error instanceof APIError && error.status === 402) {
      console.error('Insufficient credits to create video')
    }
    throw error
  })
```

{% endtab %}

{% tab title="Python" %}

```python
from shortgenius.types import APIError

# Check credits before expensive operations
usage = client.usage.get()

if usage.balance.credits < 10:
    print("Warning: Low on credits!")

# Handle insufficient credit errors
try:
    video = client.videos.create(
        # ... video parameters ...
    )
except APIError as e:
    if e.status_code == 402:
        print("Insufficient credits to create video")
    raise
```

{% endtab %}
{% endtabs %}

***

## Next Steps

You've now covered:

1. **How to retrieve your credit balance.**
2. **When credits are deducted.**
3. **Tips for efficient credit usage.**

For additional tips and real-world workflows, check out the [Guides & Tutorials](/api/guides/usage-credits.md) section. Or, if you need a deep dive into every endpoint's request/response, visit the [Reference](/api/guides/usage-credits.md) section.