Skip to main content

​
Overview

Follow these steps to experience the full Percify creation loop quickly.
Sign up on the Percify dashboard. Your starter credits appear automatically; if not, visit Billing to purchase a pack.
Navigate to Settings → API Keys. Create a key and store it securely. Use it in the Authorization: Bearer <key> header for server-side calls.
Use the Avatar Studio UI or call the image generation endpoint:
curl -X POST https://api.percify.io/v1/images/generate \
  -H "Authorization: Bearer $PERCIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"futuristic portrait, soft rim light"}'
Response includes id, status, and creditCost. Track generation with the returned ID if asynchronous.
Adjust prompt, style, or upscale. Publishing marks the avatar as visible in feed/explore unless you set private visibility. Private avatars still usable for video/voice pipelines.
In Studio select “Image to Video”. Each clip consumes base + per‑second credits. Keep under 5s for minimal cost. See [/percify/image-to-video] for pricing formula.
Upload a clean sample (≥15s). Voice cloning costs base credits; generating speech adds duration‑based cost. Attach voice track to video from the Studio timeline.
Use public asset URLs or fetch metadata:
curl -H "Authorization: Bearer $PERCIFY_API_KEY" \
  https://api.percify.io/v1/avatars/{avatarId}
Embed in your app or generate derived assets.
Dashboard shows per‑feature consumption. For programmatic checks:
curl -H "Authorization: Bearer $PERCIFY_API_KEY" \
  https://api.percify.io/v1/credits/balance

​
Credit Cost Cheatsheet

FeatureBaseVariableNotes
Image Standard (Flux)2—Per output
Image Premium (Imagen3/Reality4)5—Per output
Percify Yourself10—Photo → avatar
Avatar Cast30—Multi‑character scene
Voice Cloning5—One-time per clone
Audio Generation5+1/secIncludes TTS duration
Video Studio30+6/sec >5sFirst 5s in base
Reality Lab20+4/sec >5sCinematic mode
Full rationale: [/percify/credits].

​
Minimal End-to-End Example (Server)

// generate-avatar.ts
import fetch from 'node-fetch';

const API = 'https://api.percify.io/v1';
const KEY = process.env.PERCIFY_API_KEY!;

async function run() {
  // 1. Image
  const imgRes = await fetch(`${API}/images/generate`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ prompt: 'celestial explorer portrait, nebula background' })
  }).then(r => r.json());

  // 2. Video from image
  const vidRes = await fetch(`${API}/videos/from-image`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ imageId: imgRes.id, durationSeconds: 5 })
  }).then(r => r.json());

  // 3. Voice line
  const voiceRes = await fetch(`${API}/audio/generate`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ text: 'Exploring the stars with Percify.', voiceId: 'default' })
  }).then(r => r.json());

  console.log({ imgRes, vidRes, voiceRes });
}

run();

​
Next Steps

Avatar Studio

Workflows & UI

Credits

Pricing logic

API Auth

Authenticate calls

​
Troubleshooting

IssueCauseFix
401 UnauthorizedMissing/invalid API keyRegenerate key in dashboard
Insufficient creditsBalance below feature costPurchase credits or lower duration
Slow video generationHigh concurrency or long durationReduce length or queue workflows
Voice artifactingLow quality source sampleRe‑record with clean background
See [/percify/faq] for more.