api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "author": {
          "description": "Author when found.",
          "nullable": true,
          "properties": {
            "avatarUrl": {
              "description": "Profile picture URL.",
              "nullable": true,
              "type": "string"
            },
            "handle": {
              "description": "Public username without a leading @.",
              "minLength": 1,
              "type": "string"
            },
            "nickname": {
              "description": "Display name.",
              "nullable": true,
              "type": "string"
            },
            "platformUserId": {
              "description": "Numeric user id.",
              "type": "string"
            },
            "privateAccount": {
              "description": "Whether the account is private.",
              "type": "boolean"
            },
            "region": {
              "description": "Two-letter country code when available.",
              "nullable": true,
              "type": "string"
            },
            "secUid": {
              "description": "Stable opaque user id.",
              "type": "string"
            },
            "signature": {
              "description": "Profile bio text.",
              "nullable": true,
              "type": "string"
            },
            "verified": {
              "description": "Whether the account is verified.",
              "type": "boolean"
            }
          },
          "required": [
            "handle",
            "verified"
          ],
          "type": "object"
        },
        "details": {
          "additionalProperties": {
            "nullable": true
          },
          "description": "Additional TikTok-native fields from the post (author, music, video, etc.), minus keys already promoted above.",
          "properties": {},
          "type": "object"
        },
        "downloads": {
          "description": "Populated only when `downloadMedia=true` was passed and media was available.",
          "items": {
            "description": "A hosted media asset.",
            "properties": {
              "cdnUrl": {
                "description": "Permanent hosted URL.",
                "type": "string"
              },
              "originalUrl": {
                "description": "Source media URL.",
                "type": "string"
              },
              "postId": {
                "description": "Video id from the post.",
                "type": "string"
              },
              "type": {
                "description": "Asset type.",
                "enum": [
                  "video",
                  "image"
                ],
                "type": "string"
              }
            },
            "required": [
              "originalUrl",
              "cdnUrl",
              "type"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "lookupStatus": {
          "description": "Whether the video was resolved.",
          "enum": [
            "found",
            "not_found"
          ],
          "type": "string"
        },
        "media": {
          "description": "Primary playable media payload for the video.",
          "nullable": true,
          "properties": {
            "dimensions": {
              "description": "Pixel dimensions.",
              "properties": {
                "height": {
                  "minimum": 0,
                  "type": "integer"
                },
                "width": {
                  "minimum": 0,
                  "type": "integer"
                }
              },
              "required": [
                "width",
                "height"
              ],
              "type": "object"
            },
            "downloadUrl": {
              "description": "Best available video URL (typically watermarked).",
              "nullable": true,
              "type": "string"
            },
            "downloadWithoutWatermarkUrl": {
              "description": "Best available video URL without watermark.",
              "nullable": true,
              "type": "string"
            },
            "slideshowImages": {
              "description": "Ordered image URLs when the post is a photo slideshow.",
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "thumbnailUrl": {
              "description": "Thumbnail or cover image URL.",
              "nullable": true,
              "type": "string"
            }
          },
          "required": [
            "downloadUrl",
            "downloadWithoutWatermarkUrl",
            "thumbnailUrl"
          ],
          "type": "object"
        },
        "metrics": {
          "description": "Engagement metrics for the video.",
          "nullable": true,
          "properties": {
            "comments": {
              "description": "Comment count.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "likes": {
              "description": "Like count.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "saves": {
              "description": "Save or collection count.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "shares": {
              "description": "Share count.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "views": {
              "description": "Play count.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            }
          },
          "type": "object"
        },
        "music": {
          "description": "Music or sound when found.",
          "nullable": true,
          "properties": {
            "author": {
              "description": "Music author.",
              "nullable": true,
              "type": "string"
            },
            "coverUrl": {
              "description": "Music cover image URL.",
              "nullable": true,
              "type": "string"
            },
            "durationSec": {
              "description": "Music duration in seconds.",
              "minimum": 0,
              "nullable": true,
              "type": "number"
            },
            "id": {
              "description": "Music or sound id.",
              "nullable": true,
              "type": "string"
            },
            "isOriginal": {
              "description": "Whether the sound is marked as original.",
              "type": "boolean"
            },
            "playUrl": {
              "description": "Music playable URL.",
              "nullable": true,
              "type": "string"
            },
            "title": {
              "description": "Music title.",
              "nullable": true,
              "type": "string"
            }
          },
          "type": "object"
        },
        "transcript": {
          "description": "Populated only when `getTranscript=true` was passed and a transcript was available.",
          "nullable": true,
          "properties": {
            "content": {
              "description": "Raw transcript text.",
              "type": "string"
            },
            "format": {
              "description": "Transcript format.",
              "enum": [
                "webvtt"
              ],
              "type": "string"
            }
          },
          "required": [
            "format",
            "content"
          ],
          "type": "object"
        },
        "video": {
          "description": "Video details when found.",
          "nullable": true,
          "properties": {
            "caption": {
              "description": "Caption text.",
              "nullable": true,
              "type": "string"
            },
            "createdAt": {
              "description": "ISO-8601 timestamp when the video was posted.",
              "nullable": true,
              "type": "string"
            },
            "durationMs": {
              "description": "Video duration in milliseconds.",
              "minimum": 0,
              "nullable": true,
              "type": "integer"
            },
            "id": {
              "description": "TikTok video id.",
              "minLength": 1,
              "type": "string"
            },
            "isAd": {
              "description": "Whether TikTok marks the post as an ad.",
              "type": "boolean"
            },
            "mediaType": {
              "description": "Whether the post is a video or a photo slideshow.",
              "enum": [
                "video",
                "slideshow"
              ],
              "type": "string"
            },
            "region": {
              "description": "Video region (two-letter country code).",
              "nullable": true,
              "type": "string"
            },
            "url": {
              "description": "Canonical public TikTok URL for this video.",
              "minLength": 1,
              "type": "string"
            }
          },
          "required": [
            "id",
            "url",
            "caption",
            "createdAt",
            "durationMs",
            "mediaType",
            "isAd"
          ],
          "type": "object"
        }
      },
      "required": [
        "lookupStatus",
        "video",
        "author",
        "music",
        "metrics",
        "media",
        "transcript",
        "downloads"
      ],
      "type": "object"
    },
    "meta": {
      "description": "Metadata describing the request and billing outcome.",
      "properties": {
        "cached": {
          "description": "True when served from shared response cache. Credits still apply (full endpoint price); Age header may be present.",
          "type": "boolean"
        },
        "creditsCharged": {
          "description": "Credits charged for this request.",
          "minimum": 0,
          "type": "integer"
        },
        "requestId": {
          "description": "Unique request identifier for tracing this API call.",
          "minLength": 1,
          "type": "string"
        },
        "version": {
          "description": "Public API version that served the response.",
          "enum": [
            "v1"
          ],
          "type": "string"
        }
      },
      "required": [
        "requestId",
        "creditsCharged",
        "version"
      ],
      "type": "object"
    }
  },
  "required": [
    "data",
    "meta"
  ],
  "type": "object"
}