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).
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.
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.
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.
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í).
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 |
|
|---|---|
| status | El estado HTTP de la respuesta, se repite aquí para ayudarle con la depuración. |
| code | Código de error interno de Clipping Magic. |
| message | Mensaje 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 Status | Significado |
|---|---|
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. "
}
}
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 |
| 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 |
|
Ejemplo
{
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
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 (endpoint) 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:
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 |
|||||||||||||||
|
test
Booleano true, false
|
Pasa en
En el caso de imágenes de producción, omitir o pasar cuando es 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
|
El 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:
|
|||||||||||||||
|
Configure los niveles de color:
|
|||||||||||||||
|
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:
|
|||||||||||||||
|
Configure el balance de blancos:
|
|||||||||||||||
|
Configure los toques finales:
|
|||||||||||||||
|
Configure los parámetros de los bordes:
|
|||||||||||||||
|
Ajustar la imagen según el resultado
|
|||||||||||||||
|
Controle el tamaño del resultado y la relación de aspecto:
|
|||||||||||||||
|
Controle las opciones del resultado:
|
|||||||||||||||
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
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
}
}
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 |
|
Opcional
format |
En lugar de eso,
En lugar de eso,
En lugar de eso, El acceso al objeto JSON de la imagen no cuesta, solamente cuesta descargar los resultados de producción. |
|
Encabezados de respuesta
Cuando |
|
|---|---|
x-amz-meta-id
Example: 2346
|
El |
x-amz-meta-secret
Example: image_secret1
|
El |
x-amz-meta-resultrevision
Example: 1
|
El 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. |
Pruébelo
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
}
}
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 |
| offset |
El |
Pruébelo
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
}
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 |
|
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
}
}
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
}