{
  "openapi": "3.1.0",
  "info": {
    "version": "1.0.0",
    "title": "Hera.Video API",
    "description": "API for motion graphics video generation"
  },
  "servers": [
    {
      "url": "https://api.hera.video/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your API key for authenticating requests."
      }
    },
    "schemas": {
      "ExportConfig": {
        "type": "object",
        "properties": {
          "format": {
            "$ref": "#/components/schemas/ExternalExportFormatEnum"
          },
          "aspect_ratio": {
            "$ref": "#/components/schemas/ExternalExportAspectRatioEnum"
          },
          "fps": {
            "anyOf": [
              {
                "type": "string",
                "enum": ["24"]
              },
              {
                "type": "string",
                "enum": ["25"]
              },
              {
                "type": "string",
                "enum": ["30"]
              },
              {
                "type": "string",
                "enum": ["60"]
              }
            ],
            "description": "Frames per second for this export output."
          },
          "resolution": {
            "$ref": "#/components/schemas/ExternalExportResolutionEnum"
          }
        },
        "required": ["format", "aspect_ratio", "fps", "resolution"],
        "description": "Configuration for an export output. Defines the file format, aspect ratio, frame rate, and resolution."
      },
      "ExternalExportFormatEnum": {
        "type": "string",
        "enum": ["mp4", "prores", "webm", "gif"],
        "description": "Output format for this export (e.g. mp4, prores, webm, gif)."
      },
      "ExternalExportAspectRatioEnum": {
        "type": "string",
        "enum": ["16:9", "9:16", "1:1", "4:5"],
        "description": "Aspect ratio for this export (e.g. '16:9', '9:16', '1:1', '4:5')."
      },
      "ExternalExportResolutionEnum": {
        "type": "string",
        "enum": ["360p", "480p", "720p", "1080p", "4k"],
        "description": "Resolution for this export output (e.g. '1080p', '720p')."
      },
      "CreateVideoOutput": {
        "type": "object",
        "properties": {
          "video_id": {
            "type": "string",
            "description": "Unique ID of the job/video that was created."
          },
          "project_url": {
            "type": "string",
            "description": "Optional URL to view the project in the user interface."
          }
        },
        "required": ["video_id"],
        "description": "Response for a successfully queued video generation job."
      },
      "CreateVideoInput": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string",
            "description": "Text prompt describing the motion graphics/video to generate. Be specific about subject, style, motion, and colors for best results.",
            "example": "A spinning rainbow wheel."
          },
          "reference_image_url": {
            "type": "string",
            "description": "URL of a single reference image to guide visual style or content. Use reference_image_urls instead if you have multiple images."
          },
          "reference_image_urls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 5,
            "description": "Up to 5 reference image URLs to guide visual style or content. Preferred over reference_image_url when providing multiple images."
          },
          "reference_video_url": {
            "type": "string",
            "description": "Optional URL of a reference video."
          },
          "duration_seconds": {
            "type": "number",
            "description": "Duration (in seconds) for the generated video. Optional. Range: 1–120. If omitted, default or parent is used.",
            "maximum": 120,
            "example": 8
          },
          "style_id": {
            "type": "string",
            "description": "Optional ID of a style to use for styling the video."
          },
          "brand_kit_id": {
            "type": "string",
            "description": "[Deprecated] Optional ID of a style to use for styling the video. Use `style_id` instead.",
            "deprecated": true
          },
          "parent_video_id": {
            "type": "string",
            "description": "Video ID or template ID to use as a starting point for this generation. Useful for iterations on a previous result or starting from a template."
          },
          "assets": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": ["image", "video", "audio", "font", "csv"],
                  "description": "Asset type: image, video, audio, font, or csv."
                },
                "url": {
                  "type": "string",
                  "description": "URL of the asset file. Use the POST /files endpoint to upload local files and get a URL."
                }
              },
              "required": ["type", "url"]
            },
            "description": "Optional array of asset files to include in the video generation. Each asset has a type and a URL."
          },
          "outputs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExternalExportConfig"
            },
            "maxItems": 10,
            "description": "Array of output configurations (1–10). Each specifies format, aspect_ratio, fps, and resolution. A good default is one entry: { format: \"mp4\", aspect_ratio: \"16:9\", fps: \"30\", resolution: \"1080p\" }.",
            "example": [
              {
                "format": "mp4",
                "aspect_ratio": "16:9",
                "fps": "30",
                "resolution": "1080p"
              }
            ]
          },
          "sound_effects": {
            "type": "boolean",
            "default": false,
            "description": "[Beta] When true, generates sound effects for the video"
          }
        },
        "required": ["prompt", "outputs"],
        "description": "Request body to create a new motion graphics export job."
      },
      "ExternalExportConfig": {
        "type": "object",
        "properties": {
          "format": {
            "$ref": "#/components/schemas/ExternalExportFormatEnum"
          },
          "aspect_ratio": {
            "$ref": "#/components/schemas/ExternalExportAspectRatioEnum"
          },
          "fps": {
            "anyOf": [
              {
                "type": "string",
                "enum": ["24"]
              },
              {
                "type": "string",
                "enum": ["25"]
              },
              {
                "type": "string",
                "enum": ["30"]
              },
              {
                "type": "string",
                "enum": ["60"]
              }
            ],
            "description": "Frames per second for this export output."
          },
          "resolution": {
            "$ref": "#/components/schemas/ExternalExportResolutionEnum"
          }
        },
        "required": ["format", "aspect_ratio", "fps", "resolution"],
        "description": "Configuration for an export output. Defines the file format, aspect ratio, frame rate, and resolution."
      },
      "UploadFileOutput": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "Public URL of the uploaded file. Use this URL in POST /videos fields that accept a URL.",
            "example": "https://your-supabase-url.supabase.co/storage/v1/object/public/images/api-uploads/abc123.png"
          }
        },
        "required": ["url"],
        "description": "Response after successfully uploading a file."
      },
      "GetVideoResponse": {
        "type": "object",
        "properties": {
          "video_id": {
            "type": "string",
            "description": "Unique ID of this job/video.",
            "example": "vid_abcde12345"
          },
          "project_url": {
            "type": "string",
            "description": "Optional user interface URL for this project."
          },
          "status": {
            "$ref": "#/components/schemas/ExternalExportStatusEnum"
          },
          "outputs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExportStatusEntry"
            },
            "description": "Detailed export output statuses for each configuration requested."
          }
        },
        "required": ["video_id", "status", "outputs"],
        "description": "Complete status object and output info for a generated video job."
      },
      "ExternalExportStatusEnum": {
        "type": "string",
        "enum": ["in-progress", "success", "failed"],
        "description": "High-level status of the export job (in-progress, success, failed)."
      },
      "ExportStatusEntry": {
        "type": "object",
        "properties": {
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ExternalExportStatusEnum"
              },
              {
                "description": "Status of this export output (in-progress, success, or failed)."
              }
            ]
          },
          "file_url": {
            "type": "string",
            "nullable": true,
            "description": "URL to download or view the exported file if succeeded, or null if not applicable."
          },
          "config": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ExternalExportConfig"
              },
              {
                "description": "Configuration details for this export output."
              }
            ]
          },
          "error": {
            "type": "string",
            "description": "Error message (if status is 'failed')."
          }
        },
        "required": ["status", "config"],
        "description": "Status information for an individual export output."
      }
    },
    "parameters": {}
  },
  "paths": {
    "/videos": {
      "post": {
        "description": "Creates a new motion graphics generation job. Submit your prompt and desired output formats to queue a video for generation.",
        "summary": "Create a new motion graphics video generation job",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateVideoInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Job successfully queued. Returns a job/video ID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateVideoOutput"
                }
              }
            }
          }
        }
      }
    },
    "/files": {
      "post": {
        "description": "Upload a file (image, video, audio, font, or CSV) to be used when creating videos. The returned URL can be used in POST /videos.",
        "summary": "Upload a file",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The file to upload. Supported types: images (PNG, JPEG, GIF, SVG, WebP, BMP), videos (MP4, MPEG, WebM, MOV, AVI, FLV, MPG, WMV, 3GP), audio (MP3, WAV, AAC), fonts (TTF, OTF, EOT, WOFF, WOFF2), Lottie (JSON), and CSV. Max size: 10 MB."
                  }
                },
                "required": ["file"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "File uploaded successfully. Returns the public URL of the stored file.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadFileOutput"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — missing file, unsupported type, or file too large.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Unsupported file type: text/plain"
                    }
                  },
                  "required": ["error"]
                }
              }
            }
          }
        }
      }
    },
    "/videos/{video_id}": {
      "get": {
        "description": "Retrieve the export status, details, and output URLs for a generated video job using its ID.",
        "summary": "Get the status of a motion graphics video",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "The unique video/job ID returned when creating the job."
            },
            "required": true,
            "description": "The unique video/job ID returned when creating the job.",
            "name": "video_id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Full export status and list of outputs for the specified video/job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetVideoResponse"
                }
              }
            }
          },
          "404": {
            "description": "No video/job found with the specified ID.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Video/job not found"
                    }
                  },
                  "required": ["error"]
                }
              }
            }
          }
        }
      }
    }
  },
  "x-mcp": {
    "enabled": true
  }
}