Saltar al contenido principal

Plataforma API: Objetivos de imagen

La API de gestión de objetivos de imagen de 8th Wall permite a los desarrolladores gestionar dinámicamente la *biblioteca de objetivos de imagen * asociada a sus proyectos WebAR impulsados por 8th Wall. Esta API y la documentación que la acompaña están diseñadas para desarrolladores familiarizados con el desarrollo web y objetivos de imagen de 8th Wall.

Antes de empezar: Antes de empezar a utilizar la API de Destino de Imagen, su área de trabajo debe estar en un plan de facturación *de empresa. Para actualizar, póngase en contacto con ventas.

Autenticación

La autenticación se realiza mediante claves secretas. Las áreas de trabajo de un plan Enterprise pueden solicitar una Clave API. Incluya esta clave secreta en cada solicitud para verificar que la solicitud está autorizada. Como la clave está asignada a su área de trabajo , tendrá acceso a todos los objetivos de imagen de todas las aplicaciones de esa área de trabajo .

Puedes ver tu clave en la página de su cuenta.

Visualización que muestra los objetivos de imagen dentro de las apps, las apps dentro del área de trabajo y la Clave API dentro del área de trabajo

Importante:

La clave API de Image Target es una clave B2B asociada a su área de trabajo. Siga las mejores prácticas para asegurar su Clave API, ya que exponer públicamente tu clave API puede dar lugar a un uso no intencionado y a un acceso no autorizado. En particular, evite:

  • Incrustar la clave API de objetivo de imagen en el código que se ejecuta en el dispositivo de un usuario o que se comparte públicamente
  • Almacenar la clave API del objetivo de imagen dentro del árbol de fuentes de tu aplicación

Límites y cuotas

  • 25 peticiones por minuto, con una ráfaga permitida de 500, lo que significa que puedes hacer 500 peticiones en un minuto , después puedes hacer 25 peticiones por minuto, o puedes esperar 20 minutos y hacer otras 500 peticiones.
  • 10.0000 solicitudes al día.

Nota: Estos límites solo se aplican a la API de gestión de objetivos de imagen, que permite a los desarrolladores gestionar dinámicamente la biblioteca de imágenes asociadas a un proyecto 8th Wall. Estos límites no son aplicables a las activaciones de usuario final de una experiencia Web AR.

Para solicitar un aumento de los límites de cuota de la API de objetivo de imagen para los proyectos de su área de trabajo , envía una solicitud a support.

Puntos finales

Crear nuevo objetivo de imagen

Subir un nuevo objetivo a la lista de objetivos de imagen de una app

Solicitud

curl -X POST "https://api.8thwall.com/v1/apps/$APP_KEY/targets" \
-H "X-Api-Key:$SECRET_KEY" \
-F "name=my-target-name" \
-F "image=@image.png"\
-F "geometry.top=0"\
-F "geometry.left=0"\
-F "geometry.width=480"\
-F "geometry.height=640"\
-F "metadata={\"customFlag\":true}"
-F "loadAutomatically=true"
CampoTipoValor por defectoDescripción
imageDatos binariosFormato PNG o JPEG, debe ser de al menos 480x640, menos de 2048x2048 y menos de 10MB
nameCadenaDebe ser único dentro de una app, no puede incluir tildes (~) y no puede superar los 255 caracteres
type [Optional]Cadena'PLANAR''PLANAR', 'CILÍNDRICO', o 'CÓNICO'.
metadata (opcional)CadenanuloDebe ser JSON válido si metadataIsJson es verdadero, y no puede superar los 2048 caracteres
metadataIsJson [Opcional]BooleanotruePueds establecerlo a false para utilizar la propiedad de metadatos como una cadena sin procesar
loadAutomatically [Opcional]BooleanofalseCada app está limitada a 5 objetivos de imagen con loadAutomatically: true
geometry.isRotated [Opcional]BooleanofalseEstablézcalo como verdadero si la imagen se prerrota de horizontal a vertical.
geometry.topintegerEstas propiedades especifican el recorte que se aplicará a su imagen. Debe tener una relación de aspecto de 3:4, y al menos 480x640.
geometry.leftinteger
geometry.widthinteger
geometry.heightinteger
geometry.topRadiusintegerSolo se necesita para tipo: 'CONICAL'
geometry.bottomRadiusintegerSolo se necesita para tipo: 'CONICAL'

Geometría de carga plana / cilíndrica

Este diagrama muestra cómo se aplica el recorte especificado a la imagen que has subido para generar las imágenes imageUrl y thumbnailImageUrl. La relación anchura:altura es siempre 3:4.

Diagrama que muestra cómo se aplican el recorte, la rotación y la escala a los objetivos de imágenes planas y cilíndricas

Para un recorte apaisado, sube la imagen girada 90 grados en el sentido de las agujas del reloj, establece geometry.isRotated: true, y especifica el recorte contra la imagen girada.

Diagrama que muestra cómo se aplican el recorte, la rotación y la escala a los objetivos de imagen planos y cilíndricos cuando isRotated es verdadero

Geometría de carga cónica

Este diagrama muestra cómo se aplana y recorta tu imagen subida en función de los parámetros. La imagen subida a tiene un formato "arco iris" en el que los bordes superior e inferior de tu contenido están alineados a dos círculos concéntricos. Si su objetivo es más estrecho por arriba que por abajo, especifica topRadius como el negativo del radio exterior, y bottomRadius como el radio interior (positivo). Para un recorte apaisado , establece geometry.isRotated: true, y la imagen aplanada se rotará antes de aplicarle el recorte .

Diagrama que muestra cómo se aplican el recorte, la rotación y la escala a los objetivos de imagen cónicos

Respuesta

Este es el formato de respuesta JSON estándar para los objetivos de imagen.

{
"name": "...",
"uuid": "...",
"type": "PLANAR",
"loadAutomatically": true,
"status": "AVAILABLE",
"appKey": "...",
"geometry": {
"top": 842,
"left": 392,
"width": 851,
"height": 1135,
"isRotated": true,
"originalWidth": 2000,
"originalHeight": 2000
},
"metadata": null,
"metadataIsJson": true,
"originalImageUrl": "https://cdn.8thwall.com/image-target/...",
"imageUrl": "https://cdn.8thwall.com/image-target/...",
"thumbnailImageUrl": "https://cdn.8thwall.com/image-target/...",
"geometryTextureUrl": "https://cdn.8thwall.com/image-target/...",
"created": 1613508074845,
"updated": 1613683291310
}
PropiedadTipoDescripción
nameCadena
uuidCadenaID único de este objetivo de imagen
tipoCadena'PLANAR', 'CILÍNDRICO', o 'CÓNICO'
loadAutomaticallyBooleano
statusCadena'AVAILABLE' o 'TAKEN_DOWN'
appKeyCadenaLa app a la que pertenece el objetivo
geometríaObjetoVer más abajo
metadataCadena
metadataIsJsonBooleano
originalImageUrlCadenaURL CDN de la imagen de origen que se subió
imageUrlCadenaVersión recortada de geometryTextureUrl
thumbnailImageUrlCadenaversión de 350px de alto de la imageUrl para su uso en miniaturas
geometryTextureUrlCadenaPara cónica, es una versión aplanada de la imagen original; para plana y cilíndrica, es igual que originalImageUrl
createdintegerFecha de creación en milisegundos después de la época unix
updatedintegerFecha de la última actualización en milisegundos después de la época unix

Geometría plana

PropiedadTipoDescripción
topinteger
leftinteger
widthinteger
heightinteger
isRotatedBooleano
originalWidthintegerAnchura de la imagen subida
originalHeightintegerAltura de la imagen subida

Geometría cilíndrica o cónica

Amplía las propiedades de Geometría plana con la alteración de que originalWidth y originalHeight se refieren a las dimensiones de la imagen aplanada almacenada en geometryTextureUrl.

PropiedadTipoDescripción
topRadiusfloat
bottomRadiusfloat
coninessfloatSiempre 0 para tipo: CILINDRO, derivado de radio superior/radio inferior para tipo: CÓNICO
cylinderCircumferenceTopfloatLa circunferencia del círculo completo trazado por el borde superior de tu objetivo
targetCircumferenceTopfloatLa longitud a lo largo del borde superior de tu objetivo antes de aplicar el recorte
cylinderCircumferenceBottomfloatDerivado de cylinderCircumferenceTop y topRadius/bottomRadius
cylinderSideLengthfloatDerivado de targetCircumferenceTop y las dimensiones de la imagen original
arcAnglefloatDerivado de cylinderCircumferenceTop y targetCircumferenceTop
inputModeCadena'BASIC' o 'ADVANCED'. Controla lo que ven los usuarios en la consola de 8th Wall, ya sean controles deslizantes o cuadros de introducción de números.

Listar objetivos de imagen

Consulte una lista de objetivos de imagen que pertenezcan a una app. Los resultados están paginados, lo que significa que si la app contiene más objetivos de imagen de los que se pueden devolver en una respuesta, tendrá que hacer varias peticiones para enumerar la lista completa de objetivos de imagen.

Solicitud

curl "https://api.8thwall.com/v1/apps/$APP_KEY/targets" -H "X-Api-Key:$SECRET_KEY"
ParámetroTipoDescripción
by [Opcional]CadenaEspecifica la columna por la que ordenar. Las opciones son "creado", "actualizado", "nombre" o "uuid".
dir [Opcional]CadenaControla la dirección de ordenación de la lista. O "asc" o "desc".
start [Opcional]CadenaEspecifica que la lista comienza con los elementos que tienen este valor en la columna by
after [Opcional]CadenaEspecifica que la lista comienza inmediatamente después de los elementos que tienen este valor
limit [Opcional]integerDebe estar entre 1 y 500
continuation [Opcional]CadenaSe utiliza para buscar la página siguiente a la consulta inicial.

Lista ordenada

Esta consulta enumera los objetivos de la app empezando por "z" y yendo hacia "a".

curl "https://api.8thwall.com/v1/apps/$APP_KEY/targets?by=name&dir=desc" -H "X-Api-Key:$SECRET_KEY"

Múltiples clasificaciones

Puedes especificar un parámetro secundario "ordenar por" que actúe como criterio de desempate en caso de duplicados en tu primer valor por. uuid se utiliza como criterio de desempate por defecto si no se especifica.

curl "https://api.8thwall.com/v1/apps/$APP_KEY/targets?by=updated&by=uuid" -H "X-Api-Key:$SECRET_KEY"

Especifica un punto de partida

Puede especificar inicio o después de los valores que corresponden a los valores por para especificar tu posición actual en la lista. Si quiere que su lista comience inmediatamente después del elemento con actualizado: 333 y uuid: 777, utilizaría:

curl "https://api.8thwall.com/v1/apps/$APP_KEY/targets?by=updated&by=uuid&start=333&after=777" -H "X-Api-Key:$SECRET_KEY"

De esta forma, los elementos con updated: 333 se siguen incluyendo en la página siguiente si su uuid es posterior a 777. Si el valor actualizado de un elemento es mayor que 333, pero su uuid es menor que 777, se seguirá incluyendo en la página siguiente porque la segunda propiedad por sólo entra en juego para los desempates.

No es válido especificar un valor después de para la ordenación principal mientras se proporciona un valor inicio para la ordenación de desempate. Por ejemplo, no sería válido especificar ?by=name&by=uuid&after=my-name-&start=333. En su lugar debería ser?by=nombre&by=uuid&after=mi-nombre- porque el segundo punto de inicio sólo entra en juego cuando el punto de inicio principal es inclusivo (utilizando inicio).

Diagrama que muestra cómo los parámetros by, start y after especifican el punto inicial de la lista

Respuesta

Objeto JSON que contiene la propiedad targets, que es una matriz de objetos objetivo de imagen en el formato estándar .

Si continuationToken está presente, para obtener la siguiente página de objetivos de imagen, tendrá que especificar ?continuation=[continuationToken] en una petición de seguimiento para obtener la siguiente página de objetivos de imagen.

{
"continuationToken": "...",
"targets": [{
"name": "...",
"uuid": "...",
"type": "PLANAR",
"loadAutomatically": true,
"status": "AVAILABLE",
"appKey": "...",
"geometry": {
"top": 842,
"left": 392,
"width": 851,
"height": 1135,
"isRotated": true,
"originalWidth": 2000,
"originalHeight": 2000
},
"metadata": null,
"metadataIsJson": true,
"originalImageUrl": "https://cdn.8thwall.com/image-target/...",
"imageUrl": "https://cdn.8thwall.com/image-target/...",
"thumbnailImageUrl": "https://cdn.8thwall.com/image-target/...",
"geometryTextureUrl": "https://cdn.8thwall.com/image-target/...",
"created": 1613508074845,
"updated": 1613683291310
}, {
"name": "...",
"uuid": "...",
"type": "CONICAL",
"loadAutomatically": true,
"status": "AVAILABLE",
"appKey": "...",
"geometry": {
"top": 0,
"left": 0,
"width": 480,
"height": 640,
"originalWidth": 886,
"originalHeight": 2048,
"isRotated": true,
"cylinderCircumferenceTop": 100,
"cylinderCircumferenceBottom": 40,
"targetCircumferenceTop": 50,
"cylinderSideLength": 21.63,
"topRadius": 1600,
"bottomRadius": 640,
"arcAngle": 180,
"coniness": 1.3219280948873624,
"inputMode": "BASIC"
},
"metadata": "{\"my-metadata\": 34534}",
"metadataIsJson": true,
"originalImageUrl": "https://cdn.8thwall.com/...",
"imageUrl": "https://cdn.8thwall.com/...",
"thumbnailImageUrl": "https://cdn.8thwall.com/...",
"geometryTextureUrl": "https://cdn.8thwall.com/...",
"created": 1613508074845,
"updated": 1613683291310
}]
}

Obtener objetivo de imagen

Solicitud

curl "https://api.8thwall.com/v1/targets/$TARGET_UUID" -H "X-Api-Key:$SECRET_KEY"

Respuesta

Objeto JSON del formato de objetivo de imagen estándar

Modificar el objetivo de imagen

Se pueden modificar las siguientes propiedades:

  • name
  • loadAutomatically
  • metadata
  • metadataIsJson

Se aplican las mismas reglas de validación que en la carga inicial

Para los objetivos de imagen cilíndricos y cónicos, también se pueden modificar las siguientes propiedades del objeto de geometría :

  • cylinderCircumferenceTop
  • targetCircumferenceTop
  • inputMode

Las demás propiedades geométricas del objetivo se actualizarán para que coincidan.

Solicitud

curl -X PATCH "https://api.8thwall.com/v1/targets/$TARGET_UUID"\
-H "X-Api-Key:$SECRET_KEY"\
-H "Content-Type: application/json"\
--data '{"name":"new-name", "geometry: {"inputMode": "BASIC"}, "metadata": "{}"}'

Respuesta

Objeto JSON del formato de objetivo de imagen estándar

Eliminar objetivo de imagen

Solicitud

curl -X DELETE "https://api.8thwall.com/v1/targets/$TARGET_UUID" -H "X-Api-Key:$SECRET_KEY"

Respuesta

Una eliminación correcta devolverá una respuesta vacía con el código de estado 204: Sin contenido.

Vista previa del objetivo de imagen

Genera una URL que los usuarios puedan utilizar para previsualizar el seguimiento de un objetivo.

Solicitud

curl "https://api.8thwall.com/v1/targets/$TARGET_UUID/test" -H "X-Api-Key:$SECRET_KEY"

Respuesta

{
"url": "https://8w.8thwall.app/previewit/?j=...",
"token": "...",
"exp": 1612830293128
}
PropiedadTipoDescripción
urlCadenaLa URL que puede utilizarse para previsualizar el seguimiento del objetivo
tokenCadenaActualmente, este token solo puede ser utilizado por nuestra aplicación de previsualización.
expintegerLa marca de tiempo en milisegundos de cuándo caducará el token. Las fichas caducan una hora después de su emisión.

La funcionalidad de previsualización está pensada para ser utilizada en el contexto de un usuario específico que gestione o configure objetivos de imagen. No publique las URL de previsualización en un sitio público ni las compartas con un gran número de usuarios.

Prácticas recomendadas para experiencias de previsualización personalizadas: La URL de previsualización que devuelve la API es la experiencia de 8th Wall genérica de previsualización de objetivos de imagen. Si quiere personalizar aún más el frontend de la vista previa de tu objetivo de imagen, siga estos pasos:

  1. Crear un proyecto público de 8th Wall
  2. Personaliza la UX de este proyecto según sus especificaciones
  3. Sube los objetivos de imagen que los usuarios quieran probar a través de la API utilizando la clave de la aplicación para el proyecto que creó en el paso 1
  4. Genera una URL de destino de imagen comprobable para los usuarios finales utilizando la URL pública del proyecto en el paso 1 y un parámetro URL con el nombre del objetivo de imagen
  5. En el proyecto que has creado en el paso 1, utiliza el parámetro URL para establecer el objetivo de imagen activo mediante la llamada XR8.XrController.configure({imageTargets: ['theTargetName']}).

Tratamiento de errores

Si la API rechaza su solicitud, la respuesta será Content-Type: application/json, y el cuerpo contendrá un mensaje `` propiedad que contiene una cadena de error.

Ejemplo

{
"message": "App not found: ..."
}

Códigos de estado

EstadoRazón
400Esto puede ocurrir si has especificado un valor no válido, o has proporcionado un parámetro que no existe.
403Esto puede ocurrir si no proporcionas correctamente su clave secreta.
404La app o el objetivo de imagen podrían estar borrados, o la clave de la app o el UUID del objetivo son incorrectos. Este es también el código de respuesta si la clave API proporcionada no coincide con el recurso al que intentas acceder.
413La imagen cargada ha sido rechazada por ser un archivo demasiado grande.
429Su Clave API ha superado su límite de velocidad asociado.