User & Credits API

Overview

The User & Credits API provides endpoints for managing user profiles, checking credit balance, viewing usage history, and handling billing operations.

Base URL

https://api.percify.io/v1

Core Endpoints

Method	Endpoint	Description
GET	`/user/profile`	Get current user profile
PATCH	`/user/profile`	Update user profile
GET	`/user/credits/balance`	Get credit balance
GET	`/user/credits/history`	Get credit transaction history
GET	`/user/usage`	Get usage statistics
POST	`/user/credits/purchase`	Purchase credit pack
GET	`/user/tier`	Get subscription tier info

User Profile Object

{
  "id": "user_abc123",
  "email": "user@example.com",
  "username": "creative_user",
  "displayName": "Creative User",
  "avatar": "https://cdn.percify.io/avatars/user_abc123.jpg",
  "bio": "AI artist and content creator",
  "website": "https://example.com",
  "tier": "pro",
  "verified": true,
  "stats": {
    "avatarsCreated": 156,
    "videosGenerated": 42,
    "voicesCloned": 8,
    "followers": 234,
    "following": 89
  },
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-11-25T06:30:00Z"
}

Credits Object

{
  "balance": 450,
  "lifetime": {
    "earned": 50,
    "purchased": 500,
    "spent": 100
  },
  "currentMonth": {
    "earned": 0,
    "spent": 35
  },
  "tier": "pro",
  "nextRefill": "2025-12-01T00:00:00Z"
}

Get User Profile

const response = await fetch('https://api.percify.io/v1/user/profile', {
  headers: {
    'Authorization': `Bearer ${process.env.PERCIFY_API_KEY}`
  }
});

const profile = await response.json();
console.log(`Username: ${profile.username}, Tier: ${profile.tier}`);

import os
import requests

response = requests.get(
    'https://api.percify.io/v1/user/profile',
    headers={'Authorization': f'Bearer {os.environ["PERCIFY_API_KEY"]}'}
)

profile = response.json()
print(f"Username: {profile['username']}, Tier: {profile['tier']}")

curl -X GET https://api.percify.io/v1/user/profile \
  -H "Authorization: Bearer $PERCIFY_API_KEY"

Get Credit Balance

const response = await fetch('https://api.percify.io/v1/user/credits/balance', {
  headers: {
    'Authorization': `Bearer ${process.env.PERCIFY_API_KEY}`
  }
});

const credits = await response.json();
console.log(`Available credits: ${credits.balance}`);

import os
import requests

response = requests.get(
    'https://api.percify.io/v1/user/credits/balance',
    headers={'Authorization': f'Bearer {os.environ["PERCIFY_API_KEY"]}'}
)

credits = response.json()
print(f"Available credits: {credits['balance']}")

curl -X GET https://api.percify.io/v1/user/credits/balance \
  -H "Authorization: Bearer $PERCIFY_API_KEY"

Credit Transaction History

curl "https://api.percify.io/v1/user/credits/history?limit=50&offset=0" \
  -H "Authorization: Bearer $PERCIFY_API_KEY"

Response:

{
  "transactions": [
    {
      "id": "txn_abc123",
      "type": "debit",
      "amount": 5,
      "balance": 445,
      "description": "Avatar generation (Imagen3)",
      "resourceType": "avatar",
      "resourceId": "avatar_xyz789",
      "createdAt": "2025-11-25T06:15:00Z"
    },
    {
      "id": "txn_def456",
      "type": "credit",
      "amount": 100,
      "balance": 450,
      "description": "Credit pack purchase",
      "resourceType": "purchase",
      "resourceId": "purchase_pqr012",
      "createdAt": "2025-11-20T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 234,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Usage Statistics

curl "https://api.percify.io/v1/user/usage?period=30d" \
  -H "Authorization: Bearer $PERCIFY_API_KEY"

Response:

{
  "period": "30d",
  "startDate": "2025-10-26T00:00:00Z",
  "endDate": "2025-11-25T23:59:59Z",
  "usage": {
    "avatars": {
      "count": 45,
      "creditsSpent": 135,
      "byModel": {
        "flux": { "count": 30, "credits": 60 },
        "imagen3": { "count": 15, "credits": 75 }
      }
    },
    "videos": {
      "count": 12,
      "creditsSpent": 420,
      "totalDuration": 96
    },
    "audio": {
      "count": 8,
      "creditsSpent": 85,
      "totalDuration": 65
    }
  },
  "totalCreditsSpent": 640,
  "averagePerDay": 21.3
}

Subscription Tiers

curl -X GET https://api.percify.io/v1/user/tier \
  -H "Authorization: Bearer $PERCIFY_API_KEY"

Response:

{
  "currentTier": "pro",
  "tierDetails": {
    "name": "Pro",
    "monthlyCredits": 500,
    "price": 29.99,
    "features": [
      "500 credits per month",
      "Priority processing",
      "Advanced models access",
      "Batch generation",
      "Priority support"
    ],
    "limits": {
      "avatarsPerMonth": 1000,
      "videosPerMonth": 200,
      "voiceClonesTotal": 50,
      "concurrentGenerations": 5
    }
  },
  "usage": {
    "avatarsThisMonth": 45,
    "videosThisMonth": 12,
    "voiceClones": 8
  },
  "billingCycle": {
    "start": "2025-11-01T00:00:00Z",
    "end": "2025-12-01T00:00:00Z",
    "renewalDate": "2025-12-01T00:00:00Z"
  }
}

Purchase Credits

const response = await fetch('https://api.percify.io/v1/user/credits/purchase', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.PERCIFY_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    packId: 'pack_500',
    paymentMethod: 'stripe',
    returnUrl: 'https://example.com/payment/success'
  })
});

const purchase = await response.json();
console.log(`Payment URL: ${purchase.paymentUrl}`);

Response:

{
  "id": "purchase_abc123",
  "packId": "pack_500",
  "credits": 500,
  "price": 49.99,
  "currency": "USD",
  "paymentUrl": "https://checkout.stripe.com/...",
  "status": "pending",
  "expiresAt": "2025-11-25T07:00:00Z"
}

Available Credit Packs

Pack ID	Credits	Price	Bonus	Best For
`pack_100`	100	$9.99	-	Trying out
`pack_500`	500	$49.99	+50	Regular users
`pack_1000`	1000	$89.99	+150	Power users
`pack_5000`	5000	$399.99	+1000	Professionals

Update User Profile

const response = await fetch('https://api.percify.io/v1/user/profile', {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.PERCIFY_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    displayName: 'Updated Name',
    bio: 'AI artist specializing in character design',
    website: 'https://newsite.com'
  })
});

const profile = await response.json();

Rate Limits by Tier

Tier	API Requests/min	Concurrent Generations	Priority
Free	10	1	Standard
Pro	60	5	High
Enterprise	300	20	Highest

Webhooks

Subscribe to credit and usage events:

{
  "event": "credits.low_balance",
  "data": {
    "balance": 25,
    "threshold": 50,
    "recommendation": "purchase_pack_500"
  },
  "timestamp": "2025-11-25T06:35:00Z"
}

Available events:

credits.low_balance - Balance below threshold
credits.purchased - Credits added
tier.upgraded - Subscription upgraded
tier.downgraded - Subscription downgraded
usage.limit_approaching - Near tier limit

Error Responses

{
  "error": {
    "code": "payment_failed",
    "message": "Payment processing failed. Please check your payment method.",
    "details": {
      "reason": "insufficient_funds",
      "paymentMethod": "card_****1234"
    }
  }
}

Common error codes:

invalid_pack_id - Credit pack doesn’t exist
payment_failed - Payment processing error
tier_limit_reached - Monthly limit exceeded
invalid_update - Profile update validation failed

Best Practices

Monitor Usage

// Check balance before expensive operations
async function checkCredits(required) {
  const response = await fetch(
    'https://api.percify.io/v1/user/credits/balance',
    {
      headers: {
        'Authorization': `Bearer ${process.env.PERCIFY_API_KEY}`
      }
    }
  );
  
  const credits = await response.json();
  
  if (credits.balance < required) {
    throw new Error(
      `Insufficient credits. Required: ${required}, Available: ${credits.balance}`
    );
  }
  
  return credits.balance;
}

Set Up Webhooks

Configure webhooks to:

Alert when balance is low
Track usage patterns
Automate credit purchases
Monitor tier limits

Optimize Credit Usage

Use Flux model for testing (2 credits)
Keep videos under 5 seconds when possible
Reuse voice clones (5 credits once)
Batch similar operations
Monitor usage statistics regularly

Next Steps

Credits Guide

Understand pricing

Payments

Billing and invoices

Usage Tracking

Optimize performance

Getting Started

Avatar API

Video Studio API

Audio & Voice API

User & Credits API

Overview

Base URL

Core Endpoints

User Profile Object

Credits Object

Get User Profile

Get Credit Balance

Credit Transaction History

Usage Statistics

Subscription Tiers

Purchase Credits

Available Credit Packs

Update User Profile

Rate Limits by Tier

Webhooks

Error Responses

Best Practices

Next Steps

Credits Guide

Payments

Usage Tracking

​Overview

​Base URL

​Core Endpoints

​User Profile Object

​Credits Object

​Get User Profile

​Get Credit Balance

​Credit Transaction History

​Usage Statistics

​Subscription Tiers

​Purchase Credits

​Available Credit Packs

​Update User Profile

​Rate Limits by Tier

​Webhooks

​Error Responses

​Best Practices

​Next Steps

Credits Guide

Payments

Usage Tracking

Overview

Base URL

Core Endpoints

User Profile Object

Credits Object

Get User Profile

Get Credit Balance

Credit Transaction History

Usage Statistics

Subscription Tiers

Purchase Credits

Available Credit Packs

Update User Profile

Rate Limits by Tier

Webhooks

Error Responses

Best Practices

Next Steps