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).
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 o Segredo de API como a senha. Note que ClippingMagic.js somente usa o Id de API, para não revelar o Segredo de API para os seus usuários.
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.
Note que todas as operações de upload e download ocorrem no back-end, mas todas as operações de revisão e edição acontecem no Editor inteligente.
Essa divisão protege sua chave de API, além de possibilitar uma experiência contínua para o usuário do seu site.
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.
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 |
|
|---|---|
| status | O status HTTP da resposta, repetido aqui para auxílio na depuração de erros. |
| code | código interno de erro Clipping Magic |
| message | Mensagem 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 Status | Significado |
|---|---|
200-299
|
Êxito |
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. |
Os erros de API recentes estão relacionados na página da sua conta para facilitar o debugging.
Exemplo de resposta de erro
{
"error" : {
"status" : 400,
"code" : 1006,
"message" : "Failed to read the supplied image. "
}
}
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 |
| 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 |
|
Exemplo
{
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
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 no upload de arquivos binários.
|
Parâmetros |
|||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
A imagem de entrada de ser fornecida como:
O arquivo 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 |
|||||||||||||||
|
test
Boleano true, false
|
Informe
Omitir ou passar Imagens de teste têm processamento gratuito, mas o resultado incorpora uma marca d'água. |
||||||||||||||
|
format
Enum json, result, clipping_path_svg, clipping_path_tiff, alpha_mask_png
|
O Recuperar o objeto JSON de imagem não debita a sua conta. Você só é cobrado quando faz download de resultados de produção. |
||||||||||||||
|
maxPixels
Inteiro 1000000 a 26214400
|
Altera o tamanho máximo de imagem (= largura × altura) usado ao redimensionar a imagem após o upload. Padrão: 4.194.404 pixels |
||||||||||||||
|
background.color
#RRGGBB #0055FF
|
Omita para usar um fundo transparente e receber o resultado PNG. Inclua para obter um fundo opaco da cor selecionada e o resultado específicat e o resultado output.opaqueFileFormat(padrão JPEG). Não deixe de incluir o "#". |
||||||||||||||
|
Configure os parâmetros de processamento:
|
|||||||||||||||
|
Configure os níveis de cores:
|
|||||||||||||||
|
Configura a remoção de uma cor do fundo que tenha reflexo no primeiro plano, como um pano de fundo verde:
|
|||||||||||||||
|
Configure o equilíbrio de banco:
|
|||||||||||||||
|
Configure os toques finais:
|
|||||||||||||||
|
Configure os parâmetros de borda:
|
|||||||||||||||
|
|||||||||||||||
|
Controla o tamanho e a proporção do resultado:
|
|||||||||||||||
|
Controla as opções de saída:
|
|||||||||||||||
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
Nome do usuário = Id da API, Senha = Segredo da API
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" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
}
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.
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 não houver resultados disponíveis, você receberá uma resposta de erro.
|
Parâmetros |
|
|---|---|
| imageId |
Incorporado no URL
Você precisa inserir o valor de |
|
Opcional
format |
Recuperar o objeto JSON de imagem não debita a sua conta. Você só é cobrado quando faz download de resultados de produção. |
|
Cabeçalhos de resposta
Quando |
|
|---|---|
x-amz-meta-id
Example: 2346
|
|
x-amz-meta-secret
Example: image_secret1
|
|
x-amz-meta-resultrevision
Example: 1
|
Toda vez que um resultado é gerado, este contador é incrementado. |
x-amz-meta-width
Example: 3200
(incluído somente para format=result)
|
A largura em pixels do resultado que você está buscando nesta solicitação. |
x-amz-meta-height
Example: 2400
(incluído somente para format=result)
|
A altura em pixels do resultado que você está buscando nesta solicitação. |
Content-Disposition
Example: attachment; filename*=UTF-8''example_image1_clipped_rev_0.png
|
O nome do arquivo de resultado, incluindo a extensão. |
Experimente
Nome do usuário = Id da API, Senha = Segredo da API
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346" \ -u 123:[secret] \ -LOJ
Exemplo de resposta JSON
{
"image" : {
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
}
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 |
| offset |
O |
Experimente
Nome do usuário = Id da API, Senha = Segredo da API
cURL
$ curl "https://clippingmagic.com/api/v1/images?limit=2&offset=0" \ -u 123:[secret]
Exemplo de resposta
{
"images" : [ {
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}, {
"id" : 2347,
"secret" : "image_secret2",
"resultRevision" : 0,
"originalFilename" : "example_image2.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
} ],
"limit" : 2,
"offset" : 0
}
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 |
|
Atributos de resposta |
|
|---|---|
| image |
O objeto JSON de imagem excluído. |
Experimente
Nome do usuário = Id da API, Senha = Segredo da API
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346/delete" \ -u 123:[secret] \ -X POST
Exemplo de resposta
{
"image" : {
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
}
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 da API remanescente em sua conta. 0 se não tiver assinatura ou se a assinatura for de uma plano sem API. |
Experimente
Nome do usuário = Id da API, Senha = Segredo da API
cURL
$ curl "https://clippingmagic.com/api/v1/account" \ -u 123:[secret]
Exemplo de resposta
{
"subscriptionPlan" : "none",
"subscriptionState" : "ended",
"credits" : 0
}