me.byjp.emojify.suggestEmoji Documentation (EN)

main query

Suggest emoji whose meaning best matches a short passage of text.

Parameters

limit integer Optional

Maximum number of suggestions to return.

text string Required

The passage of text to match, up to 600 units. Despite the maxGraphemes field name, the limit is actually enforced in Unicode code points (runes), not user-perceived graphemes — a single multi-rune grapheme cluster (e.g. a ZWJ family emoji) counts as multiple units toward it. maxLength is in UTF-8 bytes, not runes — emoji-laden input can run up to 4 bytes per rune. Note that the underlying model reads at most 256 tokens (~1300 runes of ordinary English, far fewer for punctuation-dense text); anything beyond that is ignored rather than rejected, and a long passage whose subject is a small fraction of the text tends to yield a generic suggestion.

Output

Encodingapplication/json

suggestions array Required

No description available.

Errors

TextTooLong text exceeds the 600-unit limit (counted in Unicode code points/runes, not graphemes).

NoMatch no suggestion cleared the minimum score.

RateLimitExceeded too many requests from this client; slow down and retry.

Overloaded the server is at capacity and shed this request; retry after a short delay.

Try It

Requests are sent directly from your browser. Some servers may block requests due to CORS.

Service Endpoint Base URL for XRPC calls (e.g., https://api.bsky.social)

Parameters

limit Maximum number of suggestions to return.

text * The passage of text to match, up to 600 units. Despite the maxGraphemes field name, the limit is actually enforced in Unicode code points (runes), not user-perceived graphemes — a single multi-rune grapheme cluster (e.g. a ZWJ family emoji) counts as multiple units toward it. maxLength is in UTF-8 bytes, not runes — emoji-laden input can run up to 4 bytes per rune. Note that the underlying model reads at most 256 tokens (~1300 runes of ordinary English, far fewer for punctuation-dense text); anything beyond that is ignored rather than rejected, and a long passage whose subject is a small fraction of the text tends to yield a generic suggestion.

View raw schema

{
  "type": "query",
  "errors": [
    {
      "name": "TextTooLong",
      "description": "text exceeds the 600-unit limit (counted in Unicode code points/runes, not graphemes)."
    },
    {
      "name": "NoMatch",
      "description": "no suggestion cleared the minimum score."
    },
    {
      "name": "RateLimitExceeded",
      "description": "too many requests from this client; slow down and retry."
    },
    {
      "name": "Overloaded",
      "description": "the server is at capacity and shed this request; retry after a short delay."
    }
  ],
  "output": {
    "schema": {
      "type": "object",
      "required": [
        "suggestions"
      ],
      "properties": {
        "suggestions": {
          "type": "array",
          "items": {
            "ref": "#suggestion",
            "type": "ref"
          }
        }
      }
    },
    "encoding": "application/json"
  },
  "parameters": {
    "type": "params",
    "required": [
      "text"
    ],
    "properties": {
      "text": {
        "type": "string",
        "maxLength": 2400,
        "description": "The passage of text to match, up to 600 units. Despite the maxGraphemes field name, the limit is actually enforced in Unicode code points (runes), not user-perceived graphemes — a single multi-rune grapheme cluster (e.g. a ZWJ family emoji) counts as multiple units toward it. maxLength is in UTF-8 bytes, not runes — emoji-laden input can run up to 4 bytes per rune. Note that the underlying model reads at most 256 tokens (~1300 runes of ordinary English, far fewer for punctuation-dense text); anything beyond that is ignored rather than rejected, and a long passage whose subject is a small fraction of the text tends to yield a generic suggestion.",
        "maxGraphemes": 600
      },
      "limit": {
        "type": "integer",
        "default": 3,
        "maximum": 5,
        "minimum": 1,
        "description": "Maximum number of suggestions to return."
      }
    }
  },
  "description": "Suggest emoji whose meaning best matches a short passage of text."
}

suggestion object

No description available.

Properties

emoji string Required

The suggested emoji.

name string Required

The emoji's CLDR label.

score integer Required

A similarity score — cosine similarity between the query and this emoji's meaning, adjusted by a per-emoji penalty that suppresses generically-matching emoji — expressed in per-mille (parts per thousand, 0-1000). This is not basis points (which would be parts per ten-thousand). Divide by 1000 for the 0..1 float value used internally — this is an integer because the lexicon primitive set has no float type.

minimum: 0maximum: 1000

View raw schema

{
  "type": "object",
  "required": [
    "emoji",
    "name",
    "score"
  ],
  "properties": {
    "name": {
      "type": "string",
      "description": "The emoji's CLDR label."
    },
    "emoji": {
      "type": "string",
      "description": "The suggested emoji."
    },
    "score": {
      "type": "integer",
      "maximum": 1000,
      "minimum": 0,
      "description": "A similarity score — cosine similarity between the query and this emoji's meaning, adjusted by a per-emoji penalty that suppresses generically-matching emoji — expressed in per-mille (parts per thousand, 0-1000). This is not basis points (which would be parts per ten-thousand). Divide by 1000 for the 0..1 float value used internally — this is an integer because the lexicon primitive set has no float type."
    }
  }
}