> ## Documentation Index
> Fetch the complete documentation index at: https://docs.percify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Percify Quickstart

> From signup to your first animated, voiced avatar in minutes

## Overview

Follow these steps to experience the full Percify creation loop quickly.

<AccordionGroup>
  <Accordion icon="user-plus" title="1. Create account & sign in">
    Sign up on the Percify dashboard. Your starter credits appear automatically; if not, visit Billing to purchase a pack.
  </Accordion>

  <Accordion icon="key" title="2. Get API key">
    Navigate to Settings → API Keys. Create a key and store it securely. Use it in the `Authorization: Bearer <key>` header for server-side calls.
  </Accordion>

  <Accordion icon="image" title="3. Generate your first avatar image">
    Use the Avatar Studio UI or call the image generation endpoint:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion icon="wand-magic-sparkles" title="4. Refine & publish">
    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.
  </Accordion>

  <Accordion icon="film" title="5. Convert image → short video">
    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.
  </Accordion>

  <Accordion icon="microphone" title="6. Clone a voice & generate audio">
    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.
  </Accordion>

  <Accordion icon="share" title="7. Share, embed or fetch via API">
    Use public asset URLs or fetch metadata:

    ```bash theme={null}
    curl -H "Authorization: Bearer $PERCIFY_API_KEY" \
      https://api.percify.io/v1/avatars/{avatarId}
    ```

    Embed in your app or generate derived assets.
  </Accordion>

  <Accordion icon="coins" title="8. Monitor credit usage">
    Dashboard shows per‑feature consumption. For programmatic checks:

    ```bash theme={null}
    curl -H "Authorization: Bearer $PERCIFY_API_KEY" \
      https://api.percify.io/v1/credits/balance
    ```
  </Accordion>
</AccordionGroup>

## Credit Cost Cheatsheet

| Feature                          | Base | Variable   | Notes                 |
| -------------------------------- | ---- | ---------- | --------------------- |
| Image Standard (Flux)            | 2    | —          | Per output            |
| Image Premium (Imagen3/Reality4) | 5    | —          | Per output            |
| Percify Yourself                 | 10   | —          | Photo → avatar        |
| Avatar Cast                      | 30   | —          | Multi‑character scene |
| Voice Cloning                    | 5    | —          | One-time per clone    |
| Audio Generation                 | 5    | +1/sec     | Includes TTS duration |
| Video Studio                     | 30   | +6/sec >5s | First 5s in base      |
| Reality Lab                      | 20   | +4/sec >5s | Cinematic mode        |

Full rationale: \[/percify/credits].

## Minimal End-to-End Example (Server)

```typescript theme={null}
// 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

<CardGroup cols={3}>
  <Card title="Avatar Studio" icon="camera" href="/percify/avatar-studio">Workflows & UI</Card>
  <Card title="Credits" icon="coins" href="/percify/credits">Pricing logic</Card>
  <Card title="API Auth" icon="key" href="/percify/api-auth">Authenticate calls</Card>
</CardGroup>

## Troubleshooting

| Issue                 | Cause                             | Fix                                |
| --------------------- | --------------------------------- | ---------------------------------- |
| 401 Unauthorized      | Missing/invalid API key           | Regenerate key in dashboard        |
| Insufficient credits  | Balance below feature cost        | Purchase credits or lower duration |
| Slow video generation | High concurrency or long duration | Reduce length or queue workflows   |
| Voice artifacting     | Low quality source sample         | Re‑record with clean background    |

See \[/percify/faq] for more.