Documentación para API

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 HTTP estándar. Todas las peticiones a la API tendrán que incluir los datos de su API, con la identificación de la API como el nombre de usuario y la clave 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 clave de 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.

Pruébelo

Todas las acciones API vienen con el formato html / enlaces a ejemplos que puede probar desde su propio explorador.Los ejemplos cURL usan la información de su API si ya está inscrito, así es que simplemente los tiene que copiar y pegar en su terminal para ejecutarlos.

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.

Ejemplo de una respuesta de error

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

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

301-303

Al descargar resultados: se le redirije a la ubicación real del resultado. No se devolverá ningún objeto JSON de error. Configure su biblioteca de clientes HTTP de modo que siga las redirecciones al descargar los resultados.

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.

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

La clave secreta necesaria 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" : 2345,
  "secret" : "image_secret",
  "resultRevision" : 0,
  "originalFilename" : "image.jpg",
  "test" : false
}

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

Para subir una imagen se carga de la manera habitual un archivo HTTP POST. Tenga en cuenta que el tipo de contenido tiene que ser multipart/form-data

Atributos

image

El archivo de imagen a cargar. Debe ser un archivo .bmp, .gif, .jpeg, .png o .tiff.

El tamaño máximo de una imagen es 8.388.608 píxeles, que se reduce a 4.194.404 píxeles. Reduzca sus imágenes al último tamaño o más pequeño antes de cargarlas.

Opcional
test

Pasa cuando es 'true' para indicar que es una imagen de prueba. Las imágenese de prueba se pueden procesar gratis, pero el resultado tendrá una marca de agua incrustada.

Atributos de la respuesta

image

Objeto JSON de la imagen.

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

Username = API Id, Password = API Key

cURL

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

Supone que 'example.jpg' existe. Reemplace según sea apropiado.

Ejemlo de respuesta

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

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

Para descargar un resultado, tiene que ejecutar una función HTTP GET estándar. Primero se tiene que haber producido un resultado. Esto generalmente se hace permitiéndole al usuario final recortar la imagen de su sitio usando ClippingMagic.js

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, y las descargas posteriores son gratuitas.

Si hay un resultado, se le redirigirá ahí (los resultados se almacenan en Amazon S3), así es que asegúrese de que su biblioteca cliente esté configurada para seguir el redireccionamiento.

El encabezado de la respuesta x-amz-meta-resultrevision indica el resultado resultRevision del resultado descargado y el encabezado Content-Disposition indica el nombre de archivo del resultado, incluida la extensión: jpeg para los resultados con fondos opacos, .png para los resultados con fondos transparentes.

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

Argumentos

image_id

Incorporado en el URL

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

Opcional
format

Por opción predeterminada, se devuelve la imagen resultante. Sin embargo, si especifica format=json, entonces recibirá 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.

Username = API Id, Password = API Key

cURL

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

Respuesta JSON del ejemplo

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "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.

Argumentos

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.

Username = API Id, Password = API Key

cURL

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

Ejemlo de respuesta

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

Eliminar POST https://clippingmagic.com/api/v1/images/[image_id]/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.

Argumentos

image_id

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

Username = API Id, Password = API Key

cURL

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

Ejemlo de respuesta

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

Error de Javascript :-(


¡Ayúdenos a corregir este problema!