Documentação da API

Todas as requisições de API são requisições HTTP padrão para URLs estilo REST. As respostas são JSON ou uma imagem (ao buscar o resultado).

Autenticação

A API usa autenticação padrão HTTP básica de acesso. Todas as requisições para a API precisarão incluir suas Credenciais de API, com o Id de API como usuário e a Chave de API como a senha. Note que ClippingMagic.js somente usa o Id de API, para não revelar a Chave de API para os seus usuários.

Segurança

Todas as requisições dever ser feitas sobre HTTPS e você deve autenticar todas elas.

Sua biblioteca de cliente HTTP deve aceitar Indicação de Nome do Servidor (SNI) para fazer requisições corretamente. Se você estiver recebendo erros de handshake estranhos, provavelmente esta é a causa.

Back-end contra front-end

Note que todas as operações de download ocorrem no back-end, mas todas as operações de recorte acontecem no cliente web (front-end) usando ClippingMagic.js.

Essa divisão protege sua chave de API, além de possibilitar uma experiência contínua para o usuário do seu site.

Limitação de velocidade

O uso da API tem limite de velocidade generoso e não há tetos além do seus créditos de API.

Durante as operações conduzidas pelo usuário final, é improvável que você tenha limitações de velocidade, pois o uso é adaptado pelo sistema de forma transparente.

No entanto, para trabalhos em lote, recomendamos começar com no máximo cinco ramificações e adicionar uma nova ramificação a cada cinco minutos, até atingir o nível de paralelismo desejado. Se você precisa de mais de 100 ramificações simultâneas, fale conosco antes de começar.

Se enviar requisições em excesso, você começará a receber respostas do tipo 429 Too Many Requests. Se isso ocorrer, você deverá aplicar um algoritmo de back off linear: na primeira resposta desse tipo, aguarde 5 segundos até reenviar a requisição seguinte. Na segunda resposta 429 consecutiva, aguarde 2 x 5=10 segundos até reenviar a requisição seguinte. Na terceira, aguarde 3 x 5=15 segundos, e assim por diante.

Você poderá reinicializar o contador de back off após o processamento satisfatório de uma requisição, e o back off deve ser aplicado ramificação a ramificação, ou seja, as ramificações devem operar independentemente.

Experimente

Todas as ações de API têm exemplos de formulário HTML / link que você pode experimentar diretamente no seu navegador. Os exemplos cURL usam suas Credenciais de API se você já se cadastrou. Assim, basta copiar e colar no seu terminal para executá-los.

Objeto JSON de erro

Usamos status HTTP convencionais para indicar êxito ou falha de uma requisição de API e incluir informações importantes sobre erro no objeto JSON de erro retornado.

Tentamos sempre retornar um objeto JSON de erro com qualquer requisição problemática. Teoricamente, no entanto, sempre é possível haver falhas internas no servidor que resultam em uma resposta de erro não JSON.

Atributos

statusO status HTTP da resposta, repetido aqui para auxílio na depuração de erros.
codeCódigo de erro interno do Clipping Magic.
messageMensagem de erro inteligível, para ajudar na depuração.

Se o status HTTP da sua requisição for 200, não haverá retorno de Objeto JSON de erro e você pode supor com segurança que a requisição foi, de forma geral, exitosa.

Algumas bibliotecas de cliente HTTP suscitam exceções para status HTTP no intervalo 400-599. Você deverá obter essas exceções e tratá-las adequadamente.

HTTP StatusSignificado
200-299

Êxito

301-303

Ao fazer download de resultados: você está sendo redirecionado para o local real de armazenamento de resultados. Não haverá retorno de objeto JSON de erro. Você deve configurar sua biblioteca HTTP de cliente para seguir os redirecionamentos ao fazer download de resultados.

400-499

Há um problema com as informações fornecidas na requisição, por exemplo, a falta de um parâmetro. Analise a mensagem de erro para resolver como solucioná-lo.

500-599

Houve um erro interno no Clipping Magic. Aguarde alguns momentos e tente novamente. Se o problema persistir, envie-nos um e-mail.

Exemplo de resposta de erro

{
  "error" : {
    "status" : 400,
    "code" : 1006,
    "message" : "Failed to read the supplied image. "
  }
}

Objeto JSON de erro

Registros de imagem são representados de modo uniforme com um objeto JSON, retornado em várias ações da API.

Atributos

id

Identificador único da imagem. Necessário para permitir que usuários editem a imagem e façam download do resultado.

secret

A chave secreta necessária para editar esta imagem com ClippingMagic.js

resultRevision

Inteiro indicando a revisão mais recente disponível para download (0 = ainda não há resultado disponível).

Permite determinar se há um resultado mais recente para esta imagem do que o que você fez download.

originalFilename

Uma cadeia de caracteres contendo o nome do arquivo fornecido no upload da imagem original.

test

true significa que esta é uma imagem de teste com processamento gratuito, mas o resultado terá uma marca d'água.

false significa que esta é uma imagem de produção, cujo processamento tem um custo em créditos, mas o resultado não terá marca-d'água.

Exemplo

{
  "id" : 2345,
  "secret" : "image_secret",
  "resultRevision" : 0,
  "originalFilename" : "image.jpg",
  "test" : false
}

Upload POST https://clippingmagic.com/api/v1/images

O upload de uma imagem é feito por meio de um upload de arquivo HTTP POST padrão. Este endpoint deve ser chamado do seu backend, não do javascript da sua página da web. Lembre-se de que o Content-Type deve ser multipart/form-data

Parâmetros

image

O arquivo de imagem para fazer upload, que deve ser .bmp, .gif, .jpeg, .png ou tiff.

O tamanho máximo para upload de imagem (= largura × altura) é 33.554.432pixels, que é reduzido para 4.194.404pixels, a menos que seja substituído pelo maxPixels abaixo. Reduza suas imagens para esse último tamanho ou menos antes de fazer upload.

Opcional
test

Informe true para indicar que esta é uma imagem de teste. Imagens de teste têm processamento gratuito, mas o resultado incorpora uma marca d'água.

Opcional
format

format=json (padrão): não há geração de resultado automático de recorte e o objeto JSON de imagem é retornado. Use esta opção quando há um um operador humano revisando e possivelmente retocando o recorte usando ClippingMagic.js.

format=result gera e recupera o resultado do recorte automático.

format=clipping_path_svg gera o resultado do recorte automático e recupera o demarcador de corte (SVG).

format=alpha_mask_png gera o resultado do recorte automático e recupera a máscara alfa (PNG). A máscara alfa tem o mesmo tamanho da imagem original. A aplicação à imagem original não gera o resultado, pois a Proteção de borda e o Removedor de halo aprimoram as cores das delimitações.

O id e o secret são retornados nos cabeçalhos x-amz-meta-id e x-amz-meta-secret ao recuperar um resultado que não seja JSON. Armazene isso para poder avaliar e editar o resultado usando ClippingMagic.js.

Recuperar o objeto JSON de imagem não debita a sua conta. Você só é cobrado quando faz download de resultados de produção.

Opcional
maxPixels

Inteiro, mín: 1.000.000 pixels, máx: 8.388.708 pixels, padrão: 4.194.404 pixels.

Altera o tamanho máximo de imagem (= largura × altura) usado ao redimensionar a imagem após o upload.

No modo de teste, você pode fazer upload de imagens sem ter uma assinatura. Porém, para fazer upload de imagens de produção via a API, você precisará de uma assinatura de API válida, embora os uploads não consumam créditos.

Experimente

Username = API Id, Password = API Key

cURL

$ curl https://clippingmagic.com/api/v1/images \
 -u 123:[secret] \ 
 -F 'image=@example.jpg' \ 
 -F 'test=true'

Supõe que 'example.jpg' existe. Substitua adequadamente. Linha com 'test=true' é opcional.

Exemplo de resposta

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

Download GET https://clippingmagic.com/api/v1/images/[imageId]

Para fazer download de um resultado, você faz um HTTP GET padrão. O resultado tem que ser gerado primeiro. Em geral, isso é feito deixando o usuário final recortar a imagem no seu site usando ClippingMagic.js

Downloads de resultados de testes é gratuito, mas incluem uma marca d'água. Downloads de produção consomem um crédito na primeira vez que o download for feito. Downloads repetidos são gratuitos.

Se houver um resultado disponível, você será redirecionado a ele (resultados são armazenados na Amazon S3). Portanto, confirme que sua biblioteca de cliente está configurada para seguir redirecionamentos.

O cabeçalho de resposta x-amz-meta-resultrevision indica o resultRevision do download do resultado. O cabeçalho Content-Disposition indica o nome do arquivo de resultado, incluindo a extensão: .jpeg para resultados com fundo opaco e .png para resultados com fundo transparente.

Se não houver resultados disponíveis, você receberá uma resposta de erro.

Parâmetros

imageId

Incorporado no URL

Você precisa inserir o valor de id que foi retornado na chamada Upload.

Opcional
format

Por padrão, a imagem resultante é retornada.

format=clipping_path_svg recupera o demarcador de corte (SVG).

format=alpha_mask_png recupera a máscara alfa (PNG).

format=json recupera o objeto JSON de imagem. Útil se você quiser verificar o resultRevision ou se tiver perdido a chave secreta da imagem.

Recuperar o objeto JSON de imagem não debita a sua conta. Você só é cobrado quando faz download de resultados de produção.

Username = API Id, Password = API Key

cURL

$ curl https://clippingmagic.com/api/v1/images/2345 \
 -u 123:[secret] \ 
 -LOJ

Exemplo de resposta JSON

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

Lista GET https://clippingmagic.com/api/v1/images

Para recuperar uma lista dos seus objetos JSON de imagem, use um HTTP GET padrão.

Parâmetros

Opcional
limit

Número de registros a recuperar. O padrão é 20 (mín. 1, máx. 100).

Opcional
offset

Deslocamento para usar na lista de registros (por padrão, é 0).

Atributos de resposta

images

Um array de objetos JSON de imagem.

limit

O limit realmente usado na produção do resultado.

offset

O offset realmente usado na produção do resultado.

Username = API Id, Password = API Key

cURL

$ curl "https://clippingmagic.com/api/v1/images?limit=2&offset=0" \
 -u 123:[secret]

Exemplo de resposta

{
  "images" : [ {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }, {
    "id" : 2346,
    "secret" : "image_secret2",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  } ],
  "limit" : 2,
  "offset" : 0
}

Excluir POST https://clippingmagic.com/api/v1/images/[imageId]/delete

Para excluir uma imagem, use um HTTP POST padrão para o URL de exclusão.

Este é um pequeno desvio da prática REST padrão, para tratar o fato de que várias bibliotecas de HTTP cliente não aceitam o verbo DELETE e, ao mesmo tempo, evitar a confusão de ter várias formas de fazer a mesma coisa.

Parâmetros

imageId

Incorporado no URL

Você precisa inserir o valor de id que foi retornado na chamada Upload.

Atributos de resposta

image

O objeto JSON de imagem excluído.

Experimente

Username = API Id, Password = API Key

cURL

$ curl https://clippingmagic.com/api/v1/images/2345/delete \
 -u 123:[secret] \ 
 -X POST

Exemplo de resposta

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

Conta GET https://clippingmagic.com/api/v1/account

Obtenha informações básicas sobre a sua conta, como o status da assinatura e o número de créditos remanescentes.

Parâmetros

Nenhum

Atributos de resposta

subscriptionPlan

O seu plano de assinatura atual ou "nenhum".

subscriptionState

O status do seu plano de assinatura atual ("ativo" ou "atrasado") ou, se não houver assinatura, "terminado".

credits

A quantidade de créditos remanescente em sua conta. Se não for assinante, a quantidade será 0.

Username = API Id, Password = API Key

cURL

$ curl "https://clippingmagic.com/api/v1/account" \
 -u 123:[secret]

Exemplo de resposta

{
  "subscriptionPlan" : "none",
  "subscriptionState" : "ended",
  "credits" : 0
}