# Images API

\
Get random image
----------------

<mark style="color:blue;">`GET`</mark> `https://api.ksoft.si/images/random-image`

Gets random image from the specified tag.

#### Query Parameters

| Name | Type    | Description                             |
| ---- | ------- | --------------------------------------- |
| nsfw | boolean | Default: false, if to show nsfw content |
| tag  | string  | Name of the tag                         |

#### Headers

| Name           | Type   | Description          |
| -------------- | ------ | -------------------- |
| Authentication | string | Authentication token |

{% tabs %}
{% tab title="200 Image successfully retrieved." %}

```javascript
{
    "url": "https://api-cdn.ksoft.si/media/i-p_gksmnq-84.jpg",
    "snowflake": "i-p_gksmnq-84",
    "nsfw": false,
    "tag": "birb"
}
```

{% endtab %}

{% tab title="404 Could not find an image matching this query." %}

```javascript
{
    "code": 404,
    "message": "Nothing found using your query.",
    "cache": false
}
```

{% endtab %}
{% endtabs %}

## List of Tags

<mark style="color:blue;">`GET`</mark> `https://api.ksoft.si/images/tags`

Retrieve the list of all available tags.

#### Headers

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | Authorization token |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "models": [
        {
            "name": "pepe",
            "nsfw": false
        },
        {
            "name": "doge",
            "nsfw": false
        },
        {
            "name": "kappa",
            "nsfw": false
        },
        {
            "name": "dab",
            "nsfw": false
        },
        {
            "name": "birb",
            "nsfw": false
        },
        {
            "name": "dog",
            "nsfw": false
        },
        {
            "name": "hentai_gif",
            "nsfw": true
        },
        {
            "name": "floofs",
            "nsfw": false
        },
        {
            "name": "lewd",
            "nsfw": true
        },
        {
            "name": "fbi",
            "nsfw": false
        },
        {
            "name": "neko",
            "nsfw": true
        },
        {
            "name": "Glomp",
            "nsfw": false
        },
        {
            "name": "lick",
            "nsfw": false
        },
        {
            "name": "kiss",
            "nsfw": false
        },
        {
            "name": "smack",
            "nsfw": false
        },
        {
            "name": "spank",
            "nsfw": false
        },
        {
            "name": "pat",
            "nsfw": false
        },
        {
            "name": "hug",
            "nsfw": false
        }
    ],
    "tags": [
        "pepe",
        "doge",
        "kappa",
        "dab",
        "birb",
        "dog",
        "floofs",
        "fbi",
        "Glomp",
        "lick",
        "kiss",
        "smack",
        "spank",
        "pat",
        "hug"
    ],
    "nsfw_tags": [
        "hentai_gif",
        "lewd",
        "neko"
    ]
}
```

{% endtab %}
{% endtabs %}

## Tag search

<mark style="color:blue;">`GET`</mark> `https://api.ksoft.si/images/tags/{search}`

Search for tags.

#### Path Parameters

| Name   | Type   | Description  |
| ------ | ------ | ------------ |
| search | string | Search query |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Authentication token |

{% tabs %}
{% tab title="200 If you replace {search} in the URL with "birb" you get this response:" %}

```javascript
{
    "models": [
        {
            "name": "birb",
            "nsfw": false
        }
    ],
    "tags": [
        "birb"
    ]
}
```

{% endtab %}
{% endtabs %}

## Get image from ID (snowflake)

<mark style="color:blue;">`GET`</mark> `https://api.ksoft.si/images/image/{snowflake}`

Retrieve image data.

#### Path Parameters

| Name      | Type   | Description                 |
| --------- | ------ | --------------------------- |
| snowflake | string | Image snowflake (unique ID) |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Authentication token |

{% tabs %}
{% tab title="200 For example if you replace {snowflake} with i-hcz0h5bg-33 the API will return this:" %}

```javascript
{
    "url": "https://api-cdn.ksoft.si/media/i-hcz0h5bg-33.jpg",
    "snowflake": "i-hcz0h5bg-33",
    "nsfw": false,
    "tag": "birb"
}
```

{% endtab %}

{% tab title="404 If image with that identifier does not exist." %}

```javascript
{
    "code": 404,
    "message": "Image does not exist."
}
```

{% endtab %}
{% endtabs %}

## Get random meme

<mark style="color:blue;">`GET`</mark> `https://api.ksoft.si/images/random-meme`

Retrieves a random meme from the cache. Source: reddit

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Authentication token |

{% tabs %}
{% tab title="200 Retrieves a random meme in a reddit object." %}

```javascript
{
    "title": "I do it all the time",
    "image_url": "https://i.imgur.com/I7jphHT.jpg",
    "source": "https://www.reddit.com/r/memes/comments/9gsc6e/i_do_it_all_the_time/",
    "subreddit": "r/memes",
    "upvotes": 4331,
    "downvotes": 173,
    "comments": 100,
    "created_at": 1537251612,
    "nsfw": false,
    "author": "/u/Holofan4life",
    "awards": 0
}
```

{% endtab %}
{% endtabs %}

## Wikihow

<mark style="color:blue;">`GET`</mark> `https://api.ksoft.si/images/random-wikihow`

Retrieves weird images from WikiHow

#### Query Parameters

| Name | Type    | Description                                 |
| ---- | ------- | ------------------------------------------- |
| nsfw | boolean | Default: false, if to display nsfw content. |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Authentication token |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "url": "https://api-cdn.ksoft.si/media/wikihow/i-movo1mn4.jpg",
    "title": "Pierce Your Own Belly Button At Home",
    "nsfw": false,
    "article_url": "https://www.wikihow.com/pierce-your-own-belly-button-at-home"
}
```

{% endtab %}
{% endtabs %}

## Random cute pictures

<mark style="color:blue;">`GET`</mark> `https://api.ksoft.si/images/random-aww`

Get random cute pictures, mostly animals.

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Authentication token |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "title": "no words for this love",
    "image_url": "https://i.redd.it/g4pof35510o11.jpg",
    "source": "https://www.reddit.com/r/Eyebleach/comments/9i8rwo/no_words_for_this_love/",
    "subreddit": "r/Eyebleach",
    "upvotes": 110,
    "downvotes": 1,
    "comments": 4,
    "created_at": 1537713156,
    "nsfw": false,
    "author": "/u/rosliasantamaria",
    "awards": 0
}
```

{% endtab %}
{% endtabs %}

## Random NSFW

<mark style="color:blue;">`GET`</mark> `https://api.ksoft.si/images/random-nsfw`

Retrieves random NSFW pics. (real life stuff)

#### Query Parameters

| Name | Type    | Description                                           |
| ---- | ------- | ----------------------------------------------------- |
| gifs | boolean | Default: false, if to retrieve gifs instead of images |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Authentication token |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "title": "Good morning",
    "image_url": "https://i.redd.it/example.nsfw",
    "source": "https://www.reddit.com/r/pawg/comments/9gk6rx/good_morning/",
    "subreddit": "r/pawg",
    "upvotes": 4179,
    "downvotes": 83,
    "comments": 49,
    "created_at": 1537189909,
    "nsfw": true,
    "author": "/u/thementaltyrant",
    "awards": 0
}
```

{% endtab %}
{% endtabs %}

## Random images from a subreddit

<mark style="color:blue;">`GET`</mark> `https://api.ksoft.si/images/rand-reddit/{subreddit}`

Retrieve images from the specified subreddit.

#### Path Parameters

| Name      | Type   | Description         |
| --------- | ------ | ------------------- |
| subreddit | string | Specified subreddit |

#### Query Parameters

| Name         | Type    | Description                                                                                                                           |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| remove\_nsfw | boolean | Default: false, if set to true, endpoint will filter out nsfw posts.                                                                  |
| span         | string  | Default: "day", select range from which to get the images. Can be one of the following: "hour", "day", "week", "month", "year", "all" |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Authentication token |

{% tabs %}
{% tab title="200 Normal response, if down-vote count is zero, it's probably because the post hasn't been updated by our background workers." %}

```javascript
{
    "title": "Its Treason Then",
    "image_url": "https://i.redd.it/4t2kvw1040o11.jpg",
    "source": "https://www.reddit.com/r/PrequelMemes/comments/9i8vx0/its_treason_then/",
    "subreddit": "r/PrequelMemes",
    "upvotes": 3564,
    "downvotes": 0,
    "comments": 39,
    "created_at": 1537714103,
    "nsfw": false,
    "author": "/u/Skie69",
    "awards": 0
}
```

{% endtab %}

{% tab title="400 This is returned when span parameter has an unexpected value." %}

```javascript
{
    "error": true,
    "code": 125,
    "message": "span parameter has an invalid value. can be: day (default), hour, week, month, year or all"
}
```

{% endtab %}

{% tab title="404 This is returned when the subreddit doesn't exist." %}

```javascript
{
    "error": 404,
    "message": "subreddit not found"
}
```

{% endtab %}

{% tab title="410 " %}

```javascript
{

    "error": true,
    "code": 130,
    "message": "reddit returned no results, try extending your span to week or month (set 'span' GET parameter)"
}
```

{% endtab %}
{% endtabs %}