ShapelessAI Thumbnails API

openapi: 3.2.0
info:
  title: ShapelessAI Thumbnails API
  version: '1'
  description: 'The social media team an agent can call. Publish to LinkedIn, X, Instagram, TikTok, YouTube, Facebook, Threads, Bluesky, Reddit, Mastodon, Telegram, Discord and Pinterest, with each network''s limits checked first; make images, AI video, edits of your own footage, carousels, thumbnails, recorded product demos, speech and subtitles, one call each; or hand the whole goal to the agent team as a job. Every refusal says what to do next (a connect link, a checkout link, the question to ask). Bearer API key (Settings -> API keys) or the hosted MCP''s OAuth token. Read the docs live, not from memory: https://shapelessai.com/llms-full.txt is every docs and capability page in one fetch, prose at https://shapelessai.com/docs. What exists and what is planned: https://shapelessai.com/api/capabilities (an x-status: planned operation answers 501 with a want door).'
servers:
- url: https://shapelessai.com
tags:
- name: Thumbnails
paths:
  /api/thumbnails:
    post:
      summary: A frame of a video plus words (tool render_thumbnail). Schema on GET /api/tools
      operationId: postThumbnails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                video_key:
                  type: string
                  description: The finished video (mediaKey from edit_footage or videoKey from a video job (jobs_create)).
                frame_at:
                  type: number
                  description: Seconds into the video (or into frame_key) to take the face from.
                frame_key:
                  type: string
                  description: 'A clip to take the frame from instead, at its own resolution: the take behind the cut. frame_at then counts on it.'
                headline:
                  type: string
                  description: 'Three to five words, not the title. *Stars* mark the accent words: "I hired *an AI*".'
                picture_key:
                  type: string
                  description: 'One picture at most (an image media key): the product, the post, the number, the company''s mark or the face of the person the video is about.'
                accent:
                  type: string
                  description: Hex colour of the starred words. Defaults to the cut's accent.
                foreground:
                  type: string
                  description: Hex colour of the words. Default white.
                outline:
                  type: string
                  description: Hex colour of the contour and the scrim behind the words. Default near-black.
                budgetUsd:
                  type: number
                  description: The most this call may spend, in USD (default 2, max 10). Held while the tool runs, released after.
              required:
              - video_key
              - frame_at
              - headline
              x-tool: render_thumbnail
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResult'
        '400':
          description: The input does not match the tool's schema; the message names the field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No credential, or not valid.
        '402':
          description: Not enough credit to hold budgetUsd, or the call costs more than budgetUsd.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoCredit'
        '403':
          description: The key is missing the "write" scope.
        '404':
          description: No such tool on this deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The tool refused this input; nothing was charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Over the key's rate limit (600 requests an hour).
        '502':
          description: The tool failed; nothing was charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - apiKey:
        - write
      - oauth:
        - write
      x-scope: write
      x-status: live
      tags:
      - Thumbnails
components:
  schemas:
    ToolResult:
      type: object
      properties:
        tool:
          type: string
        output:
          description: The tool's own result; media it made is named by mediaKey.
        media:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              url:
                type: string
                format: uri
          description: Every media key the output names, with the URL that streams it (read scope). Put a key on a post's mediaKeys.
        chargedUsd:
          type: number
      required:
      - tool
      - output
      - media
      - chargedUsd
    Upgrade:
      type: object
      description: Links a person clicks to pay. Every 402 carries one.
      properties:
        pricing:
          type: string
          format: uri
        checkout:
          type: array
          items:
            type: object
            properties:
              tier:
                type: string
              name:
                type: string
              priceUsd:
                type: number
              monthlyCreditUsd:
                type: number
              url:
                type: string
                format: uri
            required:
            - tier
            - name
            - priceUsd
            - monthlyCreditUsd
            - url
      required:
      - pricing
      - checkout
    NoCredit:
      type: object
      description: 'Out of credit. Hand upgrade.pricing (or one checkout url) to the human: one click signs in and pays.'
      properties:
        error:
          type: string
        code:
          type: string
        upgrade:
          $ref: '#/components/schemas/Upgrade'
      required:
      - error
      - upgrade
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: slk_... key; scopes read, write, publish.
    oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://shapelessai.com/api/auth/mcp/authorize
          tokenUrl: https://shapelessai.com/api/auth/mcp/token
          scopes:
            read: Read anything the account holds.
            write: 'Create and edit: jobs, drafts, agents, Brand Memory.'
            publish: Anything that goes out to a platform, or spends.
            wiki: Write to the wiki at /vizipedia as this account, and nothing else. A key with `write` covers it.