{
  "openapi": "3.1.0",
  "info": {
    "title": "Thumbn API",
    "version": "1.0.0",
    "summary": "Make YouTube, TikTok and Instagram Reels thumbnails from a video.",
    "description": "Give Thumbn a video link and it watches the video, writes thumbnail concepts and renders them at each platform's size. Runs are asynchronous: start one with `POST /jobs`, then poll `GET /jobs/{id}` until `status` is `complete` and read `thumbnails`. Authenticate with an API key on the `x-api-key` header (create one in Settings on thumbn.so). Requests act as the key's owner, on their plan, and spend their credits. AI assistants can use the MCP server at https://api.thumbn.so/mcp instead.",
    "termsOfService": "https://thumbn.so/terms",
    "contact": {
      "name": "Thumbn support",
      "url": "https://thumbn.so/support",
      "email": "contact@thumbn.so"
    }
  },
  "externalDocs": {
    "description": "Thumbn API and MCP documentation",
    "url": "https://thumbn.so/developers"
  },
  "servers": [
    {
      "url": "https://api.thumbn.so",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Jobs",
      "description": "Thumbnail runs."
    },
    {
      "name": "Media",
      "description": "The rendered images."
    },
    {
      "name": "Service",
      "description": "Service status."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "tags": [
          "Service"
        ],
        "summary": "Check the API is up",
        "description": "Returns `{ ok: true }` when the API is serving requests. Needs no authentication.",
        "security": [],
        "responses": {
          "200": {
            "description": "The API is up.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/jobs": {
      "post": {
        "operationId": "createThumbnailJob",
        "tags": [
          "Jobs"
        ],
        "summary": "Start a thumbnail run",
        "description": "Starts a run for a video link and returns its id straight away. The run spends credits from the key owner's account: one analysis charge and a charge per rendered image. The editable copy of a thumbnail with text or arrows is free. Poll `getThumbnailJob` for the result.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateJobRequest"
              },
              "example": {
                "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                "platforms": [
                  "youtube",
                  "reels"
                ],
                "imageModel": "nano-banana-pro",
                "variants": 2,
                "style": "mrbeast"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The run was accepted and queued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "status"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The job id."
                    },
                    "status": {
                      "type": "string",
                      "const": "queued"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request body is missing something or is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "No valid API key or session was sent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "The account has no active plan, or not enough credits for this run.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The plan does not include what was asked for.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "A provider key needed for the chosen model is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Slow down and try again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listThumbnailJobs",
        "tags": [
          "Jobs"
        ],
        "summary": "List thumbnail runs",
        "description": "Lists the account's runs, newest first, each with a cover image reference when one exists.",
        "responses": {
          "200": {
            "description": "The account's runs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "jobs"
                  ],
                  "properties": {
                    "jobs": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Job"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No valid API key or session was sent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{id}": {
      "get": {
        "operationId": "getThumbnailJob",
        "tags": [
          "Jobs"
        ],
        "summary": "Get a run and its thumbnails",
        "description": "Returns the run's status and, once it is `complete`, the thumbnails it produced. Fetch each image with `getThumbnailImage`. A `failed` run carries the reason in `error`, and any credits it was charged are refunded.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The job id returned when the run was started.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The run and its thumbnails so far.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "job",
                    "thumbnails"
                  ],
                  "properties": {
                    "job": {
                      "$ref": "#/components/schemas/Job"
                    },
                    "thumbnails": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Thumbnail"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No valid API key or session was sent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No run with that id belongs to this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{id}/retry": {
      "post": {
        "operationId": "retryThumbnailJob",
        "tags": [
          "Jobs"
        ],
        "summary": "Retry a failed run",
        "description": "Starts a failed run again with the same video and settings. Charged like a new run.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The job id returned when the run was started.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The run was restarted and queued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "status"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The job id."
                    },
                    "status": {
                      "type": "string",
                      "const": "queued"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No valid API key or session was sent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Not enough credits to run it again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No run with that id belongs to this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The run is not in a state that can be retried.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/media/thumbnails/{id}": {
      "get": {
        "operationId": "getThumbnailImage",
        "tags": [
          "Media"
        ],
        "summary": "Download a thumbnail image",
        "description": "Returns the image bytes for one thumbnail from `getThumbnailJob`. Add `?download` to receive it as a file attachment.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The thumbnail's `id`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "download",
            "in": "query",
            "required": false,
            "description": "Present (with any value) to get a `Content-Disposition: attachment` response.",
            "schema": {
              "type": "string"
            },
            "allowEmptyValue": true
          }
        ],
        "responses": {
          "200": {
            "description": "The image.",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "No valid API key or session was sent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No thumbnail with that id belongs to this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "A Thumbn API key, created in Settings on thumbn.so. Revoked and expired keys are rejected."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "What went wrong, in plain language."
          },
          "code": {
            "type": "string",
            "description": "A stable machine-readable code, when there is one."
          }
        },
        "additionalProperties": true
      },
      "CreateJobRequest": {
        "type": "object",
        "required": [
          "videoUrl"
        ],
        "properties": {
          "videoUrl": {
            "type": "string",
            "format": "uri",
            "description": "Link to a YouTube, TikTok or Instagram Reels video."
          },
          "platforms": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "youtube",
                "reels",
                "tiktok"
              ]
            },
            "minItems": 1,
            "description": "Which sizes to render: `youtube` is 16:9 (1280×720); `reels` and `tiktok` are 9:16 (1080×1920)."
          },
          "variants": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4,
            "description": "How many different concepts to make. Limited by the plan."
          },
          "imageModel": {
            "type": "string",
            "enum": [
              "nano-banana-pro",
              "gpt-image-2",
              "gpt-image-2.6-sunburst",
              "gpt-image-2.6-flare"
            ],
            "description": "The image model to render with."
          },
          "style": {
            "type": "string",
            "enum": [
              "mrbeast",
              "clickbait",
              "cinematic",
              "minimal",
              "aesthetic",
              "documentary"
            ],
            "description": "The visual style preset."
          },
          "title": {
            "type": "string",
            "maxLength": 300,
            "description": "The video's title. Fetched for YouTube links when omitted."
          },
          "notes": {
            "type": "string",
            "maxLength": 2000,
            "description": "What the thumbnail must show or avoid."
          },
          "referenceAssetIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Ids of images from the account's asset library to keep faithful (a face, a logo)."
          }
        }
      },
      "Job": {
        "type": "object",
        "required": [
          "id",
          "status",
          "platforms",
          "variants",
          "imageModel",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "ingesting",
              "analyzing",
              "generating",
              "complete",
              "failed"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why the run failed, or a note about a partial result."
          },
          "videoUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "platforms": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "youtube",
                "reels",
                "tiktok"
              ]
            }
          },
          "variants": {
            "type": "integer"
          },
          "imageModel": {
            "type": "string"
          },
          "style": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "completedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "additionalProperties": true
      },
      "Thumbnail": {
        "type": "object",
        "required": [
          "id",
          "jobId",
          "platform",
          "variantIndex"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Pass to `getThumbnailImage`."
          },
          "jobId": {
            "type": "string"
          },
          "platform": {
            "type": "string",
            "enum": [
              "youtube",
              "reels",
              "tiktok"
            ]
          },
          "variantIndex": {
            "type": "integer",
            "description": "Which concept this is, from 0."
          },
          "contentType": {
            "type": "string"
          },
          "conceptHeadline": {
            "type": [
              "string",
              "null"
            ],
            "description": "The overlay text of the concept, if it has one."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": true
      }
    }
  }
}