api.frankerfacez.com
Open in
urlscan Pro
2606:4700:20::ac43:4647
Public Scan
Submitted URL: http://api.frankerfacez.com/
Effective URL: https://api.frankerfacez.com/docs/
Submission: On December 16 via api from RU — Scanned from DE
Effective URL: https://api.frankerfacez.com/docs/
Submission: On December 16 via api from RU — Scanned from DE
Form analysis 1 forms found in the DOM
<form class="download-url-wrapper"><label class="select-label" for="select"><span>Select a definition</span><select id="select">
<option value="https://api.frankerfacez.com/v1/swagger.json">API v1</option>
<option value="https://api.frankerfacez.com/v2/swagger.json">API v2</option>
<option value="https://api.frankerfacez.com/auth/swagger.json">Authentication</option>
<option value="https://cdn.frankerfacez.com/swagger.json">CDN</option>
</select></label></form>Text Content
Select a definitionAPI v1API v2AuthenticationCDN
FRANKERFACEZ
1.0
OAS3
https://api.frankerfacez.com/v1/swagger.json
Get emotes. Set emotes. Be one with the emotes.
ABOUT EMOTES
There are a few values on the emote model returned by our API that are not
immediately obvious what they do, so we'd like to explain how they work.
FieldDescription idThe integer ID of an emote. IDs will always be numbers in API
v1, though in a future release we may switch to using strings. nameThe name of
an emote. This is the text string in chat that should be replaced with an
instance of the emote. heightThe height of the emote at 1x scale in pixels.
widthThe width of the emote at 1x scale in pixels. publicA public emote can be
freely added to channels and collections on FrankerFaceZ. Non-public emotes
require the owner's permission in the form of an unlock code. hiddenWhether or
not the emote should be displayed in UI like menus that list available emotes.
This is rarely used, and was intended to create easter eggs. modifierWhether or
not the emote is a modifier emote. See the secton on Modifier Emotes below for
more details. modifier_flagsA bitset of flags for customizing how a modifier
functions. See the section on Emote Effects below for more details. offsetThis
is deprecated and should not be used in the future. marginsThis is deprecated
and should not be used in the future. cssThis is deprecated and should not be
used in the future. ownerInformation about the user that uploaded the emote,
including their FFZ user ID, username, and display name. artistIf a separate
artist has been set for an emote, information about the artist of the emote,
including their FFZ user ID, username, and display name. urlsA map of DPI scales
to emote URLs. There will always be a 1 entry and there may also be 2 and 4
entries for 2x and 4x DPI scales as well. Previously, URLs were sent as
network-path references (see RFC 3986 for details) but now all URLs are
absolute. Sorry for the inconvenience this has caused. animatedA map of DPI
scales to animated emote URLs. This functions the same as urls but may be null
if the emote is not animated. These URLs currently return WebP images but may
return a different type in the future. You may append .webp to the end of the
URL to ensure you receive a WebP response, or append .gif to receive a GIF
response. Please avoid GIF if you are able. maskIf the emote is a modifier emote
that applies a mask, a map of DPI scales to mask image URLs. This may be null if
the emote is not a modifier with an associated mask. mask_animatedIf the emote
is a modifier emote that applies a mask, and the mask is animated, a map of DPI
scales to mask image URLs. This may be null if the emote is not a modifier with
an associated mask or if that mask does not have animation. statusA numeric
status for emotes in our system. This should always be 1 in APIv1 responses as
that represents an emote that has been approved. usage_countThe number of
channels and/or collections that the emote has been added to. created_atThe
datetime when the emote was created. last_updatedThe datetime when the emote was
last modified.
> Note: Masks are not yet being used, but will be handled in the official client
> by applying a mask-image to the base emote image. The presence of a mask map
> is enough to know that the modifier applies a mask. There will not be an
> associated flag.
MODIFIER EMOTES
Modifier emotes are emotes that appear over top of other emotes or otherwise
change how another emote is presented.
To use a modifier emote, users must first use another emote and then follow it
with one or more modifiers, separated by spaces. If a modifier is used without a
target emote directly before it, the modifier will appear as a normal emote
instead. Including anything between the target emote and modifiers other than
whitespace will result prevent the effect from working and the modifier will be
displayed as a normal emote instead.
When displaying modifiers, they should be vertically and horizontally centered
over the target emote. The official FFZ client handles this by containing an
emote and its modifiers within a container element that has position: relative
and that scales to the size of the target emote. Modifiers are then absolutely
positioned within that container to center them. For example, assume the target
emote is CatBag which has a width of 32 pixels and a height of 29 pixels. Let's
also assume that the modifier in use is LookingOutAWreath. A hypothetical
container might look like:
<figure style="display: inline-block; position: relative; width: 32px; height: 29px">
<img src="https://cdn.frankerfacez.com/emoticon/25927/1">
<img
style="position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%)"
src="https://cdn.frankerfacez.com/emoticon/147011/1"
>
</figure>
That would result in something appearing like the following:
EMOTE EFFECTS
> I realize that implementing these effects can potentially be a lot of work for
> a developer, especially if they aren't using a client that renders chat via
> HTML and CSS. In the future I'd like to potentially offer a server endpoint
> that prerenders emotes with effects. Unfortunately, we lack the resources to
> do that at this time.
>
> For now, please at least check for the Hidden flag to avoid rendering
> modifiers that should be hidden. I think that would give users without full
> support in their client of choice the best experience.
In addition to appearing on top of a target emote, modifiers can also have other
visual effects on the presentation of the target emote. These additional
properties are controlled through a bitset of flags stored in an emote's
modifier_flags field. The following is a table of all currently available
modifiers:
> Note: Holes in the following table represent flags that were used in testing
> and removed without being associated with any current effect emote.
ValueFlagDescriptionExample 1HiddenThe modifier should not be rendered. This is
set for modifiers that have other visual effects on targets. They should not be
displayed, and only have images for use when used incorrectly (and thus
appearing as a normal emote) or for display in UX such as emote menus. 2FlipXThe
target emote should be flipped horizontally. 4FlipYThe target emote should be
flipped vertically. 8GrowXThe target emote should have its width doubled. 16Not
yet implemented. 32Not yet implemented. 64Not yet implemented. 128Not yet
implemented. 256Not yet implemented. 512Not yet implemented. 1024Not yet
implemented. 2048RainbowThe target emote should have its hue rotated over time,
creating a rainbow animation effect. 4096HyperRedThe target emote should have
its image modified to turn it red and increase its contrast to create an effect
similar to "HYPER" emotes.(Example combined with next effect.) 8192HyperShakeThe
target emote should shake quickly to create an effect similar to "HYPER" emotes.
16384CursedThe target emote should have its image modified to greatly increase
its contrast while reducing its brightness slightly and reducing it to
greyscale, creating an effect similar to cursed / despair emotes. 32768JamThe
target emote should have an animation applied to create the illusion of
headbanging / shaking to a rhythm. 65536BounceThe target emote should have an
animation applied so that it squishes down, flips horizontally, squishes down
again, and flips back to the original orientation before repeating.
A modifier emote may have one or more flag set, and all existing effect emotes
so far have the Hidden flag set in addition to the flag(s) for whatever specific
effect they produce.
For example, the ffzHyper effect emote has the flags Hidden | HyperRed |
HyperShake giving it a numeric value of 12_289.
ABOUT EMOTE SETS
Emote sets, also known as collections, are exactly what they sound like: a set
containing one or more emotes. There are several types of sets that might be
encountered:
1. Every channel has a primary emote set which all users within that channel
can use freely. These emote sets are included in the responses of /v1/room
endpoints, with the ID given in a room's set property and the contents of
the emote set included in a map later in the response.
2. There is at least one global emote set that all users across Twitch can use
freely. There may be more than one of these emote sets if there is a special
event happening. These sets are included in the response of
/v1/set/global/ids with their IDs given in the default_sets array and the
contents of the emote sets included in a map later in the response.
3. There is at least one global emote set that is only usable by specific
users. There may be more than one of these emote sets. These sets are
included in the response of /v1/set/global/ids with a users map where the
keys of the map are emote set IDs and the values of the map are arrays of
Twitch IDs.
While we would appreciate it if third-party clients support these, we
understand if you choose not to. However, if not supporting them then please
make sure to at least not include them at all rather than including them as
available for all users.
Emote set objects, in addition to their array of emotes, will include a title
that can be displayed when relevant describing the source of the emote set such
as a channel that the emote set is associated with. Emote sets may also include
an icon that may be used when displaying the emote set such as within an emote
menu. If included, the icon will be the URL of an image which may be a PNG,
WebP, or SVG image.
RATE LIMITS
FrankerFaceZ uses rate limits to help prevent our API from being overloaded. We
use the generic cell rate algorithm, which is a leaky bucket-type limiter.
The default limits are as follows:
ConditionFill RateBucket Size User token is provided800 points per user per
OAuth client800 points App token is provided300 points per OAuth Client300
points No token120 points per IP address120 points
Note: Limits are not per IP address when an app token or user token is provided.
If you exhaust your available points, an error is returned: HTTP 429 Too Many
Requests
When you make an API request, you will receive a set of headers containing
information pertaining to rate limiting:
HeaderDescription RateLimit-LimitThe maximum number of points you can spend
within one minute. RateLimit-RemainingThe remaining points in your bucket.
RateLimit-ResetThe number of seconds remaining until your bucket will refill to
maximum capacity. Retry-AfterThe number of seconds until you should retry. Only
sent if a request was denied due to an exhausted capacity.
If you require a higher rate limit, please ask in the general development
channel of our Discord.
Terms of service
Servers
https://api.frankerfacez.com - Production API Server
USERS
GET/v1/user/{userName}
Get a user by name
GET/v1/_user/{userName}
Get a user by name, without extra data
GET/v1/user/id/{twitchID}
Get a user by Twitch ID
GET/v1/_user/id/{twitchID}
Get a user by Twitch ID, without extra data
GET/v1/user/_id/{userID}
Get a user by FFZ ID
GET/v1/_user/_id/{userID}
Get a user by FFZ ID, without extra data
GET/v1/user/yt/{youtubeID}
Get a user by YouTube ID
GET/v1/_user/yt/{youtubeID}
Get a user by YouTube ID, without extra data
EMOTES
GET/v1/emote/{emoteID}/recommend
[WIP] Get recommended emotes to an emote
GET/v1/emote/{emoteID}/similar
[WIP] Get similar emotes (by image) to an emote
GET/v1/emote/{emoteID}
Get an emote by ID
GET/v1/emotes
Get emotes in bulk
GET/v1/emoticons
Get emotes in bulk
BADGES
GET/v1/badge/{badgeID}
Get a badge by ID or name
GET/v1/_badge/{badgeID}
Get a badge by ID or name (plain)
GET/v1/badges
Get all badges (with user names)
GET/v1/_badges
Get all badges (plain)
GET/v1/badges/ids
Get all badges (with user IDs)
ROOMS
GET/v1/room/id/{twitchID}
Get a room by Twitch ID
GET/v1/room/_id/{userID}
Get a room by FFZ ID
GET/v1/room/{roomName}
Get a room by Twitch login
GET/v1/room/yt/{youtubeID}
Get a room by YouTube ID
GET/v1/_room/id/{twitchID}
Get a room by Twitch ID (plain)
GET/v1/_room/_id/{userID}
Get a room by FFZ ID (plain)
GET/v1/_room/{roomName}
Get a room by Twitch login (plain)
GET/v1/_room/yt/{youtubeID}
Get a room by YouTube ID (plain)
GET/v1/multi_room/{roomNames}
Get multiple rooms by Twitch login
GET/v1/multi_room/id/{roomIDs}
Get multiple rooms by Twitch ID
GET/v1/multi_room/_id/{roomIDs}
Get multiple rooms by FFZ ID
GET/v1/_multi_room/{roomNames}
Get multiple rooms by Twitch login (plain)
GET/v1/_multi_room/id/{roomIDs}
Get multiple rooms by Twitch ID (plain)
GET/v1/_multi_room/_id/{roomIDs}
Get multiple rooms by FFZ ID (plain)
GET/v1/rooms/{roomNames}
Get limited info for multiple rooms by Twitch login
GET/v1/rooms/id/{roomIDs}
Get limited info for multiple rooms by Twitch ID
GET/v1/rooms/_id/{roomIDs}
Get limited info for multiple rooms by FFZ ID
EMOTE SETS
GET/v1/set/global
Get all globally applicable emote sets
GET/v1/set/global/ids
Get all globally applicable emote sets, with user Twitch IDs
GET/v1/_set/global
Get all globally applicable emote sets, without any extra data
GET/v1/set/{setID}
Get an emote set by ID
GET/v1/set/{setID}/ids
Get an emote set by ID, including user Twitch IDs
GET/v1/_set/{setID}
Get an emote set by ID, without a users list
SCHEMAS
User
Badge
Emote
EmoteSet
Room