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

# Conceitos fundamentais

> Projeto, API key, resolve, job, plataformas e envelope da API

## Projeto

Um **projeto** agrupa chaves de API, uso e jobs. Cada integração deve ter seu próprio projeto no [Developer Dashboard](https://shappire.tools/developer).

## API key

Chaves `shp_live_...` autenticam integrações server-to-server. Não usam sessão do dashboard.

| Conceito      | Descrição                                            |
| ------------- | ---------------------------------------------------- |
| Prefixo       | `shp_live_` em produção                              |
| Header        | `X-API-Key` (recomendado) ou `Authorization: Bearer` |
| Escopos       | `media:resolve`, `media:download`                    |
| Armazenamento | Apenas hash no servidor — secret só na criação       |

## Resolve vs download

| Etapa    | Endpoint               | Síncrono?   | Saída                             |
| -------- | ---------------------- | ----------- | --------------------------------- |
| Resolve  | `POST /media/resolve`  | Sim         | `data.id`, metadados, `formats[]` |
| Download | `POST /media/download` | Não (`202`) | `job_id`                          |
| Status   | `GET /jobs/{id}`       | Sim         | Progresso e URL final             |

O resolve tem TTL de 1 hora — use `data.id` como `media_id` dentro da janela ou passe `url` direto no download.

## Plataformas

Cada host suportado (TikTok, Instagram, SoundCloud, …) expõe **capabilities**: `video`, `audio`, `image`, `metadata`. YouTube não entra nessa lista — consulte `GET /platforms` para a lista atual.

Engines internos (`native`, `yt-dlp`) não são expostos na API pública.

## Envelope

* Sucesso: `{ "data": ... }`
* Erro: `{ "error": { "code", "message", "request_id" } }`

Detalhes: [Visão geral](/api-reference/overview).

## Limites

Por projeto: 1.000 req/dia, 2 jobs simultâneos. Por chave: 60 req/min. Veja [Rate limiting](/api-reference/rate-limiting).