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 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.

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.

Exemplo de resposta de erro

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

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.

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

Para upload de uma imagem, você deve fazer um upload de arquivo HTTP POST padrão. Lembre-se de que o Content-Type deve ser multipart/form-data

Atributos

image

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

O tamanho máximo da imagem é 8.388.608 pixels, que é reduzido para 4.194.404 pixels. Reduza suas imagens para esse último tamanho ou menos antes de fazer upload.

Opcional
test

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

Atributos de resposta

image

O objeto JSON de imagem.

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

Supõe que 'example.jpg' existe. Substitua adequadamente.

Exemplo de resposta

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

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

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.

Argumentos

image_id

Incorporado no URL

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

Opcional
format

Por padrão, a imagem de resultado é retornada. Porém, se você especificar format=json, você receberá 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.

Argumentos

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/[image_id]/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.

Argumentos

image_id

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.

Argumentos

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
}