openapi: 3.1.0
info:
  title: GIPHY API
  description: |
    The GIPHY API provides programmatic access to the world's largest library of
    GIFs, stickers, animated emoji and Clips (GIFs with sound). Search, trending,
    translate, random, and category endpoints all return rich media objects with
    multiple image renditions optimized for any surface.

    Authentication is via API key. New developers receive a rate-limited Beta key;
    a Production key is granted after application review.
  version: '1.0'
  contact:
    name: GIPHY Developers
    url: https://developers.giphy.com/
    email: support@giphy.com
  termsOfService: https://developers.giphy.com/terms/
  license:
    name: GIPHY API Terms of Service
    url: https://developers.giphy.com/terms/
servers:
  - url: https://api.giphy.com
    description: Production API
  - url: https://upload.giphy.com
    description: Upload API
security:
  - ApiKeyAuth: []
tags:
  - name: GIFs
    description: Search, trending, translate, random, and lookup endpoints for animated GIFs.
  - name: Stickers
    description: The same surface as GIFs but scoped to transparent-background stickers.
  - name: Emoji
    description: GIPHY's animated emoji library and per-emoji variations.
  - name: Clips
    description: GIFs with sound. Access is gated; contact clips@giphy.com.
  - name: Animate
    description: Programmatic creation of animated text/word GIFs.
  - name: Channels
    description: Channel discovery and metadata.
  - name: Categories
    description: Top-level categories and subcategories used to organize GIFs.
  - name: Search Discovery
    description: Tag autocompletion, related search terms, and trending search queries.
  - name: Analytics
    description: Pingback and action register endpoints for measuring user engagement.
  - name: Upload
    description: Programmatic upload of GIFs and video assets.
  - name: Utilities
    description: Identifier generation and other helpers.
paths:
  /v1/gifs/search:
    get:
      tags: [GIFs]
      operationId: searchGifs
      summary: Search GIFs
      description: Search GIPHY's library of millions of GIFs by keyword.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: q
          in: query
          required: true
          description: Search query term or phrase, URL-encoded, max 50 characters.
          schema: { type: string, maxLength: 50 }
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Rating'
        - $ref: '#/components/parameters/Lang'
        - $ref: '#/components/parameters/Bundle'
        - $ref: '#/components/parameters/RandomId'
        - $ref: '#/components/parameters/CountryCode'
      responses:
        '200': { $ref: '#/components/responses/GifListResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v1/gifs/trending:
    get:
      tags: [GIFs]
      operationId: getTrendingGifs
      summary: Get Trending GIFs
      description: Return the most relevant and engaging GIFs each day.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Rating'
        - $ref: '#/components/parameters/Bundle'
        - $ref: '#/components/parameters/RandomId'
        - $ref: '#/components/parameters/CountryCode'
      responses:
        '200': { $ref: '#/components/responses/GifListResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v1/gifs/translate:
    get:
      tags: [GIFs]
      operationId: translateGif
      summary: Translate Term to GIF
      description: Convert words and phrases to a single, contextually relevant GIF.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: s
          in: query
          required: true
          description: Search term to translate to a GIF.
          schema: { type: string }
        - $ref: '#/components/parameters/Weirdness'
        - $ref: '#/components/parameters/Rating'
        - $ref: '#/components/parameters/RandomId'
      responses:
        '200': { $ref: '#/components/responses/SingleGifResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /v1/gifs/random:
    get:
      tags: [GIFs]
      operationId: getRandomGif
      summary: Get Random GIF
      description: Return a single random GIF, optionally filtered by tag.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: tag
          in: query
          required: false
          description: Filter results by tag.
          schema: { type: string }
        - $ref: '#/components/parameters/Rating'
        - $ref: '#/components/parameters/RandomId'
      responses:
        '200': { $ref: '#/components/responses/SingleGifResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /v1/gifs/{gif_id}:
    get:
      tags: [GIFs]
      operationId: getGifById
      summary: Get GIF by ID
      description: Retrieve metadata for a single GIF.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: gif_id
          in: path
          required: true
          description: GIPHY ID of the GIF.
          schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/SingleGifResponse' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/gifs/categories:
    get:
      tags: [Categories]
      operationId: listGifCategories
      summary: List GIF Categories
      description: Return the list of GIF categories.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A paginated list of categories.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Category' } }
                  pagination: { $ref: '#/components/schemas/Pagination' }
                  meta: { $ref: '#/components/schemas/Meta' }
  /v1/gifs/search/tags:
    get:
      tags: [Search Discovery]
      operationId: autocompleteSearchTags
      summary: Autocomplete Search Tags
      description: Return tag suggestions for a partial search term.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: q
          in: query
          required: true
          description: Partial search term.
          schema: { type: string }
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Tag autocomplete results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string }
                        analytics_response_payload: { type: string }
  /v1/tags/related/{term}:
    get:
      tags: [Search Discovery]
      operationId: getRelatedSearchTerms
      summary: Get Related Search Terms
      description: Return related search terms for a given query.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: term
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Related search terms.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string }
                        analytics_response_payload: { type: string }
  /v1/trending/searches:
    get:
      tags: [Search Discovery]
      operationId: getTrendingSearches
      summary: Get Trending Search Terms
      description: Return the most popular search terms across GIPHY.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Trending search terms.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: string } }
                  meta: { $ref: '#/components/schemas/Meta' }
  /v1/stickers/search:
    get:
      tags: [Stickers]
      operationId: searchStickers
      summary: Search Stickers
      description: Search GIPHY's library of stickers (transparent-background animations).
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: q
          in: query
          required: true
          schema: { type: string, maxLength: 50 }
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Rating'
        - $ref: '#/components/parameters/Lang'
      responses:
        '200': { $ref: '#/components/responses/GifListResponse' }
  /v1/stickers/trending:
    get:
      tags: [Stickers]
      operationId: getTrendingStickers
      summary: Get Trending Stickers
      description: Return the most relevant and engaging stickers each day.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Rating'
      responses:
        '200': { $ref: '#/components/responses/GifListResponse' }
  /v1/stickers/translate:
    get:
      tags: [Stickers]
      operationId: translateSticker
      summary: Translate Term to Sticker
      description: Convert words and phrases to a single contextually relevant sticker.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: s
          in: query
          required: true
          schema: { type: string }
        - $ref: '#/components/parameters/Weirdness'
        - $ref: '#/components/parameters/Rating'
      responses:
        '200': { $ref: '#/components/responses/SingleGifResponse' }
  /v1/stickers/random:
    get:
      tags: [Stickers]
      operationId: getRandomSticker
      summary: Get Random Sticker
      description: Return a single random sticker, optionally filtered by tag.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: tag
          in: query
          required: false
          schema: { type: string }
        - $ref: '#/components/parameters/Rating'
      responses:
        '200': { $ref: '#/components/responses/SingleGifResponse' }
  /v2/emoji:
    get:
      tags: [Emoji]
      operationId: listEmoji
      summary: List Animated Emoji
      description: Return GIPHY's animated emoji library.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200': { $ref: '#/components/responses/GifListResponse' }
  /v2/emoji/{gif_id}/variations:
    get:
      tags: [Emoji]
      operationId: getEmojiVariations
      summary: Get Emoji Variations
      description: Return all variations of a single animated emoji.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: gif_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/GifListResponse' }
  /v1/clips/search:
    get:
      tags: [Clips]
      operationId: searchClips
      summary: Search Clips
      description: Search the GIPHY Clips library (GIFs with sound).
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: q
          in: query
          required: true
          schema: { type: string }
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Rating'
        - $ref: '#/components/parameters/Lang'
        - $ref: '#/components/parameters/CountryCode'
      responses:
        '200': { $ref: '#/components/responses/ClipListResponse' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /v1/clips/trending:
    get:
      tags: [Clips]
      operationId: getTrendingClips
      summary: Get Trending Clips
      description: Return the most popular Clips of the day.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Rating'
        - $ref: '#/components/parameters/CountryCode'
      responses:
        '200': { $ref: '#/components/responses/ClipListResponse' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /v1/animate:
    get:
      tags: [Animate]
      operationId: animateText
      summary: Animate Text
      description: Programmatically generate an animated text GIF from a phrase.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: m
          in: query
          required: true
          description: Text or phrase to animate.
          schema: { type: string }
        - name: style
          in: query
          required: false
          description: Optional animation style identifier.
          schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/SingleGifResponse' }
  /v1/channels/search:
    get:
      tags: [Channels]
      operationId: searchChannels
      summary: Search Channels
      description: Find GIPHY channels matching the supplied query.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: q
          in: query
          required: true
          schema: { type: string }
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated list of channels.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Channel' } }
                  pagination: { $ref: '#/components/schemas/Pagination' }
                  meta: { $ref: '#/components/schemas/Meta' }
  /v1/randomid:
    get:
      tags: [Utilities]
      operationId: createRandomId
      summary: Create Random ID
      description: Generate a unique, privacy-preserving identifier for tracking users in a session.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: A new random ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      random_id: { type: string }
                  meta: { $ref: '#/components/schemas/Meta' }
  /v1/gifs/search/actions:
    post:
      tags: [Analytics]
      operationId: registerSearchAction
      summary: Register Search Action
      description: |
        Register an action (view, click, share) on a GIF using the analytics pingback URLs
        included in search responses. Endpoint is fire-and-forget; HTTP 200 indicates the
        event was accepted.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action_type:
                  type: string
                  enum: [SEEN, CLICK, SENT]
                analytics_response_payload: { type: string }
                random_id: { type: string }
                ts: { type: integer, description: 'Epoch timestamp in milliseconds.' }
      responses:
        '200':
          description: Event accepted.
  /v1/gifs:
    get:
      tags: [GIFs]
      operationId: getGifsById
      summary: Get GIFs by ID
      description: Fetch metadata for up to 100 GIFs at once, by comma-separated IDs.
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: ids
          in: query
          required: true
          description: Comma-separated list of GIF IDs (max 100).
          schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/GifListResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
    post:
      tags: [Upload]
      operationId: uploadGif
      summary: Upload GIF
      description: |
        Upload a GIF or video file to GIPHY at `upload.giphy.com/v1/gifs`. Maximum file
        size is 100 MB. This operation runs against the `upload.giphy.com` host (overrides
        the default server).
      servers:
        - url: https://upload.giphy.com
      parameters:
        - $ref: '#/components/parameters/ApiKey'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [api_key]
              properties:
                api_key: { type: string }
                file: { type: string, format: binary, description: 'Image or video file (≤100 MB).' }
                source_image_url: { type: string, format: uri, description: 'Optionally provide a URL instead of uploading bytes.' }
                username: { type: string }
                tags: { type: string, description: 'Comma-separated tag list.' }
                source_post_url: { type: string, format: uri }
                is_hidden: { type: boolean }
      responses:
        '200':
          description: Upload accepted, returns the new GIF identifier.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id: { type: string }
                  meta: { $ref: '#/components/schemas/Meta' }
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key
      description: API key issued via the GIPHY developer dashboard.
  parameters:
    ApiKey:
      name: api_key
      in: query
      required: true
      description: GIPHY API key (Beta or Production).
      schema: { type: string }
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of items to return per page.
      schema: { type: integer, default: 25, maximum: 50 }
    Offset:
      name: offset
      in: query
      required: false
      description: Position in the result set for pagination.
      schema: { type: integer, default: 0 }
    Rating:
      name: rating
      in: query
      required: false
      description: Filter results by MPAA-style rating.
      schema:
        type: string
        enum: [g, pg, pg-13, r, y]
    Lang:
      name: lang
      in: query
      required: false
      description: Default language (ISO 639-1) for regional content.
      schema: { type: string }
    Bundle:
      name: bundle
      in: query
      required: false
      description: Reduce response payload by requesting only the rendition bundle you need.
      schema:
        type: string
        enum: [low_bandwidth, messaging_non_clips, sticker_layering, clips_grid_picker]
    RandomId:
      name: random_id
      in: query
      required: false
      description: Privacy-preserving user identifier produced by /v1/randomid.
      schema: { type: string }
    CountryCode:
      name: country_code
      in: query
      required: false
      description: ISO 3166-1 alpha-2 country code used to localize results.
      schema: { type: string }
    Weirdness:
      name: weirdness
      in: query
      required: false
      description: Translate weirdness (0 conservative ... 10 most weird).
      schema: { type: integer, minimum: 0, maximum: 10 }
  responses:
    GifListResponse:
      description: A paginated list of GIF or Sticker objects.
      content:
        application/json:
          schema:
            type: object
            properties:
              data: { type: array, items: { $ref: '#/components/schemas/Gif' } }
              pagination: { $ref: '#/components/schemas/Pagination' }
              meta: { $ref: '#/components/schemas/Meta' }
    SingleGifResponse:
      description: A single GIF or Sticker object.
      content:
        application/json:
          schema:
            type: object
            properties:
              data: { $ref: '#/components/schemas/Gif' }
              meta: { $ref: '#/components/schemas/Meta' }
    ClipListResponse:
      description: A paginated list of Clip objects (GIFs with sound).
      content:
        application/json:
          schema:
            type: object
            properties:
              data: { type: array, items: { $ref: '#/components/schemas/Clip' } }
              pagination: { $ref: '#/components/schemas/Pagination' }
              meta: { $ref: '#/components/schemas/Meta' }
    BadRequest:
      description: Malformed request.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Forbidden:
      description: Access is restricted; for Clips endpoints, request access via clips@giphy.com.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    RateLimited:
      description: API rate limit exceeded.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    Gif:
      type: object
      description: Standard GIPHY GIF object returned by most endpoints.
      properties:
        type: { type: string, enum: [gif, sticker, emoji], description: 'Type of media object.' }
        id: { type: string, description: 'GIPHY ID for the object.' }
        slug: { type: string, description: 'URL slug used in giphy.com URLs.' }
        url: { type: string, format: uri, description: 'Canonical GIPHY URL.' }
        bitly_gif_url: { type: string, format: uri }
        bitly_url: { type: string, format: uri }
        embed_url: { type: string, format: uri }
        username: { type: string }
        source: { type: string }
        rating: { type: string, enum: [g, pg, pg-13, r, y] }
        content_url: { type: string }
        user: { $ref: '#/components/schemas/User' }
        source_tld: { type: string }
        source_post_url: { type: string, format: uri }
        update_datetime: { type: string, format: date-time }
        create_datetime: { type: string, format: date-time }
        import_datetime: { type: string, format: date-time }
        trending_datetime: { type: string, format: date-time }
        images: { $ref: '#/components/schemas/Images' }
        title: { type: string }
        alt_text: { type: string }
        is_low_contrast: { type: boolean }
        analytics_response_payload: { type: string }
        analytics: { $ref: '#/components/schemas/Analytics' }
    Clip:
      allOf:
        - $ref: '#/components/schemas/Gif'
        - type: object
          properties:
            video:
              type: object
              description: Video metadata for Clip objects (GIFs with sound).
              properties:
                duration: { type: number }
                dimensions:
                  type: object
                  properties:
                    width: { type: integer }
                    height: { type: integer }
                assets:
                  type: object
                  additionalProperties:
                    type: object
                    properties:
                      url: { type: string, format: uri }
                      width: { type: integer }
                      height: { type: integer }
                captions:
                  type: array
                  items:
                    type: object
                    properties:
                      lang: { type: string }
                      srt: { type: string, format: uri }
                      vtt: { type: string, format: uri }
    User:
      type: object
      description: GIPHY user / channel associated with content.
      properties:
        avatar_url: { type: string, format: uri }
        banner_image: { type: string, format: uri }
        banner_url: { type: string, format: uri }
        profile_url: { type: string, format: uri }
        username: { type: string }
        display_name: { type: string }
        description: { type: string }
        instagram_url: { type: string, format: uri }
        website_url: { type: string, format: uri }
        is_verified: { type: boolean }
    Channel:
      type: object
      description: GIPHY content channel.
      properties:
        id: { type: integer }
        slug: { type: string }
        url: { type: string }
        display_name: { type: string }
        short_display_name: { type: string }
        description: { type: string }
        type:
          type: string
          enum: [community, editorial]
        content_type:
          type: string
          enum: [gif, sticker, mixed]
        banner_image: { type: string, format: uri }
        is_private: { type: boolean }
        user: { $ref: '#/components/schemas/User' }
        featured_gif: { $ref: '#/components/schemas/Gif' }
        ancestors:
          type: array
          items: { $ref: '#/components/schemas/Channel' }
        tags:
          type: array
          items:
            type: object
            properties:
              channel: { type: integer }
              rank: { type: integer }
              tag: { type: string }
    Category:
      type: object
      description: A GIF category.
      properties:
        name: { type: string }
        name_encoded: { type: string }
        subcategories:
          type: array
          items:
            type: object
            properties:
              name: { type: string }
              name_encoded: { type: string }
        gif: { $ref: '#/components/schemas/Gif' }
    Images:
      type: object
      description: Map of rendition keys to rendition metadata. Available renditions include fixed_height, fixed_height_still, fixed_height_downsampled, fixed_height_small, fixed_height_small_still, fixed_width, fixed_width_still, fixed_width_downsampled, fixed_width_small, fixed_width_small_still, downsized, downsized_still, downsized_large, downsized_medium, downsized_small, original, original_still, looping, preview, preview_gif.
      additionalProperties:
        $ref: '#/components/schemas/Rendition'
    Rendition:
      type: object
      properties:
        url: { type: string, format: uri }
        width: { type: string, description: 'Width in pixels (string in API).' }
        height: { type: string, description: 'Height in pixels (string in API).' }
        size: { type: string, description: 'File size in bytes (string in API).' }
        mp4: { type: string, format: uri }
        mp4_size: { type: string }
        webp: { type: string, format: uri }
        webp_size: { type: string }
        frames: { type: string }
        hash: { type: string }
    Pagination:
      type: object
      properties:
        offset: { type: integer }
        total_count: { type: integer }
        count: { type: integer }
    Meta:
      type: object
      properties:
        msg: { type: string }
        status: { type: integer }
        response_id: { type: string }
    Analytics:
      type: object
      description: Pingback URLs returned alongside each GIF for measuring user engagement.
      properties:
        onload:
          type: object
          properties:
            url: { type: string, format: uri }
        onclick:
          type: object
          properties:
            url: { type: string, format: uri }
        onsent:
          type: object
          properties:
            url: { type: string, format: uri }
    Error:
      type: object
      properties:
        meta: { $ref: '#/components/schemas/Meta' }