SDKs oficiais

Instalação

npm install flyewin
# or: pnpm add flyewin · yarn add flyewin · bun add flyewin

pip install flyewin
# or: poetry add flyewin · uv add flyewin

• —JavaScript/TypeScript: Node 18 ou mais novo, Deno e Bun. Funciona com import (ESM) e require (CommonJS), e já vem com os tipos do TypeScript.
• —Python: 3.8 ou mais novo. Usa só a biblioteca padrão, sem requests nem outra dependência.

// CommonJS (require) also works:
const Flye = require("flyewin");
const { FlyeError } = require("flyewin");

# The same client works in scripts, Django, Flask, FastAPI, Celery...
from flyewin import Flye, FlyeError

Primeira chamada

1. 01

   Crie uma chave

   Em Dashboard → Chaves. Para começar, escolha Teste: ela não precisa de plano e não gasta cota.

2. 02

   Guarde a chave numa variável de ambiente

   O SDK lê FLYE_API_KEY sozinho. Assim a chave não fica no código nem vai parar no git.

   # macOS / Linux
   export FLYE_API_KEY="flye_test_…"
   
   # Windows (PowerShell)
   $env:FLYE_API_KEY = "flye_test_…"

3. 03

   Chame a API

   JavaScript Python

   copiar

   import Flye from "flyewin";
   
   const flye = new Flye(); // reads FLYE_API_KEY
   
   const data = await flye.utils.uuid({ count: 2 });
   console.log(data.uuids);

   copiar

   from flyewin import Flye
   
   flye = Flye()  # reads FLYE_API_KEY
   
   data = flye.utils.uuid(count=2)
   print(data["uuids"])

   O método devolve o JSON da resposta já convertido: um objeto em JavaScript e um dict em Python. O formato de cada resposta está na referência, no fim desta página.

Configuração

Tudo é opcional. Sem nada, o cliente lê a chave de FLYE_API_KEY e usa os padrões abaixo. Crie um cliente só e reaproveite na aplicação inteira.

import Flye from "flyewin";

const flye = new Flye(process.env.FLYE_API_KEY, {
  timeout: 10_000, // ms, per request
  maxRetries: 3,
});

// or pass everything in one object:
const other = new Flye({ apiKey: "flye_test_...", maxRetries: 0 });

import os
from flyewin import Flye

flye = Flye(
    os.environ["FLYE_API_KEY"],
    timeout=10.0,  # seconds, per request
    max_retries=3,
)

Variáveis de ambiente lidas pelos dois SDKs: FLYE_API_KEY (a chave) e FLYE_BASE_URL (o endereço). O que você passa no código tem prioridade.

Chaves de teste

Com uma chave flye_test_, o código é exatamente o mesmo: cada método devolve o exemplo de resposta da documentação, sem plano e sem gastar cota (30 requisições por minuto e 1.000 por dia). Parâmetros obrigatórios e rotas são conferidos como na produção, então um erro de integração aparece já no teste.

const flye = new Flye("flye_test_...");

const data = await flye.utils.hash({ text: "hello" });
console.log(flye.lastResponse.headers.get("x-flye-mode")); // "test"

flye = Flye("flye_test_...")

data = flye.utils.hash(text="hello")
print(flye.last_response.headers["x-flye-mode"])  # "test"

Use a chave de teste no desenvolvimento e no CI. Para ir para produção, só troque o valor de FLYE_API_KEY por uma chave flye_sk_.

Tratando erros

Toda falha vira um FlyeError: resposta de erro da API, tempo esgotado, falha de rede ou parâmetro faltando. Decida pelo code, que é estável. A message é para pessoas e pode mudar.

import Flye, { FlyeError } from "flyewin";

const flye = new Flye();

try {
  const data = await flye.utils.hash({ text: "hello" });
} catch (err) {
  if (!(err instanceof FlyeError)) throw err;

  switch (err.code) {
    case "invalid_api_key":
      // wrong or revoked key
      break;
    case "no_subscription":
      // activate a plan for this API in the dashboard
      break;
    case "rate_limited":
    case "quota_exceeded":
      // slow down / upgrade the plan
      break;
    default:
      console.error(err.status, err.code, err.message);
  }
}

from flyewin import Flye, FlyeError

flye = Flye()

try:
    data = flye.utils.hash(text="hello")
except FlyeError as err:
    if err.code == "invalid_api_key":
        ...  # wrong or revoked key
    elif err.code == "no_subscription":
        ...  # activate a plan for this API in the dashboard
    elif err.code in ("rate_limited", "quota_exceeded"):
        ...  # slow down / upgrade the plan
    else:
        print(err.status, err.code, err.message)

Erros do próprio SDK

Estes não vêm da API: o SDK detecta antes ou durante a chamada.

A lista completa dos códigos da API está em Documentação → Erros.

Novas tentativas

O SDK repete sozinho só o que é seguro repetir:

• —Falha de rede e erro 5xx, só em chamadas GET. Um POST (como um upload) nunca é repetido sozinho, para não duplicar.
• —429 com Retry-After de até 60 segundos (limite por minuto), em qualquer método: o SDK espera o tempo pedido e tenta de novo.
• —Nunca repete cota do mês esgotada, chave inválida, falta de plano nem parâmetro errado: tentar de novo não resolveria.
• —Até maxRetries vezes (padrão 2), com espera crescente: cerca de 0,5 s, 1 s, 2 s…

// Whole client:
const flye = new Flye(undefined, { maxRetries: 4 });

// Only this call (0 = never retry):
await flye.cdn.upload({ image, project: "shop" }, { maxRetries: 0 });

# Whole client (0 = never retry):
flye = Flye(max_retries=4)

Em JavaScript dá para mudar por chamada, no segundo argumento. Em Python a configuração vale para o cliente: crie outro cliente se precisar de um comportamento diferente.

Tempo limite e cancelamento

O tempo limite padrão é de 30 segundos por requisição, contando o download da resposta. Mude para o cliente inteiro ou só para uma chamada. Em JavaScript dá também para cancelar com um AbortSignal. Quando o tempo acaba, o erro tem o código timeout.

// Per call, in milliseconds:
await flye.stickers.search({ q: "cat" }, { timeout: 5_000 });

// Cancel with an AbortController (e.g. the user left the page):
const controller = new AbortController();
const pending = flye.stickers.search({ q: "cat" }, { signal: controller.signal });
controller.abort();

# Per call, in seconds:
flye.stickers.search(q="cat", timeout=5)

Limites e cota

Os headers de limite da última resposta ficam no cliente: lastResponse em JavaScript e last_response em Python. Use para mostrar a cota ao usuário ou para diminuir o ritmo antes de chegar no limite.

const data = await flye.utils.uuid();
const h = flye.lastResponse.headers;

console.log(h.get("x-ratelimit-remaining")); // left in this minute
console.log(h.get("x-quota-remaining"));     // left this month

data = flye.utils.uuid()
h = flye.last_response.headers

print(h.get("x-ratelimit-remaining"))  # left in this minute
print(h.get("x-quota-remaining"))      # left this month

Com várias chamadas ao mesmo tempo, lastResponse guarda a que terminou por último. Leia logo depois do await ou use um cliente por tarefa.

Upload de arquivos

Parâmetros do tipo file (como image em cdn.upload) aceitam várias formas. O SDK monta o multipart/form-data e descobre o tipo do arquivo pelo nome.

• —JavaScript: Blob ou File, Buffer/Uint8Array/ArrayBuffer, ou { data, filename, contentType } para dar nome aos bytes.
• —Python: arquivo aberto em modo binário, caminho (str ou Path), bytes, ou a tupla (nome, bytes, tipo).

import { openAsBlob } from "node:fs";
import { readFile } from "node:fs/promises";

// Node 20+: a Blob straight from disk
await flye.cdn.upload({ image: await openAsBlob("photo.jpg"), project: "shop" });

// Any Node: bytes + a file name
await flye.cdn.upload({
  image: { data: await readFile("photo.jpg"), filename: "photo.jpg" },
  project: "shop",
  folder: "products",
});

// A File received by your server (Next.js, Hono, Remix...)
const form = await request.formData();
await flye.cdn.upload({ image: form.get("image"), project: "shop" });

# An open file
with open("photo.jpg", "rb") as f:
    flye.cdn.upload(image=f, project="shop")

# A path (str or pathlib.Path)
flye.cdn.upload(image="photo.jpg", project="shop", folder="products")

# Bytes you already have, with name and type
flye.cdn.upload(image=("photo.jpg", data, "image/jpeg"), project="shop")

Limite por usuário final

Nos planos com limite por usuário final (como o Scale), passe endUserId / end_user_id com um identificador estável de cada usuário da sua plataforma, de preferência um hash. O SDK envia no header X-End-User-Id, e o limite por minuto passa a valer para cada usuário. O parâmetro só existe nos métodos que aceitam o header.

// Scale plan: the per-minute limit applies to each of your users
const data = await flye.stickers.search({
  q: "cat",
  endUserId: hash(user.id), // sent as the X-End-User-Id header
});

# Scale plan: the per-minute limit applies to each of your users
data = flye.stickers.search(
    q="cat",
    end_user_id=hash_id(user.id),  # sent as the X-End-User-Id header
)

TypeScript e tipos

O pacote npm traz index.d.ts: todos os métodos e parâmetros têm tipo e descrição no editor. Os tipos dos parâmetros seguem o padrão <Api><Método>Params, como StickersSearchParams. As respostas são any: o formato de cada uma está na referência abaixo. Em Python, o pacote tem dicas de tipo (py.typed) para mypy, pyright e o editor.

import Flye, { FlyeError, type StickersSearchParams } from "flyewin";

const flye = new Flye();

const params: StickersSearchParams = { q: "cat", limit: 10 };
const data = await flye.stickers.search(params);

# The package ships type hints (py.typed): mypy, pyright and
# your editor show every parameter and its type.
from flyewin import Flye, FileInput

Parâmetros novos

Quando uma API ganha um parâmetro antes de você atualizar o SDK, passe mesmo assim: o que o SDK não conhece segue para a API sem mudança (na query em GET e DELETE, no corpo JSON nos outros). Em Python, flye.request chama qualquer caminho diretamente.

// Parameters newer than your SDK version are sent as-is:
await flye.utils.uuid({ count: 2, someNewOption: true });

# Parameters newer than your SDK version are sent as-is:
flye.utils.uuid(count=2, some_new_option=True)

# Or call any path directly: (name, location, value)
flye.request("GET", "/utils/uuid", [("count", "query", 2)])

Usando num servidor

Crie o cliente uma vez, ao subir a aplicação, e use em todas as rotas. Repasse o erro com o status certo para o seu front-end, sem nunca devolver a chave. O cliente Python é síncrono: em frameworks assíncronos, rode a chamada numa thread.

// server.js (Express). One client for the whole app.
import express from "express";
import Flye, { FlyeError } from "flyewin";

const app = express();
const flye = new Flye();

app.get("/stickers", async (req, res) => {
  try {
    res.json(await flye.stickers.search({ q: String(req.query.q ?? "") }));
  } catch (err) {
    const status = err instanceof FlyeError && err.status ? err.status : 502;
    res.status(status).json({ error: err.code ?? "upstream_error" });
  }
});

app.listen(3000);

# main.py (FastAPI). One client for the whole app.
from fastapi import FastAPI, HTTPException
from fastapi.concurrency import run_in_threadpool
from flyewin import Flye, FlyeError

app = FastAPI()
flye = Flye()

@app.get("/stickers")
async def stickers(q: str):
    try:
        # the client is synchronous: run it off the event loop
        return await run_in_threadpool(flye.stickers.search, q=q)
    except FlyeError as err:
        raise HTTPException(err.status or 502, err.code)

Versões e atualização

Versão atual: 0.1.0. Os SDKs seguem a API /v1: versões novas só adicionam métodos e parâmetros, sem quebrar o código que já existe.

npm install flyewin@latest
pip install --upgrade flyewin

Usa outra linguagem? A especificação OpenAPI gera clientes para Go, PHP, Java, C#, Ruby e outras. E a página de cada API tem exemplos prontos em curl, Go e PHP.

// referência

Referência dos métodos

Todas as APIs e todos os métodos, com os parâmetros nos dois SDKs, um exemplo para copiar e o formato da resposta. Em JavaScript os parâmetros vão num objeto; em Python, como argumentos nomeados. Os que vão no caminho da URL também podem ser passados por posição em Python.

import Flye from "flyewin";

const flye = new Flye(); // reads FLYE_API_KEY

const data = await flye.stickers.search({
  q: "gato",
  maxWaitMs: 300,
  limit: 10,
});
console.log(data);

from flyewin import Flye

flye = Flye()  # reads FLYE_API_KEY

data = flye.stickers.search(
    q="gato",
    max_wait_ms=300,
    limit=10,
)
print(data)

{
  "query": "gato",
  "total_packs": 12,
  "pack": {
    "id": "pk_3f9a1c7e2b8d4a60c1e5",
    "name": "Gatos engraçados",
    "author": "Ana",
    "animated": true,
    "count": 30
  },
  "stickers": [
    {
      "id": "8e1f0c3ab94d27f6a5c1e08d7b3f4a12",
      "url": "https://flye.win/media/stickers/8e1f0c3ab94d27f6a5c1e08d7b3f4a12.webp",
      "format": "webp",
      "animated": true
    }
  ]
}

import Flye from "flyewin";

const flye = new Flye(); // reads FLYE_API_KEY

const data = await flye.stickers.listPacks({
  q: "gato",
  maxWaitMs: 300,
  limit: 5,
});
console.log(data);

from flyewin import Flye

flye = Flye()  # reads FLYE_API_KEY

data = flye.stickers.list_packs(
    q="gato",
    max_wait_ms=300,
    limit=5,
)
print(data)

{
  "query": "gato",
  "total": 12,
  "page": 1,
  "packs": [
    {
      "id": "pk_3f9a1c7e2b8d4a60c1e5",
      "name": "Gatos engraçados",
      "author": "Ana",
      "animated": true,
      "count": 30,
      "cover": "https://flye.win/media/stickers/8e1f0c3ab94d27f6a5c1e08d7b3f4a12.webp"
    }
  ]
}

import Flye from "flyewin";

const flye = new Flye(); // reads FLYE_API_KEY

const data = await flye.stickers.getPack({ id: "<id>" });
console.log(data);

from flyewin import Flye

flye = Flye()  # reads FLYE_API_KEY

data = flye.stickers.get_pack("<id>")
print(data)

{
  "pack": {
    "id": "pk_3f9a1c7e2b8d4a60c1e5",
    "name": "Gatos engraçados",
    "author": "Ana",
    "animated": true,
    "count": 30
  },
  "stickers": [
    {
      "id": "8e1f0c3ab94d27f6a5c1e08d7b3f4a12",
      "url": "https://flye.win/media/stickers/8e1f0c3ab94d27f6a5c1e08d7b3f4a12.webp",
      "format": "webp",
      "animated": true
    }
  ]
}

import { openAsBlob } from "node:fs";
import Flye from "flyewin";

const flye = new Flye(); // reads FLYE_API_KEY

const data = await flye.cdn.upload({
  image: await openAsBlob("photo.jpg"),
  project: "<project>",
});
console.log(data);

from flyewin import Flye

flye = Flye()  # reads FLYE_API_KEY

data = flye.cdn.upload(
    image=open("photo.jpg", "rb"),
    project="<project>",
)
print(data)

{
  "id": "6f1c2a9e-4b7d-4e1a-9c3f-2d8b7a6e5f40",
  "project": "loja",
  "folder": "produtos",
  "filename": "1743580800000000000.jpg",
  "original_name": "tenis-azul.jpg",
  "url": "https://cdn.flye.win/images/fw_9c41d2e07ab3f5168e2d/produtos/1743580800000000000.jpg",
  "size": 204800,
  "content_type": "image/jpeg",
  "created_at": "2026-11-02T13:30:00Z"
}

import Flye from "flyewin";

const flye = new Flye(); // reads FLYE_API_KEY

const data = await flye.cdn.listProjects();
console.log(data);

from flyewin import Flye

flye = Flye()  # reads FLYE_API_KEY

data = flye.cdn.list_projects()
print(data)

{
  "projects": [
    { "name": "loja", "images": 128, "bytes": 52428800, "created_at": "2026-10-01T12:00:00Z" }
  ]
}

import Flye from "flyewin";

const flye = new Flye(); // reads FLYE_API_KEY

const data = await flye.cdn.createProject({ name: "<name>" });
console.log(data);

from flyewin import Flye

flye = Flye()  # reads FLYE_API_KEY

data = flye.cdn.create_project(name="<name>")
print(data)

{ "name": "loja", "images": 0, "bytes": 0, "created_at": "2026-11-02T13:30:00Z" }

import Flye from "flyewin";

const flye = new Flye(); // reads FLYE_API_KEY

const data = await flye.cdn.getProject({ project: "<project>" });
console.log(data);

from flyewin import Flye

flye = Flye()  # reads FLYE_API_KEY

data = flye.cdn.get_project("<project>")
print(data)

{
  "project": "loja",
  "folders": [{ "name": "produtos", "images": 96 }],
  "images": [{
    "id": "6f1c2a9e-4b7d-4e1a-9c3f-2d8b7a6e5f40",
    "project": "loja",
    "folder": "produtos",
    "filename": "1743580800000000000.jpg",
    "original_name": "tenis-azul.jpg",
    "url": "https://cdn.flye.win/images/fw_9c41d2e07ab3f5168e2d/produtos/1743580800000000000.jpg",
    "size": 204800,
    "content_type": "image/jpeg",
    "created_at": "2026-11-02T13:30:00Z"
  }],
  "pagination": { "page": 1, "per_page": 20, "total": 96, "total_pages": 5 }
}

import Flye from "flyewin";

const flye = new Flye(); // reads FLYE_API_KEY

const data = await flye.cdn.getImage({ id: "<id>" });
console.log(data);

from flyewin import Flye

flye = Flye()  # reads FLYE_API_KEY

data = flye.cdn.get_image("<id>")
print(data)

{
  "id": "6f1c2a9e-4b7d-4e1a-9c3f-2d8b7a6e5f40",
  "project": "loja",
  "folder": "produtos",
  "filename": "1743580800000000000.jpg",
  "original_name": "tenis-azul.jpg",
  "url": "https://cdn.flye.win/images/fw_9c41d2e07ab3f5168e2d/produtos/1743580800000000000.jpg",
  "size": 204800,
  "content_type": "image/jpeg",
  "created_at": "2026-11-02T13:30:00Z"
}

import Flye from "flyewin";

const flye = new Flye(); // reads FLYE_API_KEY

const data = await flye.cdn.deleteImage({ id: "<id>" });
console.log(data);

from flyewin import Flye

flye = Flye()  # reads FLYE_API_KEY

data = flye.cdn.delete_image("<id>")
print(data)

{ "deleted": true, "id": "6f1c2a9e-4b7d-4e1a-9c3f-2d8b7a6e5f40" }

import Flye from "flyewin";

const flye = new Flye(); // reads FLYE_API_KEY

const data = await flye.cdn.deleteProject({ project: "<project>" });
console.log(data);

from flyewin import Flye

flye = Flye()  # reads FLYE_API_KEY

data = flye.cdn.delete_project("<project>")
print(data)

{ "deleted": true, "project": "loja", "images": 128 }

import Flye from "flyewin";

const flye = new Flye(); // reads FLYE_API_KEY

const data = await flye.cdn.getUsage();
console.log(data);

from flyewin import Flye

flye = Flye()  # reads FLYE_API_KEY

data = flye.cdn.get_usage()
print(data)

{
  "storage": { "used_bytes": 52428800, "limit_bytes": 5368709120 },
  "max_file_bytes": 20971520,
  "images": 128,
  "projects": { "used": 1, "limit": 5 }
}

import Flye from "flyewin";

const flye = new Flye(); // reads FLYE_API_KEY

const data = await flye.utils.uuid({ count: 2, version: 7 });
console.log(data);

from flyewin import Flye

flye = Flye()  # reads FLYE_API_KEY

data = flye.utils.uuid(count=2, version=7)
print(data)

{
  "version": 7,
  "uuids": [
    "019a3c1e-7b2d-7c41-9f0e-5d8a21c4b6e3",
    "019a3c1e-7b2d-7f88-a1c2-0e93b7d45f12"
  ]
}

import Flye from "flyewin";

const flye = new Flye(); // reads FLYE_API_KEY

const data = await flye.utils.hash({ text: "flye", algo: "sha256" });
console.log(data);

from flyewin import Flye

flye = Flye()  # reads FLYE_API_KEY

data = flye.utils.hash(text="flye", algo="sha256")
print(data)

{
  "algo": "sha256",
  "hex": "9a5c3b4f1f8e0d6c…"
}

import Flye from "flyewin";

const flye = new Flye(); // reads FLYE_API_KEY

const data = await flye.utils.base64({ text: "<text>" });
console.log(data);

from flyewin import Flye

flye = Flye()  # reads FLYE_API_KEY

data = flye.utils.base64(text="<text>")
print(data)

{
  "mode": "encode",
  "result": "aGVsbG8sIHdvcmxk"
}

import Flye from "flyewin";

const flye = new Flye(); // reads FLYE_API_KEY

const data = await flye.utils.ip();
console.log(data);

from flyewin import Flye

flye = Flye()  # reads FLYE_API_KEY

data = flye.utils.ip()
print(data)

{
  "ip": "203.0.113.24",
  "user_agent": "curl/8.7.1"
}