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