2023-01-20 10:41:00 +00:00
|
|
|
|
<!-- Do not edit this file directly, edit its companion .md instead
|
|
|
|
|
and regenerate this file using nixos/doc/manual/md-to-db.sh -->
|
2021-10-01 09:20:50 +00:00
|
|
|
|
<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>
|
2023-01-20 10:41:00 +00:00
|
|
|
|
<programlisting language="nix">
|
2021-10-01 09:20:50 +00:00
|
|
|
|
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>
|
2023-01-20 10:41:00 +00:00
|
|
|
|
pict-rs offers the following endpoints:
|
2021-10-01 09:20:50 +00:00
|
|
|
|
</para>
|
2023-01-20 10:41:00 +00:00
|
|
|
|
<itemizedlist>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
<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>
|
|
|
|
|
<para>
|
|
|
|
|
This endpoint returns the following JSON structure on success
|
|
|
|
|
with a 201 Created status
|
|
|
|
|
</para>
|
|
|
|
|
<programlisting language="json">
|
2021-10-01 09:20:50 +00:00
|
|
|
|
{
|
|
|
|
|
"files": [
|
|
|
|
|
{
|
|
|
|
|
"delete_token": "JFvFhqJA98",
|
|
|
|
|
"file": "lkWZDRvugm.jpg"
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
"delete_token": "kAYy9nk2WK",
|
|
|
|
|
"file": "8qFS0QooAn.jpg"
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
"delete_token": "OxRpM3sf0Y",
|
|
|
|
|
"file": "1hJaYfGE01.jpg"
|
|
|
|
|
}
|
|
|
|
|
],
|
|
|
|
|
"msg": "ok"
|
|
|
|
|
}
|
|
|
|
|
</programlisting>
|
2023-01-20 10:41:00 +00:00
|
|
|
|
</listitem>
|
2021-10-01 09:20:50 +00:00
|
|
|
|
<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:
|
|
|
|
|
</para>
|
2023-01-20 10:41:00 +00:00
|
|
|
|
<programlisting language="json">
|
|
|
|
|
{
|
|
|
|
|
"width": 800,
|
|
|
|
|
"height": 537,
|
|
|
|
|
"content_type": "image/webp",
|
|
|
|
|
"created_at": [
|
|
|
|
|
2020,
|
|
|
|
|
345,
|
|
|
|
|
67376,
|
|
|
|
|
394363487
|
|
|
|
|
]
|
|
|
|
|
}
|
|
|
|
|
</programlisting>
|
2021-10-01 09:20:50 +00:00
|
|
|
|
</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
|
2023-01-20 10:41:00 +00:00
|
|
|
|
</para>
|
|
|
|
|
<programlisting>
|
|
|
|
|
GET /image/process.jpg?src=asdf.png&thumbnail=256&blur=3.0
|
|
|
|
|
</programlisting>
|
|
|
|
|
<para>
|
2021-10-01 09:20:50 +00:00
|
|
|
|
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>
|