Visão geral

A Shappire Media API cobre resolução de metadados de mídia, enfileiramento de downloads assíncronos e consulta de jobs — tudo sob o prefixo /v1.

Base URL

https://api.shappire.tools/v1

Desenvolvimento local: http://localhost:8080/v1Todas as rotas da API pública usam esse prefixo. Chaves de produção usam o prefixo shp_live_; em ambiente local (não-produção), o prefixo é shp_test_.

Endpoints disponíveis

Método	Rota	Auth	Escopo
`GET`	`/health`	Pública	—
`GET`	`/platforms`	API key	—
`POST`	`/media/resolve`	API key	`media:resolve`
`POST`	`/media/download`	API key	`media:download`
`GET`	`/jobs/{jobId}`	API key	—

Lista detalhada: Rotas da API.

Autenticação (API key)

Crie a chave no dashboard: Developer → Projetos → API Keys.

curl https://api.shappire.tools/v1/platforms \
  -H "X-API-Key: $SHAPPIRE_API_KEY"

Authorization: Bearer shp_live_... também é aceito. Prefira X-API-Key em integrações novas.

API keys são credenciais secretasTrate shp_live_... como senha de banco de dados. Qualquer pessoa com a chave pode consumir sua cota e enfileirar downloads no seu projeto.Nunca:

commite no Git (.env no .gitignore)
coloque em código frontend (React, Vue, Svelte, Next.js client components)
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

Arquitetura correta

Browser / App
      ↓
Backend do cliente (seu servidor)
      ↓  X-API-Key: shp_live_... (variável de ambiente)
Shappire API

O usuário final nunca vê a chave. Seu backend valida a sessão do usuário e chama a Shappire server-to-server.

Arquitetura incorreta

Browser / App
      ↓  X-API-Key: shp_live_... (hardcoded ou em bundle JS)
Shappire API

Qualquer usuário pode abrir DevTools → Network, copiar a chave e usar fora do seu controle.

Onde armazenar

Ambiente	Recomendação
Servidor Node/Python/Go	`process.env.SHAPPIRE_API_KEY` / `os.environ`
Docker / K8s	Secret do orchestrator
CI/CD	Secret do pipeline (GitHub Actions, etc.)
Local	`.env` (nunca commitado)

Veja também: Chaves de API · Boas práticas

Envelope de resposta

Sucesso — sempre { "data": ... }:

{
  "data": {
    "id": "med_abc123",
    "platform": "tiktok",
    "title": "Exemplo de vídeo",
    "formats": [
      {
        "id": "video_best",
        "type": "video",
        "quality": "best",
        "container": "mp4"
      }
    ]
  }
}

Erro (rotas /v1/*):

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid.",
    "request_id": "req_7f3a2b1c"
  }
}

O header X-Request-Id repete o request_id quando presente.

Campos omitidos

A API pública não expõe: identificadores internos de projeto, payloads brutos do engine de resolução nem metadados operacionais do worker.

Resolve → Download

O resolve retorna data.id (ex. med_abc123). Use esse valor como media_id no download. TTL padrão: 1 hora.

Rate limiting

Limite	Valor padrão
Requisições/minuto	60 por API key
Requisições/dia	1.000 por projeto
Jobs simultâneos	2 por projeto

Veja Rate limiting.

Exemplo rápido (multi-linguagem)

// Requer SHAPPIRE_API_KEY em process.env
import { resolveMedia, enqueueDownload, waitForJob } from './shappire.js';

const url = 'https://www.tiktok.com/@user/video/7123456789012345678';

const media = await resolveMedia(url);
const format = media.formats.find((f) => f.id === 'video_best')?.id ?? 'video_best';
const jobId = await enqueueDownload(media.id, format);
const job = await waitForJob(jobId);

console.log(job.result.download_url);

import os
# Requer SHAPPIRE_API_KEY em os.environ
url = "https://www.tiktok.com/@user/video/7123456789012345678"

media = resolve_media(url)
job_id = enqueue_download(media["id"], "video_best")
job = wait_for_job(job_id)

print(job["result"]["download_url"])

media, err := ResolveMedia("https://www.tiktok.com/@user/video/7123456789012345678")
if err != nil {
	log.Fatal(err)
}

mediaID, _ := media["id"].(string)
jobID, err := EnqueueDownload(mediaID, "video_best")
if err != nil {
	log.Fatal(err)
}

job, err := WaitForJob(jobID)
if err != nil {
	log.Fatal(err)
}

# 1. Resolver
MEDIA=$(curl -s https://api.shappire.tools/v1/media/resolve \
  -H "X-API-Key: $SHAPPIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.tiktok.com/@user/video/7123456789012345678"}')

MEDIA_ID=$(echo "$MEDIA" | jq -r '.data.id')

# 2. Enfileirar
JOB=$(curl -s -X POST https://api.shappire.tools/v1/media/download \
  -H "X-API-Key: $SHAPPIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"media_id\":\"$MEDIA_ID\",\"format\":\"video_best\"}")

JOB_ID=$(echo "$JOB" | jq -r '.data.job_id')

# 3. Polling
curl https://api.shappire.tools/v1/jobs/$JOB_ID \
  -H "X-API-Key: $SHAPPIRE_API_KEY"

Mapa rápido

Primeira integração

Guia passo a passo completo

Chaves de API

Segurança e autenticação

Plataformas

Suportadas e exclusões (YouTube)

Resolver mídia

POST /media/resolve

Download assíncrono

Jobs e polling

Exemplos por linguagem

JS, Python, Go, PHP, Ruby, Java

Erros e códigos

Todos os error.code

Worker background

Fila + polling + storage

Introdução

Mídia

Endpoints

Endpoints disponíveis

Autenticação (API key)

Arquitetura correta

Arquitetura incorreta

Onde armazenar

Envelope de resposta

Campos omitidos

Resolve → Download

Rate limiting

Exemplo rápido (multi-linguagem)

Mapa rápido

Primeira integração

Chaves de API

Plataformas

Resolver mídia

Download assíncrono

Exemplos por linguagem

Erros e códigos

Worker background

​Endpoints disponíveis

​Autenticação (API key)

​Arquitetura correta

​Arquitetura incorreta

​Onde armazenar

​Envelope de resposta

​Campos omitidos

​Resolve → Download

​Rate limiting

​Exemplo rápido (multi-linguagem)

​Mapa rápido

Primeira integração

Chaves de API

Plataformas

Resolver mídia

Download assíncrono

Exemplos por linguagem

Erros e códigos

Worker background

Endpoints disponíveis

Autenticação (API key)

Arquitetura correta

Arquitetura incorreta

Onde armazenar

Envelope de resposta

Campos omitidos

Resolve → Download

Rate limiting

Exemplo rápido (multi-linguagem)

Mapa rápido