> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/api-rest/midapi-v2/storage/save-asset.md). # Save Asset Servicio que almacena un asset en un contexto de una operación y devuelve la clave con la que se referencia después. ### Endpoint ``` POST /storage ``` ### Headers | Nombre | Tipo | Requerido | Descripción | | ----------------- | ------ | --------- | --------------------------------------------------------------------------------------------------------- | | **Authorization** | string | **Sí** | Token de consumer en formato `Bearer `. Ver [Autenticación](/api-rest/midapi-v2/autenticacion.md). | | **consumer-id** | string | **Sí** | Identificador del consumer. | ### Cuerpo de la solicitud **Content-Type:** `application/json` #### Parámetros | Parámetro | Tipo | Requerido | Descripción | | --------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `operationId` | string | **Sí** | Identificador de la operación a la que pertenece el asset, tal como lo devolvió [Create Operation](/api-rest/midapi-v2/operations/create-operation.md). | | `asset` | object | **Sí** | Asset a almacenar. | | `asset.context` | string | **Sí** | Contexto del asset. Admite `TOKEN_FRONT_DOCUMENT`, `TOKEN_BACK_DOCUMENT`, `TOKEN_FACE_IMAGE`, `TOKEN_BEST_IMAGE`, `TOKEN_BIN_IAD` y `RAW_IMAGE`. `TOKEN_RAW_IMAGE` no se admite aquí: es el contexto con el que queda almacenada una subida `RAW_IMAGE`, y declararlo se rechaza con `400`. Ver [Contextos de asset](/api-rest/midapi-v2/storage.md#contextos-de-asset). | | `asset.file` | string | **Sí** | Contenido del asset codificado en **Base64**, con el formato que exige su contexto. | {% hint style="warning" %} Cada contexto exige un formato concreto. Los cuatro contextos tokenizados, `TOKEN_FRONT_DOCUMENT`, `TOKEN_BACK_DOCUMENT`, `TOKEN_FACE_IMAGE` y `TOKEN_BEST_IMAGE`, exigen el buffer tokenizado generado por el SDK de captura, y en ellos una imagen JPEG o PNG en Base64 se rechaza con `400`. `TOKEN_BIN_IAD` acepta el binario de la captura. `RAW_IMAGE` es el único contexto que toma una imagen en abierto, JPEG o PNG en Base64. {% endhint %} El tamaño máximo por asset es de **10 MiB**, aplicado al contenido codificado. #### Ejemplo de solicitud ```json { "operationId": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04", "asset": { "context": "TOKEN_FRONT_DOCUMENT", "file": "" } } ``` ### Respuestas #### `200` Éxito #### Parámetros de respuesta | Parámetro | Tipo | Descripción | | ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fileKey` | string | Clave del asset, con la forma `{operationId}/{CONTEXTO}`. Se reenvía sin modificar al referenciar el asset. | | `derivedFileKey` | string | Clave del asset derivado por esta subida, con la misma forma. Solo aparece en una subida `TOKEN_BIN_IAD` de la que se derivó la mejor imagen. Ver [Contextos derivados](#contextos-derivados). | | `timestamp` | string | Marca de tiempo de la respuesta en formato **ISO 8601**. | #### Ejemplo de respuesta ```json { "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_FRONT_DOCUMENT", "timestamp": "2026-06-26T12:00:03.000Z" } ``` En una subida `RAW_IMAGE` el contexto de la clave no es el declarado: la imagen en abierto se tokeniza al recibirla y la respuesta devuelve `TOKEN_RAW_IMAGE`, que es el contexto con el que se referencia el asset a partir de ese momento. ```json { "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_RAW_IMAGE", "timestamp": "2026-06-26T12:00:03.000Z" } ``` #### Contextos derivados Al almacenar un asset `TOKEN_BIN_IAD` queda disponible además el contexto `TOKEN_BEST_IMAGE` de la misma operación, con la mejor imagen de esa captura. Puede almacenarse un `TOKEN_BEST_IMAGE` propio después; si ya hay uno almacenado, se conserva ese. La respuesta devuelve la clave de esa mejor imagen en `derivedFileKey`, lista para usarse en las validaciones que la aceptan, como prueba de vida o comparación facial: ```json { "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_BIN_IAD", "derivedFileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_BEST_IMAGE", "timestamp": "2026-06-26T12:00:03.000Z" } ``` `derivedFileKey` nombra lo que derivó esa subida, así que no aparece cuando la operación ya tenía almacenado un `TOKEN_BEST_IMAGE` propio: ahí no se deriva nada y se conserva el que ya estaba. Tampoco aparece en la subida de cualquier otro contexto. Consulta [Get File Keys](/api-rest/midapi-v2/operations/get-file-keys.md) para confirmar qué contextos hay disponibles en la operación. #### Otras respuestas | Código | Descripción | | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | El `operationId` no tiene el formato esperado, el contenido no corresponde al contexto declarado, el contexto declarado no se admite en la subida (`TOKEN_RAW_IMAGE`, que solo se obtiene subiendo `RAW_IMAGE`), o el asset está vacío o excede el tamaño máximo. | | `403` | El consumer no está aprovisionado con el servicio `STORAGE`. | | `404` | La operación no existe o pertenece a otro consumer. | | `409` | Ya existe un asset de ese contexto en la operación. | | `410` | La operación ha caducado. | | `429` | El consumer ha superado su límite de tasa de peticiones. La respuesta incluye `Retry-After` con los segundos de espera, y `X-RateLimit-Limit` y `X-RateLimit-Burst` con los umbrales vigentes. | | `503` | La imagen en abierto de una subida `RAW_IMAGE` no se pudo tokenizar. No se almacena nada. | El cuerpo de una respuesta de error tiene la forma descrita en [Middleware API v2](/api-rest/midapi-v2.md#respuestas-de-error).