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

# Pricing

> Usage-based pricing with clear costs and guidance for managing spend.

Vinci uses simple usage-based pricing.

* Video generation: \$0.05 per second of generated video
* API management: Included
* Usage monitoring: Included

Info
All prices in USD. Costs are calculated based on actual processing time.

## Check balance

```http title="Endpoint" theme={"system"}
GET /api/v1/billing/balance
```

```http title="Authentication" theme={"system"}
Authorization: Bearer sk-your-api-key-here
```

```json title="Response" theme={"system"}
{
  "balance_usd": 25.50,
  "total_spent_usd": 134.75
}
```

<CodeGroup>
  ```curl cURL theme={"system"}
  curl -X GET "https://tryvinci.com/api/v1/billing/balance" \
    -H "Authorization: Bearer sk-your-api-key-here"
  ```

  ```python check_balance.py theme={"system"}
  import requests

  url = "https://tryvinci.com/api/v1/billing/balance"
  headers = {"Authorization": "Bearer sk-your-api-key-here"}

  r = requests.get(url, headers=headers)
  r.raise_for_status()
  balance = r.json()
  print(f"Current balance: ${balance['balance_usd']:.2f}")
  print(f"Total spent: ${balance['total_spent_usd']:.2f}")
  ```

  ```javascript check_balance.js theme={"system"}
  const r = await fetch("https://tryvinci.com/api/v1/billing/balance", {
    headers: { "Authorization": "Bearer sk-your-api-key-here" },
  });
  if (!r.ok) throw new Error(`HTTP ${r.status}`);
  const balance = await r.json();
  console.log(`Current balance: $${balance.balance_usd.toFixed(2)}`);
  console.log(`Total spent: $${balance.total_spent_usd.toFixed(2)}`);
  ```
</CodeGroup>

## Usage statistics

```http title="Endpoint" theme={"system"}
GET /api/v1/billing/usage?days={days}
```

```http title="Authentication" theme={"system"}
Authorization: Bearer sk-your-api-key-here
```

```json title="Response" theme={"system"}
{
  "period_days": 30,
  "total_requests": 156,
  "total_seconds": 420.5,
  "total_cost_usd": 21.025,
  "current_balance_usd": 25.50,
  "total_spent_usd": 134.75
}
```

<CodeGroup>
  ```curl cURL theme={"system"}
  curl -X GET "https://tryvinci.com/api/v1/billing/usage?days=7" \
    -H "Authorization: Bearer sk-your-api-key-here"
  ```

  ```python usage_stats.py theme={"system"}
  import requests

  url = "https://tryvinci.com/api/v1/billing/usage?days=7"
  headers = {"Authorization": "Bearer sk-your-api-key-here"}

  r = requests.get(url, headers=headers)
  r.raise_for_status()
  usage = r.json()

  print(f"Usage for last {usage['period_days']} days:")
  print(f"- Total requests: {usage['total_requests']}")
  print(f"- Total video seconds: {usage['total_seconds']}")
  print(f"- Total cost: ${usage['total_cost_usd']:.2f}")
  print(f"- Current balance: ${usage['current_balance_usd']:.2f}")
  ```

  ```javascript usage_stats.js theme={"system"}
  const r = await fetch("https://tryvinci.com/api/v1/billing/usage?days=7", {
    headers: { "Authorization": "Bearer sk-your-api-key-here" },
  });
  if (!r.ok) throw new Error(`HTTP ${r.status}`);
  const usage = await r.json();

  console.log(`Usage for last ${usage.period_days} days:`);
  console.log(`- Total requests: ${usage.total_requests}`);
  console.log(`- Total video seconds: ${usage.total_seconds}`);
  console.log(`- Total cost: $${usage.total_cost_usd.toFixed(2)}`);
  console.log(`- Current balance: $${usage.current_balance_usd.toFixed(2)}`);
  ```
</CodeGroup>

## Balance check helper

<CodeGroup>
  ```python balance_check.py theme={"system"}
  import requests

  def check_balance_for_video(duration_seconds, api_key):
      balance_url = "https://tryvinci.com/api/v1/billing/balance"
      headers = {"Authorization": f"Bearer {api_key}"}
      r = requests.get(balance_url, headers=headers)
      r.raise_for_status()
      balance = r.json()

      estimated_cost = duration_seconds * 0.05
      if balance["balance_usd"] < estimated_cost:
          return False
      return True
  ```

  ```javascript balance_check.js theme={"system"}
  async function checkBalanceForVideo(durationSeconds, apiKey) {
    const r = await fetch("https://tryvinci.com/api/v1/billing/balance", {
      headers: { "Authorization": `Bearer ${apiKey}` },
    });
    if (!r.ok) throw new Error(`HTTP ${r.status}`);
    const balance = await r.json();
    const estimated = durationSeconds * 0.05;
    return balance.balance_usd >= estimated;
  }
  ```
</CodeGroup>

## Error handling

When balance is insufficient, the API may return 402.

```json title="Insufficient balance response" theme={"system"}
{
  "detail": "Insufficient balance. Current balance: $1.25, required: $2.50"
}
```

<CodeGroup>
  ```python handle_402.py theme={"system"}
  import requests

  def make_video_request(prompt, duration, api_key):
      url = "https://tryvinci.com/api/v1/generate/text-to-video"
      headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
      data = {"prompt": prompt, "duration_seconds": duration}
      r = requests.post(url, headers=headers, json=data)
      if r.status_code == 402:
          print(f"Insufficient balance: {r.json().get('detail')}")
          return None
      r.raise_for_status()
      return r.json()
  ```

  ```javascript handle_402.js theme={"system"}
  async function makeVideoRequest(prompt, duration, apiKey) {
    const url = "https://tryvinci.com/api/v1/generate/text-to-video";
    const r = await fetch(url, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ prompt, duration_seconds: duration }),
    });
    if (r.status === 402) {
      const err = await r.json();
      console.log(`Insufficient balance: ${err.detail}`);
      return null;
    }
    if (!r.ok) throw new Error(`HTTP ${r.status}`);
    return await r.json();
  }
  ```
</CodeGroup>

## Cost optimization tips

* Use shorter durations during development.
* Poll status every 5–10 seconds and implement retry backoff.
* Monitor usage weekly and set balance alerts.