{
  "openapi": "3.1.0",
  "info": {
    "title": "HalalGen Creative & Moderation API",
    "version": "1.0.0",
    "description": "Production REST API for HalalGen: the leading Shariah-compliant generative AI platform. Provides endpoints for text-to-image synthesis, cinematic text-to-video, on-device/edge background removal, and asset management governed by strict aniconic guardrails.",
    "contact": {
      "name": "HalalGen Developer Support",
      "email": "support@halalgen.ai",
      "url": "https://halalgen.ai/developer/docs"
    },
    "license": {
      "name": "Commercial Terms",
      "url": "https://halalgen.ai/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.halalgen.ai/v1",
      "description": "Production API Server (Global Edge)"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/generate": {
      "post": {
        "summary": "Generate Shariah-Compliant Image",
        "description": "Creates high-fidelity visual media adhering strictly to Islamic aniconic guidelines (zero living beings or faces) and modesty standards.",
        "operationId": "generateImage",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["prompt"],
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "Natural language prompt describing the desired inanimate scene, architecture, product, or design."
                  },
                  "model": {
                    "type": "string",
                    "enum": ["Flux20Pro", "GPTImage25Flare", "GPTImage25Sunburst", "Gemini35Flash", "StabilityUltra"],
                    "default": "Flux20Pro",
                    "description": "Target generative AI model."
                  },
                  "aspect_ratio": {
                    "type": "string",
                    "enum": ["1:1", "16:9", "9:16", "4:3", "3:2"],
                    "default": "1:1",
                    "description": "Canvas aspect ratio."
                  },
                  "negative_prompt": {
                    "type": "string",
                    "description": "Optional additional negative prompt attributes."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generation task successfully initiated or completed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "status": { "type": "string", "enum": ["queued", "processing", "completed", "failed"] },
                    "image_url": { "type": "string", "format": "uri" },
                    "seed": { "type": "integer" },
                    "created_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid prompt or policy moderation rejection." },
          "401": { "description": "Missing or invalid Bearer API key." }
        }
      }
    },
    "/video/generate": {
      "post": {
        "summary": "Generate Cinema Studio Video",
        "description": "Synthesizes cinematic ethical short video sequences using high-definition AI video models.",
        "operationId": "generateVideo",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["prompt"],
                "properties": {
                  "prompt": { "type": "string" },
                  "duration_seconds": { "type": "integer", "enum": [5, 10], "default": 5 },
                  "camera_motion": { "type": "string", "enum": ["pan_left", "pan_right", "zoom_in", "zoom_out", "orbit", "static"], "default": "static" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Video rendering initiated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "status": { "type": "string" },
                    "video_url": { "type": "string", "format": "uri" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/images/remove-background": {
      "post": {
        "summary": "Remove Background (Transparent Cutout)",
        "description": "Isolates primary subject and generates clean transparent PNG with sub-pixel edge detection.",
        "operationId": "removeBackground",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["image_url"],
                "properties": {
                  "image_url": { "type": "string", "format": "uri" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Isolated cutout generated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "cutout_url": { "type": "string", "format": "uri" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/images/upscale": {
      "post": {
        "summary": "Upscale Image to 4K",
        "description": "Enhances resolution and neural high-frequency details up to 3840x2160.",
        "operationId": "upscaleImage",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["image_url"],
                "properties": {
                  "image_url": { "type": "string", "format": "uri" },
                  "scale_factor": { "type": "integer", "enum": [2, 4], "default": 4 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upscaled image asset ready.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "upscaled_url": { "type": "string", "format": "uri" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/assets": {
      "get": {
        "summary": "List User Assets",
        "description": "Retrieves recent creations, resolution parameters, and storage metadata.",
        "operationId": "listAssets",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": {
          "200": {
            "description": "List of user assets.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "assets": { "type": "array", "items": { "type": "object" } },
                    "total": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key (sk-hg-...)"
      }
    }
  }
}