# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://shortgenius.gitbook.io/api/guides/usage-credits.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.