API del servidor

Todas las peticiones de API son peticiones HTTP estándar a URLs estilo REST. Las respuestas son ya sea JSON o una imagen (cuando se manda a llamar un resultado).

Autenticación

La API usa autenticación de acceso básico a HTTP estándar. Todas las peticiones a la API tendrán que incluir su información de acceso a la API, con la identificación de la API como el nombre de usuario y el código secreto de la API como la contraseña. Tenga en cuenta que ClippingMagic.js solamente usa su Id de la API para no revelar a sus usuarios su código secreto de la API.

Seguridad

Todas las peticiones se deben hacer en HTTPS y usted tendrá que autenticar todas las peticiones.

Su biblioteca cliente de http debe ser compatible con la Indicación de nombre del servidor (SNI) para poder hacer peticiones. Si tiene errores raros de protocolo de enlace, esta es la razón más probable.

Backend contra Frontend

Tenga en cuenta que todas las operaciones de carga y descarga suceden en el backend, pero todas las operaciones de revisión y edición suceden en el Editor inteligente.

Esta división protege su clave API mientras que permite que el usuario final tenga una experiencia ininterrumpida en su sitio.

Limitaciones de la velocidad de respuesta

El uso de la API tiene limitaciones de velocidad de respuesta con amplias asignaciones sin límite superior más allá de sus créditos de API.

Durante la operación normal impulsada por el usuario es improbable que vea límites de la velocidad de respuesta ya que en ese caso el uso tiende a fluir de una manera que el servicio maneja muy bien.

Sin embargo, para los procesos en lotes recomendamos que comience con 5 hilos máximo y puede agregar 1 hilo nuevo cada 5 minutos hasta que llegue al nivel deseado de paralelismo. Si necesita más de 100 hilos actuales, comuníquese con nosotros antes de comenzar.

Si envía demasiadas peticiones comenzará a recibir la respuesta 429 Too Many Requests. Si esto sucede, debe aplicar una espera lineal: cuando reciba la primera respuesta de ese tipo, espere 5 segundos antes de enviar la siguiente petición. Cuando reciba la segunda respuesta 429 consecutiva, espere 2*5=10 segundos antes de enviar la siguiente petición. Cuando reciba la tercera respuesta, espere 3*5=15, etc.

Puede restablecer el contador de espera después de una petición exitosa y deberá poder aplicar la espera por cada hilo (es decir, los hilos deben operar de manera independiente entre sí).

Error de objeto JSON

Usamos estratos convencionales de HTTP para indicar el éxito o el fracaso de una petición API e incluímos información importante del error en el objeto de error JSON devuelto.

Tratamos de siempre regresar un objeto de error JSON con las solicitudes problemáticas. Sin embargo, siempre es teóricamente posible tener fallas del servidor interno que conducen a una respuesta de error que no es tipo JSON.

Atributos

statusEl estado HTTP de la respuesta, se repite aquí para ayudarle con la depuración.
codeCódigo de error interno de Clipping Magic.
messageMensaje de error en lenguaje natural, previsto para ayudar con la depuración.

Si el estadeo del HTTP de su petición es 200, no se devolverá un objeto JSON de error y podrá suponer en términos generales que la petición tuvo éxito.

Algunas bibliotecas de clientes HTTP producen exepciones para estratos HTTP en la gama de 400-599. Tendrá que darse cuenta de esas excepciones y resolverlas apropiadamente.

HTTP StatusSignificado
200-299

Éxito

400-499

Hay un problema con la información proporcionada en la solicitud (p. ej. un parámetro faltante). Revise el mensaje de error para determinar cómo arreglarlo.

500-599

Hubo un error interno de Clipping Magic. Espere un momento y vuelva a intentar, y si el problema persiste, envíenos un mensaje de correo electrónico.

Los errores recientes de la API se enumeran en la página de su cuenta para que los pueda depurar.

Ejemplo de una respuesta de error

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

Objeto JSON de la imagen

Los registros de las imágenes se representan de un modo unforme con un objeto JSON, devuelto por varias de las accoines de la API.

Atributos

id

Identificador único para la imagen. Se necesita para permitir a los usuarios editar la imagen y descargar el resultado.

secret

El código secreto es necesario para editar esta imagen con ClippingMagic.js

resultRevision

Número que indica la reversión más reciente disponible para descargar (0 = no hay ninguna todavía).

Le permite determinar si hay un resultado más nuevo para esta imagen que el que descargó previamente.

originalFilename

Una cadena que contiene el nombre del archivo proporcionado cuando cargó la imagen original.

test

true significa que esta es una imagen de prueba que puede procesar gratis, pero el resultado tendrá una marca de agua.

false significa que esta es una imagen de producción y cuesta créditos procesarla, pero el resultado no tendrá una marca de agua.

Ejemplo

{
  "id" : 2346,
  "secret" : "image_secret1",
  "resultRevision" : 0,
  "originalFilename" : "example_image1.jpg",
  "imageCategoryUser" : "Photo",
  "imageCategoryAi" : "Photo",
  "test" : false
}

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

Para cargar una imagen, ejecute una petición HTTP POST estándar para cargar un archivo. Este punto de acceso se tiene que invocar desde el backend, no se puede invocar desde el javacript de su página web. Tenga en cuenta que el tipo de contenido tiene que ser multipart/form-data cuando carga archivos binarios.

Parámetros

La imagen original se debe proporcionar como una de:

image
Binaria

Un archivo binario.

image.base64
Cadena

Un cadena codificada con base 64. La cadena no puede de más de 1 megabyte.

image.url
Cadena

Un URL por obtener.

Debe ser un archivo .bmp, .gif, .jpeg, .png o .tiff.

El tamaño máximo de una imagen para cargarla (= ancho × altura) es 33.554.432 píxeles, que se reduce a 4.194.404 píxeles a menos que maxPixels lo reemplace. Reduzca sus imágenes al último tamaño o más pequeño antes de cargarlas.

test
Booleano
true, false

Pasa en true para indicar que esta es una imagen de prueba.

En el caso de imágenes de producción, omitir o pasar cuando es false.

Las imágenese de prueba se pueden procesar gratis, pero el resultado tendrá una marca de agua incrustada.

format
Enum
json, result, clipping_path_svg, clipping_path_tiff, alpha_mask_png

format=json (predeterminado): no se produce ningún resultado de Auto-Clip y se devuelve el objeto JSON de la imagen. Use esto cuando un operador humano revisa y posiblemente retoca el resultado usando ClippingMagic.js.

format=result genera y obtiene el resultado de Auto-Clip.

format=clipping_path_svg genera el resultado de Auto-Clip y obtiene la ruta de Clipping (SVG).

format=clipping_path_tiff genera el resultado de Auto-Clip y obtiene la ruta de Clipping (TIFF).

format=alpha_mask_png genera el resultado de Auto-Clip y obtiene la cara Alpha (PNG). La máscara alfa tiene el mismo tamaño que la imagen original. Aplicarla a la imagen original no produce el resultado, ya que el Protector de bordes y el Quita halos mejoran los colores de los bordes.

El id y secret se devuelven en el x-amz-meta-id y en los encabezados x-amz-meta-secret al obtener un resultado que no es JSON. Guárdelos para poder revisar y editar su resultado con ClippingMagic.js. Vea todos los encabezados incluidos en la respuesta

El acceso al objeto JSON de la imagen no cuesta, solamente cuesta descargar los resultados de producción.

maxPixels
Entero
1000000 a 26214400

Cambia el tamaño máximo de imagen (= width × height) que se usa al cambiar las dimensiones de la imagen después de cargarla.

Predeterminado: 4.194.404pixeles

background.color
#RRGGBB
#0055FF

Omitir para usar un fondo transparente y obtener un resultado en PNG.

Incluir para obtener un fondo opaco del color especificado y un resultado output.opaqueFileFormat (JPEG predeterminado).

Asegúrese de incluir el '#'.

Configure los parámetros de procesamiento:

processing.mode
Enum
auto, photo, graphics, scan

Controle el modo de procesamiento usado para su imagen.

Opción predeterminada: auto

processing.autoClip
Booleano
true, false

Habilite (opción predeterminada) o deshabilite la función Recortar automáticamente cuando edite una imagen en la aplicación para la web.

Deshabilítelo si desea cargar imágenes a través de la API, pero entonces, recorte de forma libre otra cosa que no sea el primer plano obvio (si lo hay).

Opción predeterminada: true

processing.autoHair
Booleano
true, false

Habilite (opción predeterminada) o deshabilite la aplicación de una máscara de cabello automática.

Opción predeterminada: true

processing.allowGraphicsMode
Booleano
true, false

Habilite (opción predeterminada) o deshabilite la selección automática del modo Gráficos.

Esta configuración no se aplica cuando format=json.

Opción predeterminada: true

processing.allowScanMode
Booleano
true, false

Habilite (opción predeterminada) o deshabilite la selección automática del modo Imagen escaneada.

Esta configuración no se aplica cuando format=json.

Opción predeterminada: true

Configure los niveles de color:

colors.auto
Booleano
true, false

Ajuste automáticamente los niveles de color para mejorar el contraste.

Opción predeterminada: false

colors.brightness
Entero
-100 a 100

Ajuste el brillo de la imagen resultante.

Opción predeterminada: 0

colors.shadows
Entero
-100 a 100

Ajuste las sombras de la imagen resultante. Los valores positivos significan sombras más oscuras.

Opción predeterminada: 0

colors.highlights
Entero
-100 a 100

Ajuste la iluminación de la imagen resultante. Los valores positivos significan toques de luz más claros.

Opción predeterminada: 0

colors.temperature
Entero
-100 a 100

Ajuste la temperatura del color de la imagen resultante. Los valores positivos significan colores más cálidos.

Opción predeterminada: 0

colors.saturation
Entero
-100 a 100

Ajuste la saturación de la imagen resultante. Los valores positivos significan más saturación.

Opción predeterminada: 0

Configure la eliminación de un color del fondo que predomina en la imagen del primer plano, como por ejemplo con un filtro de verde:

colorCast.auto
Booleano
true, false

Determine automáticamente el color del fondo que desea eliminar del primer plano.

Opción predeterminada: false

colorCast.color
#RRGGBB
#A84400

El color del fondo especificado manualmente que desea eliminar del primer plano.

Omitir para detectar automáticamente.

colorCast.foregroundGuard
Flotante
0.0 a 20.0

Los valores más altos reducen el impacto de la eliminación de la dominante de color de los colores genuinos del primer plano que son similares a la dominante de color, pero más saturado que los que se están eliminando.

Opción predeterminada: 4.0

Configure el balance de blancos:

whiteBalance.auto
Booleano
true, false

Determine automáticamente el color de referencia a usar para realizar el balance de blancos.

Opción predeterminada: false

whiteBalance.color
#RRGGBB
#968386

El color para el balance de blancos especificado manualmente.

Omitir para detectar automáticamente.

Configure los toques finales:

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

Agregue un efecto de sombra paralela al resultado recortado.

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

Agregue un efecto de reflejo al resultado recortado.

Configure los parámetros de los bordes:

edges.corners
Booleano
true, false

Use (opción predeterminada) o deshabilite el Protector de esquinas.

edges.smoothing
Enum
smart, fixed

Use suazivado smart (opción predeterminada) o fixed.

edges.smoothingLevel
Flotante
0.0 a 5.0

Configure la cantidad de suavizado aplicado al resultado.

Opción predeterminada 1.0

edges.feathering
Enum
fixed, auto, local

Use desvanecimiento auto (opción predeterminada), local o fixed.

edges.featheringRadiusPx
Flotante
0.0 a 6.0

Configure la cantidad de desvanecimiento aplicada al resultado.

Opción predeterminada: 1.0

edges.offsetPx
Flotante
0.0 a 10.0

Configure el desplazamiento del borde aplicado al resultado.

Opción predeterminada: 0.0

Ajustar la imagen según el resultado

fit.toResult
Booleano
true, false

Active o desactive (opción predeterminada) Posicionar según el resultado.

Si está activada, se ignorarán los demás parámetros de esta sección.

fit.paddingPercent
Flotante
0.0 a 35.0

El espaciado interno que se aplicará alrededor del resultado ajustado, como porcentaje del tamaño del resultado.

Opción predeterminada: 5.0

fit.paddingPixels
Entero
0 a 250

El espaciado interno, en píxeles, que se aplicará alrededor del resultado de tamaño ajustado.

Si no se especifica, se usa un porcentaje para el espaciado interno.

fit.objectSize
Enum
small, medium, large

Puede especificar un tamaño sintético para su objeto. Esto es útil para el comercio electrónico, cuando desea darle que el cliente una idea general del tamaño del producto en relación con otros productos.

Opción predeterminada: large (no se ajusta el tamaño del resultado)

fit.verticalAlignment
Enum
top, middle, bottom

Especifique cómo se debe alinear su resultado si hay espacio vertical en exceso.

También se aplica cuando se distribuye espacio en exceso debido a la relación de aspecto o al tamaño deseado que se debe seguir, ver abajo.

Opción predeterminada: middle

fit.shadows
Enum
ignore, pad, tight

Puede ignorar las sombras, rellenar los dos lados parejos al tamaño de las sombras o rellenar ajustado solo donde se necesita para no cortar la sombra.

Opción predeterminada: pad

fit.rotationDeg
Flotante
-360.0 a 360.0

Girar la imagen. Los valores positivos van en sentido antihorario.

Opción predeterminada: 0

Controle el tamaño del resultado y la relación de aspecto:

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

Asegúrese de que el resultado tenga la relación de aspecto proporcionada.

fit.verticalAlignment controla cómo se distribuye el espacio vertical en exceso.

Opción predeterminada: no aplicar

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

Asegúrese de que el resultado tenga el tamaño proporcionado.

fit.verticalAlignment controla cómo se distribuye el espacio vertical en exceso.

Opción predeterminada: no aplicar

result.allowEnlarging
Booleano
true, false

Controla si el resultado se puede hacer más grande que la imagen original o no.

Opción predeterminada: false

Controle las opciones del resultado:

output.dpi
Entero
1 a 4000

Fije que la información de los PPP se inserte en el resultado.

La información de los PPP no se incluye si el resultado se optimiza para la web.

Opción predeterminada: 72

output.colorSpace
Enum
sRGB, AdobeRGB, AppleRGB, ColorMatchRGB

Fije que la información del espacio del color se inserte en el resultado.

La información del espacio del color no se incluye si el resultado se optimiza para la web.

Opción predeterminada: sRGB

output.jpegQuality
Entero
1 a 100

Configure la calidad que se usará al producir un resultado en JPEG.

Opción predeterminada: 75

output.pngOptimization
Enum
none, lossless, lossy

Configure la optimización para la web de los resultados en PNG.

Opción predeterminada: lossless

output.jpegOptimization
Enum
none, enabled

Configure la optimización para la web de los resultados en JPEG.

Opción predeterminada: enabled

output.opaqueFileFormat
Enum
jpeg, png

Configure el formato de archivo que se usará para los resultados opacos.

Opción predeterminada: jpeg

Puede cargar imágenes en el modo de prueba sin una suscripción. Sin embargo, aunque no cuesta ningún crédito cargar imágenes, necesita una suscripción válida para API para cargar imágenes de producción a través de una API.

Pruébelo


Formato: '#RRGGBB'



Formato: '#RRGGBB'

Formato: '#RRGGBB'


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

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




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

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

Nombre de usuario = Id de la API, contraseña = código secreto

cURL

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

Supone que 'example.jpg' existe. Reemplace según sea apropiado. La línea con 'prueba=verdadero' es opcional.

Respuesta del ejemplo

{
  "image" : {
    "id" : 2346,
    "secret" : "image_secret1",
    "resultRevision" : 0,
    "originalFilename" : "example_image1.jpg",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "test" : false
  }
}

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

Para descargar un resultado, tiene que ejecutar una función HTTP GET estándar. Primero se tiene que haber producido un resultado.

Los resultados de prueba se pueden descargar gratis, pero tendrán una marca de agua. Cuesta un punto descargar los resultados de producción la primera vez que los descarga; las descargas posteriores son gratuitas.

Si no hay ningún resultado, recibirá una respuesta de error.

Parámetros

imageId

Incorporado en el URL

Tendrá que introducir el valor de id que se devolvió en la invocación de Cargar.

Opcional
format

format=result (opción predeterminada) obtiene la imagen del resultado.

En lugar de eso, format=clipping_path_svg obtiene la ruta de Clipping (SVG).

format=clipping_path_tiff obtiene la ruta de Clipping (TIFF).

En lugar de eso, format=alpha_mask_png obtiene la máscara Alpha (PNG).

En lugar de eso, format=json consigue el objeto JSON de la imagen. Es útil si desea revisar resultRevision o si perdió el código secreto de la imagen.

El acceso al objeto JSON de la imagen no cuesta, solamente cuesta descargar los resultados de producción.

Encabezados de respuesta

Cuando format no es json, proporcionamos información clave en estos encabezamientos de respuesta en HTTP

x-amz-meta-id
Example: 2346

El id de su imagen.

x-amz-meta-secret
Example: image_secret1

El secret de su imagen.

x-amz-meta-resultrevision
Example: 1

El resultRevision que está obteniendo en esta petición.

Cada vez que se produce un resultado nuevo, aumenta este contador.

x-amz-meta-width
Example: 3200
(solamente se incluye para format=result)

El ancho en píxeles del resultado que está obteniendo en esta petición.

x-amz-meta-height
Example: 2400
(solamente se incluye para format=result)

La altura en píxeles del resultado que está obteniendo en esta petición.

Content-Disposition
Example: attachment; filename*=UTF-8''example_image1_clipped_rev_0.png

El nombre de archivo del resultado, incluida la extensión.

Nombre de usuario = Id de la API, contraseña = código secreto

cURL

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

Respuesta JSON del ejemplo

{
  "image" : {
    "id" : 2346,
    "secret" : "image_secret1",
    "resultRevision" : 0,
    "originalFilename" : "example_image1.jpg",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "test" : false
  }
}

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

Para obtener una lista de sus objetos JSON de la imagen tiene que ejecutar una función HTTP GET estándar.

Parámetros

Opcional
limit

Número de registros a obtener. La opción predeterminada es 20 (mín 1, máx 100).

Opcional
offset

Desplazamiento a usar en la lista de registros (la opción predeterminada es 0).

Atributos de la respuesta

images

Una cadena de objetos JSON de la imagen.

limit

El limit que se usa al producir el resultado.

offset

El offset que se usa al producir el resultado.

Nombre de usuario = Id de la API, contraseña = código secreto

cURL

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

Respuesta del ejemplo

{
  "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
}

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

Para eliminar una imagen, ejecute una petición HTTP POST en el URL del que se eliminará.

Esta es una ligera desviación de la práctica REST estándar para manejar la realidad de que muchas de las bibliotecas cliente HTTP no son compatibles con el verbo HTTP DELETE, y evita los problemas de tener muchas maneras diferentes de hacer la misma cosa.

Parámetros

imageId

Incorporado en el URL

Tendrá que introducir el valor de id que se devolvió en la invocación de Cargar.

Atributos de la respuesta

image

El objeto JSON de la imagen eliminada.

Pruébelo

Nombre de usuario = Id de la API, contraseña = código secreto

cURL

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

Respuesta del ejemplo

{
  "image" : {
    "id" : 2346,
    "secret" : "image_secret1",
    "resultRevision" : 0,
    "originalFilename" : "example_image1.jpg",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "test" : false
  }
}

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

Obtenga información básica sobre su cuenta, por ejemplo, el estado de su suscripción y el número de créditos restantes.

Parámetros

Ninguno

Atributos de la respuesta

subscriptionPlan

El plan en el que está inscrito ahora o 'ninguno'.

subscriptionState

El estado de su suscripción actual ('activa' o 'vencida') o 'cancelada' si no está inscrito.

credits

Los créditos de la API restantes en su cuenta. 0 si no está inscrito actualmente o si está inscrito en un plan sin API.

Nombre de usuario = Id de la API, contraseña = código secreto

cURL

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

Respuesta del ejemplo

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