> 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/docs.facephi-pt-br/sdks/backend-sdk/backend1n/technical_documentation/api_reference/media/assets-upload.md).

# /assets/upload

Stores an image in the database. Only JPEG, PNG or BMP images are accepted; any other content is rejected with 400. The collection `collectionId` must exist. The image becomes associated with a specimen when it is created with `POST /faces`. The `file` field is sent as a binary file in a `multipart/form-data` part, like any other field of an HTML form with a file input - it is not a text field and does not require encoding (neither base64 nor hexadecimal).

Example with curl:

```bash
curl -F "file=@image.jpg" -F "collectionId=bank01_collection01" -F "mimeType=image/jpeg" http://127.0.0.1:6982/assets/upload
```

````json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"servers":[{"url":"http://127.0.0.1:6982/"}],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT signed with HS256 (shared secret `auth_jwt_secret`) and with a non-expired `exp` claim; if it includes `nbf`, it must be currently valid. Only applied if `auth_enabled` is true and `auth_accept_authorization_header` is true. The `Bearer` scheme is case-insensitive.\n"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"The same JWT sent in an API key header. The default name is `x-api-key` and it can be changed with `auth_api_key_header_name`; only applied if `auth_accept_api_key_header` is true. If both headers are sent, `Authorization` takes precedence.\n"}},"schemas":{"AssetUploadBody":{"type":"object","description":"Body for the asset upload request in `multipart/form-data`","properties":{"file":{"$ref":"#/components/schemas/BinaryImage"},"collectionId":{"$ref":"#/components/schemas/CollectionId"},"mimeType":{"$ref":"#/components/schemas/MimeType"}},"required":["file","collectionId"]},"BinaryImage":{"type":"string","format":"binary","description":"Binary image data in JPEG, PNG or BMP format, sent or received as is (not encoded in base64 or in any other text format)."},"CollectionId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]+$","description":"An identifier that allows grouping different images or biometric templates in a common space. It can only contain ASCII letters (A-Z, a-z), digits (0-9), underscore (`_`) and hyphen (`-`); it cannot be empty and it is case-sensitive. The following are **not allowed**: spaces, dots, `+`, `:`, `@`, quotes, `%`, `~`, `/`, or non-ASCII characters (`ñ`, accents, emoji...): the identifier is used as a path parameter and any other character prevents its use. It must correspond to a collection previously created with `POST /collections`.\n"},"MimeType":{"type":"string","description":"Identifier of the file format (`image/jpeg`, `image/png` or `image/bmp`). If not included, it defaults to 'image/jpeg'. It is the value that will be returned as `Content-Type` when the image is downloaded.\n"},"UploadMediaResponse":{"type":"object","description":"Media upload response. The identifier is returned in `id` (elsewhere in the API this same value is called `mediaId`).","properties":{"id":{"$ref":"#/components/schemas/MediaId"}}},"MediaId":{"type":"string","description":"An identifier of an image in the database. Each image is associated with a single specimen (face): the uploaded image becomes associated when the face is created with `POST /faces` and it is deleted together with it (`DELETE /faces/{Id}`) or together with its collection (`DELETE /collections/{collectionId}`).\n"},"BadRequestResult":{"type":"object","description":"Result when incorrect parameters arrive in the request.","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string","description":"Specific description of the reason for the error. It is the only field that indicates the real cause."},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}},"TimeStamp":{"type":"string","description":"A date/time value (UTC) in \"%Y-%m-%dT%H:%M:%SZ\" format."},"UnauthorizedResult":{"type":"object","description":"JWT authentication is enabled and the request does not pass it. It is accompanied by the header `WWW-Authenticate: Bearer`. Values of `message`: `Missing authentication token` (no token or unsupported scheme), `JWT token validation failed` (invalid signature, algorithm or format), `JWT token is expired`, `JWT token does not include exp claim` and `JWT token is not yet valid` (future `nbf`).\n","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string"},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}},"ExceptionResult":{"type":"object","description":"An error occurred while calling the backend services.","properties":{"status":{"type":"number"},"error":{"type":"string"},"exception":{"type":"string","description":"Specific description of the reason for the exception (internal service text; it is not part of the contract)."},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}}},"responses":{"Unauthorized":{"description":"JWT authentication is enabled and the token is missing or invalid.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResult"}}}},"PayloadTooLarge":{"description":"The request body exceeds `client_max_body_size`. It is returned with no body and the connection is closed."}}},"paths":{"/assets/upload":{"post":{"description":"Stores an image in the database. Only JPEG, PNG or BMP images are accepted; any other content\nis rejected with 400. The collection `collectionId` must exist. The image becomes associated with a specimen when\nit is created with `POST /faces`. The `file` field is sent as a binary file in a\n`multipart/form-data` part, like any other field of an HTML form with a file input -\nit is not a text field and does not require encoding (neither base64 nor hexadecimal).\n\nExample with curl:\n\n```bash\ncurl -F \"file=@image.jpg\" -F \"collectionId=bank01_collection01\" -F \"mimeType=image/jpeg\" http://127.0.0.1:6982/assets/upload\n```\n","tags":["Media"],"requestBody":{"description":"Image data in multipart/form-data.","required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/AssetUploadBody"},"encoding":{"file":{"contentType":"image/jpeg, image/png, image/bmp"}}}}},"responses":{"200":{"description":"The result of the upload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadMediaResponse"}}}},"400":{"description":"Incorrect parameters arrive in the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"description":"An error occurred while calling the backend.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExceptionResult"}}}}}}}}}
````