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

# Primeira integração

> Do zero ao primeiro upload com a v0x API

Este guia leva você da conta v0x ao primeiro arquivo hospedado via API. Tempo estimado: 10 minutos.

<Info>
  **Base URL**

  ```
  https://api.v0x.lol/api/v1
  ```

  Desenvolvimento local: `http://localhost:8080/api/v1`

  Health check (sem prefixo `/api/v1`): `GET https://api.v0x.lol/health`

  Chaves de produção usam o prefixo `v0x_live_`.
</Info>

## Pré-requisitos

* Conta Google para login em [dash.v0x.lol](https://dash.v0x.lol/login)
* `curl` ou cliente HTTP no seu ambiente
* Um arquivo de teste (PNG, PDF, etc.)

<Danger>
  **API keys são credenciais secretas**

  Trate `v0x_live_...` como senha de banco de dados. Qualquer pessoa com a chave pode fazer upload e consumir sua quota de storage.

  **Nunca:**

  * commite no Git (`.env` no `.gitignore`)
  * coloque em código frontend (React, Vue, Svelte)
  * envie em apps mobile sem proxy backend
  * armazene em `localStorage`, `sessionStorage` ou cookies do browser
  * exponha em URLs, query strings ou repositórios públicos
</Danger>

## Arquitetura correta

```
Browser / App / ShareX
      ↓
Backend do cliente (seu servidor) — opcional para ShareX direto
      ↓  Authorization: Bearer v0x_live_...
v0x API
```

Para integrações web, o usuário final faz login via Google no dashboard. Scripts e ShareX usam API key server-side ou localmente no cliente desktop.

## Onde armazenar

| Ambiente                | Recomendação                                     |
| ----------------------- | ------------------------------------------------ |
| Servidor Node/Python/Go | `process.env.V0X_API_KEY` / `os.environ`         |
| Docker / K8s            | Secret do orchestrator                           |
| CI/CD                   | Secret do pipeline (GitHub Actions, etc.)        |
| ShareX                  | Campo `Authorization` no `.sxcu` (máquina local) |

Veja também: [Chaves de API](/pages/guides/authentication) · [Boas práticas](/pages/guides/boas-praticas)

***

## 1. Criar conta

1. Acesse [dash.v0x.lol/login](https://dash.v0x.lol/login)
2. Clique em **Continue with Google**
3. Após o redirect, você estará em `/dashboard`

***

## 2. Criar uma API key

1. Abra [API Keys](https://dash.v0x.lol/dashboard/api-keys)
2. Clique em **Create key**
3. Dê um nome (ex. `ShareX` ou `Worker Produção`)
4. Copie o valor `v0x_live_...` — ele aparece **uma única vez**

***

## 3. Guardar a chave

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
# Linux / macOS
export V0X_API_KEY=v0x_live_SUA_CHAVE_AQUI

# Windows PowerShell
$env:V0X_API_KEY = "v0x_live_SUA_CHAVE_AQUI"
```

***

## 4. Testar health (sem auth)

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl https://api.v0x.lol/health
```

Resposta esperada:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "status": "ok",
  "db": "ok",
  "storage": "ok"
}
```

***

## 5. Fazer upload

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl -X POST https://api.v0x.lol/api/v1/files \
  -H "Authorization: Bearer $V0X_API_KEY" \
  -F "file=@./screenshot.png"
```

Resposta `201`:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "screenshot.png",
  "mime_type": "image/png",
  "size_bytes": 248103,
  "url": "https://cdn.v0x.lol/uploads/...",
  "created_at": "2026-09-15T23:00:00Z"
}
```

O campo `url` é o link direto público via CDN.

***

## 6. Listar arquivos

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl "https://api.v0x.lol/api/v1/files?page=1&limit=20" \
  -H "Authorization: Bearer $V0X_API_KEY"
```

***

## 7. Excluir arquivo

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl -X DELETE "https://api.v0x.lol/api/v1/files/SEU_FILE_ID" \
  -H "Authorization: Bearer $V0X_API_KEY"
```

***

## Próximos passos

* [Chaves de API](/pages/guides/authentication)
* [ShareX](/pages/guides/sharex)
* [Rate limiting](/api-reference/rate-limiting)
* [API Reference](/api-reference/overview)