nixpkgs/nixos/modules/services/web-apps/pict-rs.xml

<!-- Do not edit this file directly, edit its companion .md instead
     and regenerate this file using nixos/doc/manual/md-to-db.sh -->
<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="nix">
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:
    </para>
    <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">
{
    &quot;files&quot;: [
        {
            &quot;delete_token&quot;: &quot;JFvFhqJA98&quot;,
            &quot;file&quot;: &quot;lkWZDRvugm.jpg&quot;
        },
        {
            &quot;delete_token&quot;: &quot;kAYy9nk2WK&quot;,
            &quot;file&quot;: &quot;8qFS0QooAn.jpg&quot;
        },
        {
            &quot;delete_token&quot;: &quot;OxRpM3sf0Y&quot;,
            &quot;file&quot;: &quot;1hJaYfGE01.jpg&quot;
        }
    ],
    &quot;msg&quot;: &quot;ok&quot;
}
</programlisting>
      </listitem>
      <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>
        <programlisting language="json">
{
    &quot;width&quot;: 800,
    &quot;height&quot;: 537,
    &quot;content_type&quot;: &quot;image/webp&quot;,
    &quot;created_at&quot;: [
        2020,
        345,
        67376,
        394363487
    ]
}
</programlisting>
      </listitem>
      <listitem>
        <para>
          <literal>GET /image/process.{ext}?src={file}&amp;...</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
        </para>
        <programlisting>
GET /image/process.jpg?src=asdf.png&amp;thumbnail=256&amp;blur=3.0
</programlisting>
        <para>
          which would create a 256x256px JPEG thumbnail and blur it
        </para>
      </listitem>
      <listitem>
        <para>
          <literal>GET /image/details/process.{ext}?src={file}&amp;...</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>