Usando a API flye.win

Início rápido

1. 01

   Crie uma conta

   E-mail e senha ou Google. Criar conta.

2. 02

   Gere uma chave de API

   Em Dashboard → Chaves. A chave completa aparece uma única vez — guarde em um gerenciador de segredos.

3. 03

   Ative um plano na API

   Toda API tem plano Free. Abra a API no catálogo e ative.

4. 04

   Faça a primeira requisição

   $ export FLYE_KEY="flye_sk_…"
   $ curl https://flye.win/v1/utils/uuid -H "Authorization: Bearer $FLYE_KEY"

Autenticação

Envie a chave em um dos dois headers. As chaves começam com flye_sk_ e valem para todas as APIs que você assinar.

Authorization: Bearer flye_sk_…
# ou
X-API-Key: flye_sk_…

Requisições e respostas

• —Base: https://flye.win/v1/<api>
• —Corpos de requisição e resposta em JSON UTF-8 (Content-Type: application/json).
• —Sucesso retorna 2xx com o objeto diretamente, sem envelope.
• —CORS liberado, mas lembre-se: a chave não deve ir para o navegador.

Chaves de teste

Chaves que começam com flye_test_ respondem com os exemplos da documentação de cada endpoint. Não precisam de plano e não gastam quota, então servem para integrar, rodar testes automatizados e CI sem custo.

• —Parâmetros obrigatórios e rotas são conferidos como na API real: um erro de integração aparece já no teste.
• —A resposta é sempre o exemplo, com o header X-Flye-Mode: test. Nada é executado de verdade.
• —Limite próprio: 30 requisições por minuto e 1.000 por dia, por conta.

Crie em Dashboard → Chaves, escolhendo “Teste”. Para produção, troque pela chave flye_sk_: o código continua igual.

SDKs

Clientes oficiais sem dependências, gerados a partir da mesma especificação desta documentação. Tratam autenticação, erros (FlyeError com o code da API), tempo limite e novas tentativas em 429 e falhas de rede.

$ npm install flyewin

import Flye from "flyewin";

const flye = new Flye(); // lê FLYE_API_KEY
const data = await flye.utils.uuid({ count: 2 });

$ pip install flyewin

from flyewin import Flye

flye = Flye()  # lê FLYE_API_KEY
data = flye.utils.uuid(count=2)

Cada API vira um grupo de métodos com o nome do endpoint: flye.cdn.upload(…), flye.stickers.search(…). Os headers de limite da última chamada ficam em flye.lastResponse (JS) e flye.last_response (Python).

OpenAPI

A especificação OpenAPI 3.1 é pública e sempre igual ao que está no ar. Importe no Postman, Insomnia ou Bruno, ou gere um cliente para outra linguagem com o gerador de sua preferência.

https://flye.win/openapi.json            # todas as APIs (em inglês)
https://flye.win/openapi.json?lang=pt-BR # em português
https://flye.win/openapi/<api>.json      # uma API só, ex: /openapi/utils.json

Cada operação tem um operationId estável (utilsHash, cdnUpload) e o exemplo de resposta, que é o mesmo devolvido pelas chaves de teste.

Testar no navegador

A página de cada API tem, em todo endpoint, exemplos prontos em curl, JavaScript, Python, Go e PHP, e um formulário “Testar agora” que faz a chamada de verdade com a sua chave. Use uma chave de teste: ela fica só naquela aba do navegador e não é enviada ao nosso site.

Erros

Todo erro tem o mesmo formato. Use code no seu código; message é para humanos e pode mudar.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Quota mensal do seu plano esgotada."
  }
}

Dica de quem faz: travou num erro? Explique o problema em voz alta pra um pato de borracha (ou pra qualquer coisa na mesa). Metade das vezes a resposta aparece no meio da frase. Se não aparecer, abra um ticket: quem responde é quem escreveu o código.

Limites e quotas

Cada plano define dois limites, contados por conta e por API (não por chave):

• —Rate limit — requisições por minuto, janela fixa de 60 s.
• —Quota — requisições por mês-calendário, zera no dia 1º.

Limite por usuário final

Em planos com esse modelo, como o Scale, não há teto mensal. Envie X-End-User-Id com um identificador estável do usuário da sua plataforma, de preferência um hash, e o limite por minuto passa a valer para cada usuário: se um deles exagerar, só ele recebe 429 com o código end_user_rate_limited, e os demais seguem normalmente.

Chamadas sem o header dividem o limite da conta. Em qualquer outro plano o header é ignorado. Como proteção contra loops, a conta tem uma trava de 60.000 requisições por minuto, que devolve o código platform_protection.

Versionamento

A versão está no caminho (/v1). Dentro de uma versão só fazemos mudanças compatíveis: novos endpoints, novos campos opcionais e novos códigos de erro. Trate campos desconhecidos como ignoráveis. Mudanças incompatíveis vão para /v2 com período de convivência.

Status

GET /v1/status é público, não exige chave e não consome quota. Útil para health checks. O histórico fica na página de status.

curl https://flye.win/v1/status