Documentação da API EasyCanvasFlow

Aprenda a integrar o EasyCanvasFlow em suas aplicações para gerar imagens e PDFs dinamicamente através de simples requisições.

Visão Geral

A API EasyCanvasFlow permite a geração de mídias (PNG, WebP e PDF) a partir de designs personalizados. Através de requisições GET, os usuários podem modificar parâmetros de objetos renderizados, como texto, imagens e cores, e gerar novas mídias sob demanda.

Recursos Principais

Geração de imagens em diversos formatos (PNG, WebP)
Criação de PDFs com conteúdo personalizado
Modificação dinâmica de textos, imagens e cores via parâmetros de URL
Integração simples com qualquer aplicação via requisições HTTP

Nota

Para utilizar a API, você precisará de uma chave de API válida. Obtenha sua chave no painel de controle após criar uma conta.

Autenticação

A autenticação é realizada através de API keys. Para utilizar a API, é necessário incluir o parâmetro apikey em todas as requisições, contendo a chave de API do usuário.

Sua API key é pessoal e não deve ser compartilhada. Ela identifica suas requisições e é utilizada para contabilizar o uso da API de acordo com seu plano.

# Exemplo de requisição com autenticação
https://api.easycanvasflow.com/create?id=123&apikey=sua_api_key

Segurança

Nunca compartilhe sua chave de API ou inclua-a em código-fonte público. Sempre armazene suas chaves em variáveis de ambiente ou sistemas seguros de gerenciamento de segredos.

Limites de Requisição

Os limites de requisição variam de acordo com seu plano. Consulte a página de preços para ver os limites específicos de cada plano.

Estes limites ajudam a manter a qualidade do serviço para todos os usuários. Se você precisar de limites maiores, considere atualizar para um plano empresarial.

Atenção

Exceder o limite de requisições resultará em um erro 429 (Too Many Requests). Implemente uma lógica de retry com backoff exponencial em sua aplicação para lidar com esses casos.

Como Obter o ID do Design

Para obter o ID do seu design, siga estes passos simples na tela de edição:

Acesse a tela de edição do seu design

Abra o design que você deseja utilizar na API

Localize o botão de Export

Procure pelo ícone de compartilhamento no canto superior direito da tela

Copie o ID do design

O ID será exibido, aperte em copiar ID!

Dica

O ID do design é um identificador único que permite que a API saiba qual design utilizar para gerar a mídia. Mantenha este ID seguro e não o compartilhe publicamente.

GET /create

Este endpoint gera uma nova mídia a partir de um design existente, com a possibilidade de modificar parâmetros dos objetos renderizados.

Endpoint

GET /create

URL Base

https://api.easycanvasflow.com

Parâmetros

A API aceita os seguintes parâmetros para personalizar a geração de mídia:

Parâmetro	Tipo	Obrigatório	Descrição
id	String	Sim	ID do design a ser utilizado
apikey	String	Sim	Chave de API do usuário
format	String	Não	Formato da mídia (png, webp, pdf). Padrão: png
quality	Number	Não	Qualidade da mídia (0-1). Padrão: 1
Parâmetros para qualquer objeto (texto ou imagem)
[id]-color	String	Não	Cor do objeto (formato hexadecimal ou nome da cor)
[id]-opacity	Number	Não	Opacidade do objeto (0 a 1)
[id]-angle	Number	Não	Ângulo de rotação em graus
[id]-scale	Number	Não	Escala do objeto (1 = tamanho original)
[id]-left	Number	Não	Posição X do objeto
[id]-top	Number	Não	Posição Y do objeto
Parâmetros específicos para objetos de texto
[id]-value	String	Não	Texto a ser exibido
[id]-size	Number	Não	Tamanho da fonte
[id]-align	String	Não	Alinhamento do texto ('left', 'center', 'right', 'justify')
[id]-font	String	Não	Família da fonte
[id]-style	String	Não	Estilo da fonte ('normal', 'italic')
[id]-weight	String	Não	Peso da fonte ('normal', 'bold')
[id]-decoration	String	Não	Decoração do texto ('underline', 'overline', 'linethrough', 'none')
Parâmetros específicos para objetos de imagem
[id]-url	String	Não	URL da nova imagem

Exemplos de Uso

Aqui estão alguns exemplos práticos de como utilizar a API para gerar mídias personalizadas:

Exemplo com múltiplas modificações de texto

https://api.easycanvasflow.com/create?id=123&apikey=sua_api_key&titulo-value=Promoção+Especial&titulo-color=red&titulo-size=36&titulo-weight=bold&titulo-align=center

Exemplo com posicionamento e transformação

https://api.easycanvasflow.com/create?id=123&apikey=sua_api_key&logo-left=100&logo-top=50&logo-scale=1.5&logo-angle=45&logo-opacity=0.8

Exemplo completo com múltiplos objetos

https://api.easycanvasflow.com/create?id=123&apikey=sua_api_key&titulo-value=Oferta+Imperdível&titulo-color=%23FF5500&titulo-size=42&subtitulo-value=Válido+até+30/04&subtitulo-style=italic&logo-url=https://exemplo.com/logo-promo.png&logo-scale=1.2&fundo-color=%23121212&fundo-opacity=0.9&format=webp&quality=0.9

Dica

Utilize a codificação URL para caracteres especiais em seus parâmetros. Por exemplo, espaços devem ser substituídos por + ou %20.

Objetos Renderizáveis: Texto

Objetos de texto permitem modificar o conteúdo textual exibido no design. Você pode alterar diversos aspectos do texto:

Conteúdo e Cor

[id]-value: Texto a ser exibido
[id]-color: Cor do texto (hex ou nome)
[id]-opacity: Opacidade (0-1)

Fonte e Estilo

[id]-size: Tamanho da fonte
[id]-font: Família da fonte
[id]-style: Estilo ('normal', 'italic')
[id]-weight: Peso ('normal', 'bold')
[id]-decoration: Decoração ('underline', etc.)

Alinhamento

[id]-align: Alinhamento do texto
Valores: 'left', 'center', 'right', 'justify'

Posição e Transformação

[id]-left: Posição X
[id]-top: Posição Y
[id]-angle: Rotação em graus
[id]-scale: Escala (1 = tamanho original)

# Exemplo completo de personalização de texto
https://api.easycanvasflow.com/create?id=123&apikey=sua_api_key&titulo-value=Texto+Personalizado&titulo-color=%23FF0000&titulo-size=32&titulo-font=Arial&titulo-style=italic&titulo-weight=bold&titulo-decoration=underline&titulo-align=center&titulo-left=150&titulo-top=100&titulo-angle=5&titulo-opacity=0.9

Objetos Renderizáveis: Imagem

Objetos de imagem permitem modificar as imagens exibidas no design. Você pode modificar diversos aspectos da imagem:

Conteúdo e Aparência

[id]-url: URL da nova imagem
[id]-opacity: Opacidade (0-1)

Posição e Transformação

[id]-left: Posição X
[id]-top: Posição Y
[id]-angle: Rotação em graus
[id]-scale: Escala (1 = tamanho original)

# Exemplo completo de personalização de imagem
https://api.easycanvasflow.com/create?id=123&apikey=sua_api_key&logo-url=https://exemplo.com/nova-logo.png&logo-left=200&logo-top=150&logo-angle=15&logo-scale=1.2&logo-opacity=0.85

Objetos Renderizáveis: Formas

Objetos de forma (retângulos, círculos, etc.) permitem modificar cores. Você pode modificar diversos aspectos da forma:

Aparência

[id]-color: Cor da forma (hex ou nome)
[id]-opacity: Opacidade (0-1)

Posição e Transformação

[id]-left: Posição X
[id]-top: Posição Y
[id]-angle: Rotação em graus
[id]-scale: Escala (1 = tamanho original)

# Exemplo completo de personalização de forma
https://api.easycanvasflow.com/create?id=123&apikey=sua_api_key&retangulo-color=%2300FF00&retangulo-opacity=0.7&retangulo-left=100&retangulo-top=200&retangulo-angle=30&retangulo-scale=1.5

Tratamento de Erros

A API retorna códigos de status HTTP padrão para indicar o sucesso ou falha de uma requisição. Abaixo estão os códigos de status que você pode receber:

Código	Status	Descrição
200	OK	Requisição bem-sucedida
400	Bad Request	Requisição inválida (parâmetros ausentes ou incorretos)
401	Unauthorized	Chave de API inválida
404	Not Found	Design não encontrado
429	Too Many Requests	Limite de requisições excedido
500	Internal Server Error	Erro interno do servidor

Em caso de erro, a API retornará uma resposta JSON com detalhes sobre o problema:

{
  "error": true,
  "code": 400,
  "message": "Parâmetro 'id' é obrigatório"
}

Códigos de Status

Além dos códigos de status HTTP, a API pode retornar códigos de status específicos no corpo da resposta para fornecer informações mais detalhadas sobre o resultado da operação.

Resposta de Sucesso

{
  "success": true,
  "url": "https://cdn.easycanvasflow.com/generated/img_123456789.png",
  "format": "png",
  "expiresAt": "2025-04-08T15:30:00Z",
  "metadata": {
    "width": 1200,
    "height": 630,
    "size": 24680
  }
}

Melhores Práticas

Aqui estão algumas recomendações para obter o melhor desempenho e resultados ao utilizar a API EasyCanvasFlow:

Implemente cache: Armazene as URLs geradas para evitar requisições desnecessárias para o mesmo conteúdo.
Respeite os limites: Implemente lógica de retry com backoff exponencial para lidar com erros 429.
Otimize imagens: Ao substituir imagens, utilize arquivos otimizados para melhor desempenho.
Planeje seus designs: Crie designs com IDs de objetos consistentes e bem documentados para facilitar a integração.
Monitore o uso: Acompanhe o consumo de créditos no painel para evitar surpresas.

Esta documentação está em constante evolução. Para mais informações, entre em contato com nosso suporte.