{
  "openapi": "3.1.0",
  "info": {
    "title": "KiwiWhale API",
    "version": "1.0.0",
    "description": "Agent-ready API for model generation, credit management, async job polling, and autonomous billing."
  },
  "servers": [
    {
      "url": "https://kiwiwhale.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "CreditsResponse": {
        "type": "object",
        "properties": {
          "credits": {
            "type": "number"
          },
          "account_type": {
            "type": "string"
          }
        }
      },
      "ModelsResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "count": {
            "type": "integer"
          },
          "models": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "product_id": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "public_model": {
                  "type": "string"
                },
                "category": {
                  "type": "string"
                },
                "cost_credits": {
                  "type": "number"
                },
                "description": {
                  "type": "string"
                },
                "schema": {}
              }
            }
          }
        }
      },
      "GenerateRequest": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "public_model": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "image_url": {
            "type": "string"
          },
          "video_url": {
            "type": "string"
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "size": {
            "type": "string"
          },
          "seed": {
            "type": "integer"
          },
          "output_format": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "GenerateResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "job_id": {
            "type": "string"
          }
        }
      },
      "JobResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "outputs": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string"
                },
                "mime": {
                  "type": "string"
                }
              }
            }
          },
          "seed": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      },
      "AgentRegisterRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          }
        }
      },
      "AgentRegisterResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "account_type": {
            "type": "string"
          },
          "user_id": {
            "type": "integer"
          },
          "api_key": {
            "type": "string"
          },
          "credits": {
            "type": "number"
          }
        }
      },
      "AgentTopupRequest": {
        "type": "object",
        "properties": {
          "credits": {
            "type": "number"
          }
        },
        "required": [
          "credits"
        ]
      },
      "AgentTopupResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "payment_intent_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "net_credits_bought": {
            "type": "number"
          },
          "gross_usd_charged": {
            "type": "number"
          }
        }
      },
      "AgentSetupPaymentResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "client_secret": {
            "type": "string"
          },
          "publishable_key": {
            "type": "string"
          }
        }
      },
      "AgentConfirmPaymentMethodRequest": {
        "type": "object",
        "properties": {
          "payment_method_id": {
            "type": "string"
          },
          "auto_topup_enabled": {
            "type": "boolean"
          },
          "auto_topup_mode": {
            "type": "string",
            "enum": [
              "fixed",
              "buffer"
            ]
          },
          "auto_topup_trigger_credits": {
            "type": "number"
          },
          "auto_topup_amount_credits": {
            "type": "number"
          },
          "auto_topup_target_buffer_credits": {
            "type": "number"
          },
          "auto_topup_max_per_charge_usd": {
            "type": "number"
          },
          "auto_topup_daily_cap_usd": {
            "type": "number"
          }
        },
        "required": [
          "payment_method_id"
        ]
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/agent_register.php": {
      "post": {
        "summary": "Create an agent account",
        "security": [],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentRegisterRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent registered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentRegisterResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/credits.php": {
      "get": {
        "summary": "Get current credits for authenticated account",
        "responses": {
          "200": {
            "description": "Credits returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/models.php": {
      "get": {
        "summary": "List active KiwiWhale public models",
        "security": [],
        "responses": {
          "200": {
            "description": "Active public models returned without internal provider routing details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/generate.php": {
      "post": {
        "summary": "Submit a generation request",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GenerateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Job accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerateResponse"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs.php": {
      "get": {
        "summary": "Poll job status",
        "parameters": [
          {
            "name": "job_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Job status returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agent_setup_payment.php": {
      "post": {
        "summary": "Create Stripe setup intent for autonomous payment method",
        "responses": {
          "200": {
            "description": "Setup intent created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentSetupPaymentResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agent_confirm_payment_method.php": {
      "post": {
        "summary": "Attach saved payment method and enable autonomous top-up settings",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentConfirmPaymentMethodRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment method saved"
          }
        }
      }
    },
    "/api/v1/agent_topup.php": {
      "post": {
        "summary": "Trigger autonomous top-up using saved payment method",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentTopupRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Top-up charged",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentTopupResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}