API de servidor

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

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.

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

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",
  "imageCategoryUser" : "Photo",
  "imageCategoryAi" : "Photo",
  "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 no upload de arquivos binários.

Parâmetros

A imagem de entrada de ser fornecida como:

image
Binário

Um arquivo binário.

image.base64
Cadeia de caracteres

Uma cadeia de caracteres codificada como base 64. A cadeia de caracteres pode ter o comprimento máximo de 1 megabyte.

image.url
Cadeia de caracteres

Uma URL onde buscar.

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 maxPixels abaixo. Reduza suas imagens para esse último tamanho ou menos antes de fazer upload.

test
Boleano
true, false

Informe true para indicar que esta é uma imagem de teste.

Omitir ou passar false para imagens de produção.

Imagens de teste têm processamento gratuito, mas o resultado incorpora uma marca d'água.

format
Enum
json, result, clipping_path_svg, alpha_mask_png

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. Veja todos os cabeçalhos incluídos na resposta

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

Não deixe de incluir o "#".

Configure os parâmetros de processamento:

processing.mode
Enum
auto, photo, graphics, scan

Controla o modo de processamento usado para a sua imagem.

Padrão: auto

processing.autoClip
Boleano
true, false

Ativa (padrão) ou desativa o recorte automático na edição da imagem no aplicativo da web.

Desative se quiser fazer upload de imagens via a API, mas depois desejar fazer recorte em formato livre de algo que não seja o fundo óbvio (se houver).

Padrão: true

processing.autoHair
Boleano
true, false

Ativar (opção padrão) ou desativar a aplicação de uma máscara de cabelos automática.

Padrão: true

processing.allowGraphicsMode
Boleano
true, false

Ativar (opção padrão) ou desativar a seleção automática do modo gráfico.

Esta configuração não se aplica quando format=json.

Padrão: true

processing.allowScanMode
Boleano
true, false

Ativar (opção padrão) ou desativar a seleção automática do modo de imagem digitalizada.

Esta configuração não se aplica quando format=json.

Padrão: true

Configure os níveis de cores:

colors.auto
Boleano
true, false

Ajusta automaticamente os níveis de cores para aprimorar o contraste.

Padrão: false

colors.brightness
Inteiro
-100 a 100

Ajusta o brilho da imagem resultante.

Padrão: 0

colors.shadows
Inteiro
-100 a 100

Ajusta as sombras da imagem resultante. Valores positivos se traduzem em sombras mais escuras.

Padrão: 0

colors.highlights
Inteiro
-100 a 100

Ajusta os realces da imagem resultante. Valores positivos se traduzem em realces mais claros.

Padrão: 0

colors.temperature
Inteiro
-100 a 100

Ajusta a temperatura de cores da imagem resultante. Valores positivos se traduzem em cores mais quentes.

Padrão: 0

colors.saturation
Inteiro
-100 a 100

Ajusta a saturação da imagem resultante. Valores positivos se traduzem em mais saturação.

Padrão: 0

Configura a remoção de uma cor do fundo que tenha reflexo no primeiro plano, como um pano de fundo verde:

colorCast.auto
Boleano
true, false

Determina automaticamente a cor do fundo para remover do primeiro plano.

Padrão: false

colorCast.color
#RRGGBB
#A84400

A cor de fundo especificada manualmente para remover do primeiro plano.

Omita para detecção automática.

colorCast.foregroundGuard
Flutuante
0.0 a 20.0

Valores mais altos reduzem o impacto da remoção do reflexo de cor nas cores genuínas do primeiro plano que são similares à cor do reflexo, mas mais saturadas do que as cores sendo removidas.

Padrão: 4.0

Configure o equilíbrio de banco:

whiteBalance.auto
Boleano
true, false

Determina automaticamente a cor de referência a ser usada na execução do equilíbrio de branco.

Padrão: false

whiteBalance.color
#RRGGBB
#968386

A cor de equilíbrio de banco especificada manualmente.

Omita para detecção automática.

Configure os toques finais:

effects.dropShadow
[xOffsetPx:int] [yOffsetPx:int] [blurRadiusPx:int, 0 to 75] [opacity:float, 0 to 1]
30 30 25 0.75

Adicionar um efeito de sombra projetada ao resultado recortado.

effects.reflection
[yOffsetPx:int, 0 to 400] [heightPx:int, 0 to 800] [opacity:float, 0 to 1]
0 200 0.5

Adicionar um efeito de espelho ao resultado recortado.

Configure os parâmetros de borda:

edges.corners
Boleano
true, false

Usar (padrão) ou desativar a proteção de canto.

edges.smoothing
Enum
smart, fixed

Usar smart (padrão) ou fixed suavização.

edges.smoothingLevel
Flutuante
0.0 a 5.0

Configurar a extensão de suavização aplicada ao resultado.

Padrão 1.0

edges.feathering
Enum
fixed, auto, local

Usar difusão auto (padrão), local ou fixed.

edges.featheringRadiusPx
Flutuante
0.0 a 6.0

Configurar a extensão de difusão aplicada ao resultado.

Padrão: 1.0

edges.offsetPx
Flutuante
0.0 a 10.0

Configurar o deslocamento de delimitação aplicado ao resultado.

Padrão: 0.0

Adequar a saída ao resultado

fit.toResult
Boleano
true, false

Ativar ou desativar (padrão) a adequação ao resultado.

Se estiver desativada, os parâmetros restantes nesta sessão serão ignorados.

fit.paddingPercent
Flutuante
0.0 a 35.0

O espaço em branco que será aplicado em volta do resultado adequado, como porcentagem do tamanho do resultado.

Padrão: 5.0

fit.paddingPixels
Inteiro
0 a 250

O espaço em branco, em pixels, que será aplicado ao em volta do resultado adequado.

Se não for especificado, um espaço em branco percentual será usado.

fit.objectSize
Enum
small, medium, large

É possível especificar um tamanho relativo para o objeto. Isso é util em comércio eletrônico quando você quer dar ao consumidor uma sensação do tamanho do produto em relação a outros produtos.

Padrão: large (= o tamanho do resultado não será alterado)

fit.verticalAlignment
Enum
top, middle, bottom

Especifica como o resultado deverá ser alinhado se houver espaço vertical em excesso.

Também se aplica na distribuição de espaço em excesso devido ao cumprimento de proporções ou tamanho pretendido, conforme abaixo.

Padrão: middle

fit.shadows
Enum
ignore, pad, tight

Você pode ignorar as sombras, adicionar espaço em branco dos dois lados do objeto para comportar a sombra ou apenas onde for necessário para não cortar a sombra.

Padrão: pad

fit.rotationDeg
Flutuante
-360.0 a 360.0

Gira a imagem. Valores positivos implicam em sentido anti-horário.

Padrão: 0

Controla o tamanho e a proporção do resultado:

result.aspectRatio
[width:float, >0]:[height:float, >0]
4:3

Assegura que o resultado cumpre a proporção especificada.

fit.verticalAlignment controla como o espaço vertical em excesso é distribuído.

Padrão: não é aplicado

result.targetSize
[width:int, >0] [height:int, >0]
400 300

Assegura que o resultado cumpre o tamanho especificado.

fit.verticalAlignment controla como o espaço vertical em excesso é distribuído.

Padrão: não é aplicado

result.allowEnlarging
Boleano
true, false

Controla se o resultado pode ou não ser maior do que a imagem de entrada.

Padrão: false

Controla as opções de saída:

output.dpi
Inteiro
1 a 4000

Define as informações de DPI incorporadas no resultado.

As informações de DPI não são incluídas se o resultado for otimizado para a web.

Padrão: 72

output.colorSpace
Enum
sRGB, AdobeRGB, AppleRGB, ColorMatchRGB

Define as informações de espaço de cor incorporadas no resultado.

As informações de espaço de cor não são incorporadas se o resultado for otimizado para a web.

Padrão: sRGB

output.jpegQuality
Inteiro
1 a 100

Configura a definição de qualidade usada ao produzir um resultado JPEG.

Padrão: 75

output.pngOptimization
Enum
none, lossless, lossy

Configura a otimização para web de resultados PNG.

Padrão: lossless

output.jpegOptimization
Enum
none, enabled

Configura a otimização para web de resultados JPEG.

Padrão: enabled

output.opaqueFileFormat
Enum
jpeg, png

Configura o formato de arquivo usado para resultados opacos.

Padrão: jpeg

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


Formato: '#RRGGBB'



Formato: '#RRGGBB'

Formato: '#RRGGBB'


Formato: '[xOffsetPx:int] [yOffsetPx:int] [blurRadiusPx:int, 0 to 75] [opacity:float, 0 to 1]'
Exemplo: 30 30 25 0.75

Formato: '[yOffsetPx:int, 0 to 400] [heightPx:int, 0 to 800] [opacity:float, 0 to 1]'
Exemplo: 0 200 0.5




Formato: '[width:float, >0]:[height:float, >0]'
Exemplo: 4:3

Formato: '[width:int, >0] [height:int, >0]'
Exemplo: 400 300

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",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "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.

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 id que foi retornado na chamada Upload.

Opcional
format

format=result (padrão) busca a imagem de resultado.

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.

Cabeçalhos de resposta

Quando format não é json, fornecemos as informações chave nestes cabeçalhos de resposta HTTP

x-amz-meta-id
Example: 2345

id da sua imagem.

x-amz-meta-secret
Example: image_secret

secret da sua imagem.

x-amz-meta-resultrevision
Example: 1

resultRevision que você está buscando nesta solicitação.

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''image_clipped_rev_0.png

O nome do arquivo de resultado, incluindo a extensã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",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "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",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "test" : false
  }, {
    "id" : 2346,
    "secret" : "image_secret2",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "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",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "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
}