1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-pict-rs">
<title>Pict-rs</title>
<para>
pict-rs is a a simple image hosting service.
</para>
<section xml:id="module-services-pict-rs-quickstart">
<title>Quickstart</title>
<para>
the minimum to start pict-rs is
</para>
<programlisting language="bash">
services.pict-rs.enable = true;
</programlisting>
<para>
this will start the http server on port 8080 by default.
</para>
</section>
<section xml:id="module-services-pict-rs-usage">
<title>Usage</title>
<para>
pict-rs offers the following endpoints: -
<literal>POST /image</literal> for uploading an image. Uploaded
content must be valid multipart/form-data with an image array
located within the <literal>images[]</literal> key
</para>
<programlisting>
This endpoint returns the following JSON structure on success with a 201 Created status
```json
{
"files": [
{
"delete_token": "JFvFhqJA98",
"file": "lkWZDRvugm.jpg"
},
{
"delete_token": "kAYy9nk2WK",
"file": "8qFS0QooAn.jpg"
},
{
"delete_token": "OxRpM3sf0Y",
"file": "1hJaYfGE01.jpg"
}
],
"msg": "ok"
}
```
</programlisting>
<itemizedlist>
<listitem>
<para>
<literal>GET /image/download?url=...</literal> Download an
image from a remote server, returning the same JSON payload as
the <literal>POST</literal> endpoint
</para>
</listitem>
<listitem>
<para>
<literal>GET /image/original/{file}</literal> for getting a
full-resolution image. <literal>file</literal> here is the
<literal>file</literal> key from the <literal>/image</literal>
endpoint’s JSON
</para>
</listitem>
<listitem>
<para>
<literal>GET /image/details/original/{file}</literal> for
getting the details of a full-resolution image. The returned
JSON is structured like so:
<literal>json { "width": 800, "height": 537, "content_type": "image/webp", "created_at": [ 2020, 345, 67376, 394363487 ] }</literal>
</para>
</listitem>
<listitem>
<para>
<literal>GET /image/process.{ext}?src={file}&...</literal>
get a file with transformations applied. existing
transformations include
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
<literal>identity=true</literal>: apply no changes
</para>
</listitem>
<listitem>
<para>
<literal>blur={float}</literal>: apply a gaussian blur to
the file
</para>
</listitem>
<listitem>
<para>
<literal>thumbnail={int}</literal>: produce a thumbnail of
the image fitting inside an <literal>{int}</literal> by
<literal>{int}</literal> square using raw pixel sampling
</para>
</listitem>
<listitem>
<para>
<literal>resize={int}</literal>: produce a thumbnail of
the image fitting inside an <literal>{int}</literal> by
<literal>{int}</literal> square using a Lanczos2 filter.
This is slower than sampling but looks a bit better in
some cases
</para>
</listitem>
<listitem>
<para>
<literal>crop={int-w}x{int-h}</literal>: produce a cropped
version of the image with an <literal>{int-w}</literal> by
<literal>{int-h}</literal> aspect ratio. The resulting
crop will be centered on the image. Either the width or
height of the image will remain full-size, depending on
the image’s aspect ratio and the requested aspect ratio.
For example, a 1600x900 image cropped with a 1x1 aspect
ratio will become 900x900. A 1600x1100 image cropped with
a 16x9 aspect ratio will become 1600x900.
</para>
</listitem>
</itemizedlist>
<para>
Supported <literal>ext</literal> file extensions include
<literal>png</literal>, <literal>jpg</literal>, and
<literal>webp</literal>
</para>
<para>
An example of usage could be
<literal>GET /image/process.jpg?src=asdf.png&thumbnail=256&blur=3.0</literal>
which would create a 256x256px JPEG thumbnail and blur it
</para>
</listitem>
<listitem>
<para>
<literal>GET /image/details/process.{ext}?src={file}&...</literal>
for getting the details of a processed image. The returned
JSON is the same format as listed for the full-resolution
details endpoint.
</para>
</listitem>
<listitem>
<para>
<literal>DELETE /image/delete/{delete_token}/{file}</literal>
or <literal>GET /image/delete/{delete_token}/{file}</literal>
to delete a file, where <literal>delete_token</literal> and
<literal>file</literal> are from the <literal>/image</literal>
endpoint’s JSON
</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="module-services-pict-rs-missing">
<title>Missing</title>
<itemizedlist spacing="compact">
<listitem>
<para>
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.
</para>
</listitem>
</itemizedlist>
</section>
</chapter>
|