Authentication & Essentials

In this section, we'll discuss how to securely authorize your requests, handle potential errors, and manage credits for ShortGenius services.

Authentication (Bearer Token)

All ShortGenius endpoints require a valid bearer token. If you haven't already retrieved a token from your ShortGenius dashboard, follow the sign-up process mentioned in our Getting Started Quickstart.

Using cURL

How to include your token:

Authorization: Bearer YOUR_API_TOKEN

Example request:

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

Using SDKs

If you're using one of our official SDKs, authentication is even simpler:

TypeScript

import { ShortGenius } from 'shortgenius'

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

// The SDK automatically includes the bearer token in all requests
const status = await client.status.check()

You can also use environment variables:

// SDK will automatically use SHORTGENIUS_BEARER_AUTH env variable
const client = new ShortGenius({
  bearerAuth: process.env.SHORTGENIUS_BEARER_AUTH
})

Python

from shortgenius import Shortgenius

client = Shortgenius(api_key="YOUR_API_TOKEN")

// The SDK automatically includes the API key in all requests
status = client.status.check()

You can also use environment variables:

import os

// SDK will automatically use SHORTGENIUS_API_KEY env variable
client = Shortgenius(
    api_key=os.environ.get("SHORTGENIUS_API_KEY")
)

Tip: Always store tokens securely (e.g., environment variables, secret managers). Do not commit them to version control.

Handling Errors

ShortGenius will return standard HTTP status codes and JSON-encoded error messages when something goes wrong. Below are some common error types:

Status Code	Meaning	Example Message
400	Bad Request	{"message": "Invalid request"}
401	Unauthorized	{"message": "Unauthorized"}
404	Not Found	{"message": "Not found"}
429	Too Many Requests	{"message": "Rate limit exceeded"}
500	Internal Server Error	{"message": "Something went wrong"}

Example of a 400 Response:

{
  "message": "Invalid request"
}

SDK Error Handling

The SDKs provide typed error handling:

TypeScript

import { ShortGenius, APIError } from 'shortgenius'

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

const video = await client.getVideo('invalid-id')

Python

from shortgenius import Shortgenius
from shortgenius.types import APIError

client = Shortgenius(api_key="YOUR_API_TOKEN")

try:
    video = client.videos.retrieve("invalid-id")
except APIError as e:
    print(f"API Error {e.status_code}: {e.message}")

    if e.status_code == 401:
        print("Check your API key")
    elif e.status_code == 404:
        print("Video not found")
    elif e.status_code == 429:
        print("Rate limit exceeded, slow down")

Always inspect the returned JSON for more details on why a request failed.

Rate Limits & Credits

ShortGenius enforces usage limits via a credit-based system. Each time you generate a video, image, or audio file, credits are deducted from your account.

Types of credits include:

• credits – General-purpose for many actions

• animated_video_credits – Special tier for certain AI animations

• image_credits – Used specifically for image generation

• high_quality_video_credits – For higher resolution or advanced video rendering

Checking Your Credit Balance

Use the GET /credits endpoint to see how many credits remain:

TypeScript

const usage = await client.getUsage()

console.log('Credit Balance:')
console.log(`  General credits: ${usage.balance.credits}`)
console.log(`  Image credits: ${usage.balance.image_credits}`)
console.log(`  Animated video credits: ${usage.balance.animated_video_credits}`)
console.log(`  High quality video credits: ${usage.balance.high_quality_video_credits}`)

Python

usage = client.usage.get()

print("Credit Balance:")
print(f"  General credits: {usage.balance.credits}")
print(f"  Image credits: {usage.balance.image_credits}")
print(f"  Animated video credits: {usage.balance.animated_video_credits}")
print(f"  High quality video credits: {usage.balance.high_quality_video_credits}")

cURL

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

Best Practice: Check your available credits regularly to avoid interruptions, especially before generating large batches of videos or images.

---

Next Steps You're now ready to dig into ShortGenius's core functionality. Let's move on to Video Generation to learn how to create short AI-driven clips from scratch.