Home A - Z
Page Index

An Otter Wiki

Blame

83f413 DonovanDMC 2026-01-16 18:04:17
1 
# Images
2
3
An [[API Key|YiffyAPI/APIKey]] is <span style="color: red;">not</span> required for MOST endpoints of this service. See [[Shared Responses|YiffyAPI/Shared Responses]] for common error responses.
4
5
<hr>
6
7
## Online Check
8
> <code><span style="color: rgb(52, 141, 248);">GET</span></code> `https://v2.yiff.rest/online`
9
10
::: success
11
# 200 OK: Success
b0919f DonovanDMC 2026-01-16 18:07:15
12
```json
83f413 DonovanDMC 2026-01-16 18:04:17
13
{
14
"success": true,
15
"uptime": 0
16
}
17
```
18
:::
19
20
<hr>
21
22
## List Categories
23
> <code><span style="color: rgb(52, 141, 248);">GET</span></code> `https://v2.yiff.rest/categories`
24
25
::: success
26
# 200 OK: Success
b0919f DonovanDMC 2026-01-16 18:07:15
27
```json
83f413 DonovanDMC 2026-01-16 18:04:17
28
{
29
"success": true,
30
"data": [
31
{
32
"name": "Animals > Birb",
33
"db": "animals.birb",
34
"sfw": true,
35
"count": 0
36
}
37
]
38
}
39
```
40
:::
41
42
<hr>
43
44
## Get Category
45
> <code><span style="color: rgb(52, 141, 248);">GET</span></code> `https://v2.yiff.rest/categories/{db}`
46
47
::: none
48
# Path Parameters
49
| Name | Type | Description |
50
| ----------------------------------------------------- | ------ | --------------------------------------------------------------------------------- |
51
| db <span style="color: red" title="required">*</span> | String | The "db" representation of the category (see [List Categories](#list-categories)) |
52
:::
53
54
::: success
55
# 200 OK: Success
b0919f DonovanDMC 2026-01-16 18:07:15
56
```json
83f413 DonovanDMC 2026-01-16 18:04:17
57
{
58
"success": true,
59
"data": {
60
"name": "Animals > Birb",
61
"db": "animals.birb",
62
"sfw": true,
63
"count": 0
64
}
65
}
66
```
67
:::
68
69
::: danger
70
# 404 Not Found: Not Found
b0919f DonovanDMC 2026-01-16 18:07:15
71
```json
83f413 DonovanDMC 2026-01-16 18:04:17
72
{
73
"success": false,
74
"code": 1030,
75
"error": "Category not found."
76
}
77
```
78
:::
79
2fca76 DonovanDMC 2026-01-16 19:15:19
80
<hr>
81
83f413 DonovanDMC 2026-01-16 18:04:17
82
## Get Image
83
> <code><span style="color: rgb(52, 141, 248);">GET</span></code> `https://v2.yiff.rest/images/{id}`
84
85
::: none
86
# Path Parameters
87
| Name | Type | Description |
88
| ----------------------------------------------------- | ------ | ------------------------ |
89
| id <span style="color: red" title="required">*</span> | String | The ID[^1] of the image. |
90
:::
91
92
::: success
93
# 200 OK: Success
b0919f DonovanDMC 2026-01-16 18:07:15
94
```json
83f413 DonovanDMC 2026-01-16 18:04:17
95
{
96
"success": true,
97
"data": {
98
"artists": ["tazara"],
99
"sources": [
100
"https://e621.net/posts/4332280",
101
"https://www.furaffinity.net/view/35895655/",
102
"https://d.furaffinity.net/art/tazara/1586784421/1586784421.tazara_stephen-small__1_.png",
103
"https://www.furaffinity.net/user/tazara/"
104
],
105
"width": 1275,
106
"height": 726,
107
"url": "https://static1.e621.net/data/18/ec/18ec7925aed47626e6420dc30e2804ef.png",
108
"type": "image/png",
109
"name": "18ec7925aed47626e6420dc30e2804ef.png",
110
"id": "3552ab3a5ae34c69a58852ef0a1c02f9",
111
"md5": "18ec7925aed47626e6420dc30e2804ef",
112
"ext": "png",
113
"size": 1687084,
114
"reportURL": "https://e621.net/posts/4332280", // nullable
115
"shortURL": "https://yiff.rocks/3552ab3a5ae34c69a58852ef0a1c02f9",
116
"external": true,
117
"viewable": true,
b0919f DonovanDMC 2026-01-16 18:07:15
118
"seen": 0,
83f413 DonovanDMC 2026-01-16 18:04:17
119
"category": "furry.cuddle"
120
}
121
}
122
```
123
:::
124
125
::: danger
126
# 404 Not Found: Not Found
b0919f DonovanDMC 2026-01-16 18:07:15
127
```json
83f413 DonovanDMC 2026-01-16 18:04:17
128
{
129
"success": false,
130
"code": 1040,
131
"error": "Image not found."
132
}
133
```
134
:::
135
7dc31b DonovanDMC 2026-01-16 18:08:12
136
[^1]: In most cases the md5 of the image will also work. For internally hosted images, the id and md5 will always be the same. For externally hosted images, they will be different. Regardless using the md5 of external images should work all the same.
83f413 DonovanDMC 2026-01-16 18:04:17
137
138
<hr>
139
140
## Get Random Image
141
> <code><span style="color: rgb(52, 141, 248);">GET</span></code> `https://v2.yiff.rest/{category}`
142
143
::: none
144
# Path Parameters
145
| Name | Type | Description |
146
| ----------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
147
| category <span style="color: red" title="required">*</span> | String | The category to get an image from. See [List Categories](#list-categories) for a list of categories. Take the `db` property, and replace any periods with forward slashes.[^2] |
148
:::
149
150
::: none
151
# Query Parameters
152
| Name | Type | Description |
153
| --------- | ------- | -------------------------------------------------------------------------------------- |
154
| amount | Number | The amount of images to request, between 1-5. |
155
| notes | Boolean | If notes should be hidden. |
6c0cf6 DonovanDMC 2026-01-16 18:09:09
156
| sizeLimit | String | The maximum size of images to return, in powers of 2. Units such as KB/MB can be used. |
83f413 DonovanDMC 2026-01-16 18:04:17
157
:::
158
159
::: success
160
# 200 OK: Success
b0919f DonovanDMC 2026-01-16 18:07:15
161
```json
83f413 DonovanDMC 2026-01-16 18:04:17
162
{
163
"$schema": "https://schema.yiff.rest/V2.json",
164
"images": [
165
{
166
"artists": ["tazara"],
167
"sources": [
168
"https://e621.net/posts/4332280",
169
"https://www.furaffinity.net/view/35895655/",
170
"https://d.furaffinity.net/art/tazara/1586784421/1586784421.tazara_stephen-small__1_.png",
171
"https://www.furaffinity.net/user/tazara/"
172
],
173
"width": 1275,
174
"height": 726,
175
"url": "https://static1.e621.net/data/18/ec/18ec7925aed47626e6420dc30e2804ef.png",
176
"type": "image/png",
177
"name": "18ec7925aed47626e6420dc30e2804ef.png",
178
"id": "3552ab3a5ae34c69a58852ef0a1c02f9",
179
"md5": "18ec7925aed47626e6420dc30e2804ef",
180
"ext": "png",
181
"size": 1687084,
182
"reportURL": "https://e621.net/posts/4332280", // nullable
183
"shortURL": "https://yiff.rocks/3552ab3a5ae34c69a58852ef0a1c02f9",
184
"external": true,
185
"viewable": true,
b0919f DonovanDMC 2026-01-16 18:07:15
186
"seen": 0,
83f413 DonovanDMC 2026-01-16 18:04:17
187
"category": "furry.cuddle"
188
}
189
],
190
"success": true,
191
"notes": [
192
{
193
"id": 0,
194
"content": ""
195
}
196
]
197
}
198
```
199
:::
200
201
::: info
202
# Notes
203
204
| ID | Content | Active |
205
| -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
206
| 1 | `This api host (api.furry.bot) is being removed on June 9th, 2021. Please migrate to https://yiff.rest.` | No |
207
| 2 | `We've moved to using subdomains for api versioning! e.g. https://v2.yiff.rest. They have the same functionality, just without the version in the path. The /V2 route will not be removed, but any future api versions will only use the subdomain.` | Yes |
208
| 3 | `Hey, we see you aren't using an api key. They're free! To get one, visit https://yiff.rest/apikeys.` | Yes |
209
| 4 | `WARNING! This list is STATIC, it can be inaccurate! We recommended parsing the dot notation in https://v2.yiff.rest/categories instead of this!` | No |
210
| 5 | `Since images are getting bigger, we're adding a size limit parameter. Add ?sizeLimit=<size> to limit the size of images we provide you.` | Yes |
211
| 6 | `You can now hide these notes by setting the notes parameter to disabled. (ex: ?notes=disabled)` | Yes |
212
| 7 | `We now have proper documentation: https://docs.yiff.rest` | Yes |
213
| 8 | `We have a new service available, a thumbnailer for e621. You can see its documentation at https://docs.yiff.rest/thumbnails.` | Yes |
214
215
:::
216
217
::: danger
218
# 400 Bad Request: Amount < 1
b0919f DonovanDMC 2026-01-16 18:07:15
219
```json
83f413 DonovanDMC 2026-01-16 18:04:17
220
{
221
"success": false,
222
"code": 1051,
223
"error": "Amount must be 1 or more."
224
}
225
```
226
:::
227
228
::: danger
229
# 400 Bad Request: Amount > 5
b0919f DonovanDMC 2026-01-16 18:07:15
230
```json
83f413 DonovanDMC 2026-01-16 18:04:17
231
{
232
"success": false,
233
"code": 1052,
234
"error": "Amount must be 5 or less."
235
}
236
```
237
:::
238
239
::: danger
240
# 400 Bad Request: No Results Found
b0919f DonovanDMC 2026-01-16 18:07:15
241
```json
83f413 DonovanDMC 2026-01-16 18:04:17
242
{
243
"success": false,
244
"code": 1041,
245
"error": "No results were found. Try changing your search parameters."
246
}
247
```
248
:::
249
250
::: danger
251
# 404 Not Found: Category Not Found
b0919f DonovanDMC 2026-01-16 18:07:15
252
```json
83f413 DonovanDMC 2026-01-16 18:04:17
253
{
254
"success": false,
255
"code": 1030,
256
"error": "Category not found."
257
}
258
```
259
:::
260
261
[^2]: Currently, using the dot notation as is will work, but this is considered legacy behavior and could be broken without notice.
262
263
<hr>
264
265
## Get Images Bulk
266
> <code><span style="color: rgb(0, 136, 71);">POST</span></code> `https://v2.yiff.rest/bulk`
267
268
<p>Get an arbitrary amount of images across many categories. This endpoint requires an api key, and is restricted to developer approval.</p>
269
<p>By default, a maximum of 100 images total can be fetched in one request.You can request your limit to be raised by contacting a developer.</p>
270
271
::: none
272
# Query Parameters
273
| Name | Type | Description |
274
| --------- | ------- | -------------------------------------------------------------------------------------- |
6c0cf6 DonovanDMC 2026-01-16 18:09:09
275
| sizeLimit | String | The maximum size of images to return, in powers of 2. Units such as KB/MB can be used. |
83f413 DonovanDMC 2026-01-16 18:04:17
276
:::
277
278
::: none
279
# Body Parameters
280
| Name | Type | Description |
281
| ---------------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- |
282
| some.category <span style="color: red" title="required">*</span> | Number | A map of category (in db format) to the amount of images. See [List Categories](#list-categories) for a list of categories. |
283
:::
284
285
::: success
286
# 200 OK: Success
b0919f DonovanDMC 2026-01-16 18:07:15
287
```json
83f413 DonovanDMC 2026-01-16 18:04:17
288
{
289
"success": true,
290
"data": {
291
"furry.cuddle": [
292
{
293
"artists": ["tazara"],
294
"sources": [
295
"https://e621.net/posts/4332280",
296
"https://www.furaffinity.net/view/35895655/",
297
"https://d.furaffinity.net/art/tazara/1586784421/1586784421.tazara_stephen-small__1_.png",
298
"https://www.furaffinity.net/user/tazara/"
299
],
300
"width": 1275,
301
"height": 726,
302
"url": "https://static1.e621.net/data/18/ec/18ec7925aed47626e6420dc30e2804ef.png",
303
"type": "image/png",
304
"name": "18ec7925aed47626e6420dc30e2804ef.png",
305
"id": "3552ab3a5ae34c69a58852ef0a1c02f9",
306
"md5": "18ec7925aed47626e6420dc30e2804ef",
307
"ext": "png",
308
"size": 1687084,
309
"reportURL": "https://e621.net/posts/4332280", // nullable
310
"shortURL": "https://yiff.rocks/3552ab3a5ae34c69a58852ef0a1c02f9",
311
"external": true,
312
"viewable": true,
b0919f DonovanDMC 2026-01-16 18:07:15
313
"seen": 0,
83f413 DonovanDMC 2026-01-16 18:04:17
314
"category": "furry.cuddle"
315
}
316
]
317
}
318
}
319
```
320
:::
321
322
::: danger
323
# 400 Bad Request: Invalid Body
b0919f DonovanDMC 2026-01-16 18:07:15
324
```json
83f413 DonovanDMC 2026-01-16 18:04:17
325
{
326
"success": false,
327
"code": 1054,
328
"error": "Invalid body, or no categories specified."
329
}
330
```
331
:::
332
333
::: danger
334
# 400 Bad Request: Invalid Category
b0919f DonovanDMC 2026-01-16 18:07:15
335
```json
83f413 DonovanDMC 2026-01-16 18:04:17
336
{
337
"success": false,
338
"code": 1030,
339
"error": "Invalid category specified: invalid.category"
340
}
341
```
342
:::
343
344
::: danger
345
# 400 Bad Request: Too Many Images Requested
b0919f DonovanDMC 2026-01-16 18:07:15
346
```json
83f413 DonovanDMC 2026-01-16 18:04:17
347
{
348
"success": false,
349
"code": 1056,
350
"error": "Total amount of images requested is greater than {limit} ({total})"
351
}
352
```
353
:::