{
  "openapi": "3.1.0",
  "info": {
    "title": "PeakMV Ads API",
    "version": "1.0.0",
    "description": "Make photo and video ads (software and physical products) from an agent or script. Guide: https://peakmv.com/docs/agents . MCP server: https://peakmv.com/mcp . Ads cost real money; confirm price with the user first. You cannot add credits through the API (https://peakmv.com/credits)."
  },
  "servers": [
    {
      "url": "https://peakmv.com"
    }
  ],
  "paths": {
    "/api/ads/pricing": {
      "get": {
        "summary": "Prices, styles and limits",
        "description": "Public. Read live prices before quoting a user.",
        "operationId": "get_pricing",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": []
      }
    },
    "/api/ads/account": {
      "get": {
        "summary": "Credit balance and spend cap",
        "description": "Check before creating an ad.",
        "operationId": "get_account",
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit (100/min per key) or hourly/daily limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/ads/analyze-url": {
      "post": {
        "summary": "Read a software website and plan ads (free)",
        "description": "Reads the public home page (no login) and returns product facts, a suggested style, five ad angles and a stored share image. 12 per hour. Page text is treated as untrusted data.",
        "operationId": "post_analyze_url",
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit (100/min per key) or hourly/daily limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The site could not be read",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/ads/images": {
      "post": {
        "summary": "Store an image for an ad (free)",
        "description": "Send url (we fetch it, public http/https only) or dataBase64 + contentType. Returns the imageUrl to pass to generate. JPG, PNG, WebP, 2 KB to 10 MB. 60 per hour.",
        "operationId": "post_images",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "imageUrl": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit (100/min per key) or hourly/daily limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "400": {
            "description": "Bad input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Image could not be fetched",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "dataBase64": {
                    "type": "string"
                  },
                  "contentType": {
                    "type": "string",
                    "enum": [
                      "image/jpeg",
                      "image/png",
                      "image/webp"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/ads/hooks": {
      "post": {
        "summary": "Suggest opening hooks (free, optional)",
        "description": "20 per hour.",
        "operationId": "post_hooks",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "hooks": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit (100/min per key) or hourly/daily limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "productName",
                  "style"
                ],
                "properties": {
                  "productName": {
                    "type": "string"
                  },
                  "style": {
                    "$ref": "#/components/schemas/Style"
                  },
                  "description": {
                    "type": "string"
                  },
                  "imageUrls": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "category": {
                    "type": "string",
                    "enum": [
                      "software",
                      "product"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/ads/generate": {
      "post": {
        "summary": "Create an ad (CHARGES CREDITS)",
        "description": "Charges the price from /api/ads/pricing immediately; refunded automatically if generation fails. Returns 202 at once; poll GET /api/ads/{id}. The same requestKey is never charged twice and returns the existing ad with alreadyProcessed:true. API keys may start at most $100 of ads per 24 hours.",
        "operationId": "post_generate",
        "responses": {
          "202": {
            "description": "Accepted: generating (200 if already ready)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ad": {
                      "type": "object"
                    },
                    "creditBalance": {
                      "type": "number"
                    },
                    "alreadyProcessed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit (100/min per key) or hourly/daily limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "400": {
            "description": "Bad input; the message names the field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits; includes price, balance, shortfall, topUpUrl",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "This requestKey belongs to a failed, refunded ad; use a new key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GenerateRequest"
              }
            }
          }
        }
      }
    },
    "/api/ads/{id}": {
      "get": {
        "summary": "Ad status and result",
        "description": "Poll every 20 to 30 seconds. See summary for the short form.",
        "operationId": "get_id",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary": {
                      "$ref": "#/components/schemas/AdSummary"
                    },
                    "ad": {
                      "type": "object",
                      "description": "Full record"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit (100/min per key) or hourly/daily limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "PeakMV API key from https://peakmv.com/dashboard/api-keys"
      }
    },
    "schemas": {
      "Style": {
        "type": "string",
        "enum": [
          "hype",
          "ugc",
          "luxury",
          "meme",
          "clean",
          "unboxing"
        ],
        "description": "ugc = a person talks to camera (video only)"
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "GenerateRequest": {
        "type": "object",
        "required": [
          "productName",
          "style",
          "imageUrls"
        ],
        "properties": {
          "requestKey": {
            "type": "string",
            "description": "Idempotency key. Always send one and reuse it on retry."
          },
          "mode": {
            "type": "string",
            "enum": [
              "video",
              "photo"
            ],
            "default": "video"
          },
          "seconds": {
            "type": "integer",
            "enum": [
              6,
              12,
              18,
              30
            ],
            "description": "Required for video"
          },
          "aspectRatio": {
            "type": "string",
            "enum": [
              "9:16",
              "16:9",
              "1:1"
            ]
          },
          "style": {
            "$ref": "#/components/schemas/Style"
          },
          "category": {
            "type": "string",
            "enum": [
              "software",
              "product"
            ],
            "default": "software"
          },
          "productName": {
            "type": "string",
            "maxLength": 80
          },
          "description": {
            "type": "string",
            "maxLength": 500,
            "description": "The only facts the ad may claim"
          },
          "prompt": {
            "type": "string",
            "maxLength": 600,
            "description": "Creative direction"
          },
          "hook": {
            "type": "string",
            "maxLength": 120,
            "description": "Used word for word"
          },
          "imageUrls": {
            "type": "array",
            "minItems": 1,
            "maxItems": 5,
            "items": {
              "type": "string"
            },
            "description": "imageUrl values from /api/ads/images or analyze-url"
          }
        }
      },
      "AdSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "generating",
              "ready",
              "failed"
            ]
          },
          "stage": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "queued",
              "planning",
              "cast",
              "frames",
              "clips",
              "finishing",
              "done",
              null
            ]
          },
          "stageProgress": {
            "type": [
              "object",
              "null"
            ]
          },
          "videoUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "imageUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "imageOptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "headline": {
            "type": [
              "string",
              "null"
            ]
          },
          "caption": {
            "type": [
              "string",
              "null"
            ]
          },
          "hook": {
            "type": [
              "string",
              "null"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "page": {
            "type": "string"
          }
        }
      }
    }
  }
}