nixos/modules/services/web-apps/pict-rs.md

   1 # Pict-rs {#module-services-pict-rs}
   2
   3 pict-rs is a  a simple image hosting service.
   4
   5 ## Quickstart {#module-services-pict-rs-quickstart}
   6
   7 the minimum to start pict-rs is
   8
   9 ```nix
  10 {
  11   services.pict-rs.enable = true;
  12 }
  13 ```
  14
  15 this will start the http server on port 8080 by default.
  16
  17 ## Usage {#module-services-pict-rs-usage}
  18
  19 pict-rs offers the following endpoints:
  20
  21 - `POST /image` for uploading an image. Uploaded content must be valid multipart/form-data with an
  22     image array located within the `images[]` key
  23
  24     This endpoint returns the following JSON structure on success with a 201 Created status
  25     ```json
  26     {
  27         "files": [
  28             {
  29                 "delete_token": "JFvFhqJA98",
  30                 "file": "lkWZDRvugm.jpg"
  31             },
  32             {
  33                 "delete_token": "kAYy9nk2WK",
  34                 "file": "8qFS0QooAn.jpg"
  35             },
  36             {
  37                 "delete_token": "OxRpM3sf0Y",
  38                 "file": "1hJaYfGE01.jpg"
  39             }
  40         ],
  41         "msg": "ok"
  42     }
  43     ```
  44 - `GET /image/download?url=...` Download an image from a remote server, returning the same JSON
  45     payload as the `POST` endpoint
  46 - `GET /image/original/{file}` for getting a full-resolution image. `file` here is the `file` key from the
  47     `/image` endpoint's JSON
  48 - `GET /image/details/original/{file}` for getting the details of a full-resolution image.
  49     The returned JSON is structured like so:
  50     ```json
  51     {
  52         "width": 800,
  53         "height": 537,
  54         "content_type": "image/webp",
  55         "created_at": [
  56             2020,
  57             345,
  58             67376,
  59             394363487
  60         ]
  61     }
  62     ```
  63 - `GET /image/process.{ext}?src={file}&...` get a file with transformations applied.
  64     existing transformations include
  65     - `identity=true`: apply no changes
  66     - `blur={float}`: apply a gaussian blur to the file
  67     - `thumbnail={int}`: produce a thumbnail of the image fitting inside an `{int}` by `{int}`
  68         square using raw pixel sampling
  69     - `resize={int}`: produce a thumbnail of the image fitting inside an `{int}` by `{int}` square
  70         using a Lanczos2 filter. This is slower than sampling but looks a bit better in some cases
  71     - `crop={int-w}x{int-h}`: produce a cropped version of the image with an `{int-w}` by `{int-h}`
  72         aspect ratio. The resulting crop will be centered on the image. Either the width or height
  73         of the image will remain full-size, depending on the image's aspect ratio and the requested
  74         aspect ratio. For example, a 1600x900 image cropped with a 1x1 aspect ratio will become 900x900. A
  75         1600x1100 image cropped with a 16x9 aspect ratio will become 1600x900.
  76
  77     Supported `ext` file extensions include `png`, `jpg`, and `webp`
  78
  79     An example of usage could be
  80     ```
  81     GET /image/process.jpg?src=asdf.png&thumbnail=256&blur=3.0
  82     ```
  83     which would create a 256x256px JPEG thumbnail and blur it
  84 - `GET /image/details/process.{ext}?src={file}&...` for getting the details of a processed image.
  85     The returned JSON is the same format as listed for the full-resolution details endpoint.
  86 - `DELETE /image/delete/{delete_token}/{file}` or `GET /image/delete/{delete_token}/{file}` to
  87     delete a file, where `delete_token` and `file` are from the `/image` endpoint's JSON
  88
  89 ## Missing {#module-services-pict-rs-missing}
  90
  91 - Configuring the secure-api-key is not included yet. The envisioned basic use case is consumption on localhost by other services without exposing the service to the internet.