{
  "openapi": "3.0.1",
  "info": {
    "title": "Morfran API",
    "version": "1.0",
    "description": "AI face swap and ready-made AI photo effects for developers. Pay with credits (no subscription); get an API key at https://morfran.com. Send images as a public URL or base64; results come back as image URLs that are kept for 1 hour. Face swap fields are PascalCase, effect fields are snake_case.",
    "contact": {
      "name": "Morfran Technology Kft.",
      "url": "https://morfran.com/contact"
    },
    "termsOfService": "https://morfran.com/terms"
  },
  "servers": [
    {
      "url": "https://api.morfran.com"
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "tags": [
    {
      "name": "Face",
      "description": "Face swap, face beautify and face detection"
    },
    {
      "name": "Effects",
      "description": "Ready-made AI photo effects"
    }
  ],
  "paths": {
    "/v1/face-swap": {
      "post": {
        "parameters": [
          {
            "name": "async",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FaceSwapApiRequest"
              },
              "example": {
                "SourceImageUrl": "https://cdn.morfran.com/effects/covers/headshot.jpg",
                "TargetImageUrl": "https://cdn.morfran.com/effects/covers/1920s.jpg"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Content",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Face"
        ],
        "summary": "Swap one face onto a photo",
        "description": "5 credits. Puts the face from the source photo onto the largest face in the target photo. Images: URL or base64 (max 10 MB). Waits up to 60 s; add ?async=true for a task id. Results are kept for 1 hour."
      }
    },
    "/v1/face-swap/group": {
      "post": {
        "parameters": [
          {
            "name": "async",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FaceSwapGroupApiRequest"
              },
              "example": {
                "SourceImageUrl": "https://cdn.morfran.com/effects/covers/headshot.jpg",
                "TargetImageUrl": "https://cdn.morfran.com/effects/covers/1920s.jpg",
                "MaxFaces": 8,
                "MatchGender": false,
                "OneToAll": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Content",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Face"
        ],
        "summary": "Swap several faces in a group photo",
        "description": "10 credits. Faces are matched by position (optionally by gender), or one face onto all faces (OneToAll). Images: URL or base64 (max 10 MB). Waits up to 60 s; add ?async=true for a task id. Results are kept for 1 hour."
      }
    },
    "/v1/face-swap/multi-source": {
      "post": {
        "parameters": [
          {
            "name": "async",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FaceSwapMultiSourceApiRequest"
              },
              "example": {
                "Sources": [
                  {
                    "ImageUrl": "https://cdn.morfran.com/effects/covers/headshot.jpg"
                  },
                  {
                    "ImageUrl": "https://cdn.morfran.com/effects/covers/1920s.jpg"
                  }
                ],
                "TargetImageUrl": "https://cdn.morfran.com/effects/covers/1920s.jpg"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Content",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Face"
        ],
        "summary": "Swap faces from several source photos",
        "description": "10 credits. Source faces go onto the target faces from left to right. Images: URL or base64 (max 10 MB). Waits up to 60 s; add ?async=true for a task id. Results are kept for 1 hour."
      }
    },
    "/v1/face-swap/{taskId}": {
      "get": {
        "parameters": [
          {
            "name": "taskId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Content",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Face"
        ],
        "summary": "Get a face swap task status and result"
      }
    },
    "/v1/face-beautify": {
      "post": {
        "parameters": [
          {
            "name": "async",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FaceBeautifyApiRequest"
              },
              "example": {
                "ImageUrl": "https://cdn.morfran.com/effects/covers/headshot.jpg"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Face"
        ],
        "summary": "Make a face sharper and cleaner",
        "description": "5 credits. Images: URL or base64 (max 10 MB). Waits up to 60 s; add ?async=true for a task id. Results are kept for 1 hour."
      }
    },
    "/v1/face-beautify/group": {
      "post": {
        "parameters": [
          {
            "name": "async",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FaceBeautifyApiRequest"
              },
              "example": {
                "ImageUrl": "https://cdn.morfran.com/effects/covers/headshot.jpg",
                "MaxFaces": 8
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceSwapTaskResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Face"
        ],
        "summary": "Beautify up to 8 faces",
        "description": "10 credits. Images: URL or base64 (max 10 MB). Waits up to 60 s; add ?async=true for a task id. Results are kept for 1 hour."
      }
    },
    "/v1/face-detect": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FaceDetectApiRequest"
              },
              "example": {
                "ImageUrl": "https://cdn.morfran.com/effects/covers/headshot.jpg"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceDetectResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceDetectResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceDetectResponse"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Content",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FaceDetectResponse"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceDetectResponse"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FaceDetectResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Face"
        ],
        "summary": "Detect faces with age range and gender",
        "description": "1 credit. Images: URL or base64 (max 10 MB). Waits up to 60 s; add ?async=true for a task id. Results are kept for 1 hour."
      }
    },
    "/v1/effects": {
      "get": {
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "summary": "List AI photo effects (free)",
        "tags": [
          "Effects"
        ]
      }
    },
    "/v1/effects/{slug}": {
      "post": {
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "async",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApplyEffectRequest"
              },
              "example": {
                "image_url": "https://cdn.morfran.com/effects/covers/headshot.jpg",
                "quality": "standard"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "summary": "Apply an AI photo effect",
        "description": "11 credits (standard) or 29 credits (pro). List effects with GET /v1/effects. Images: URL or base64 (max 10 MB). Waits up to 60 s; add ?async=true for a task id. Results are kept for 1 hour.",
        "tags": [
          "Effects"
        ]
      }
    },
    "/v1/effects/tasks/{taskId}": {
      "get": {
        "parameters": [
          {
            "name": "taskId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "summary": "Get an async effect task status and result (free)",
        "tags": [
          "Effects"
        ]
      }
    },
    "/v1/effects/{slug}/pro": {
      "post": {
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "async",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApplyEffectRequest"
              },
              "example": {
                "image_url": "https://cdn.morfran.com/effects/covers/headshot.jpg"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "summary": "Apply an AI photo effect in Pro quality",
        "description": "29 credits. Images: URL or base64 (max 10 MB). Waits up to 60 s; add ?async=true for a task id. Results are kept for 1 hour.",
        "tags": [
          "Effects"
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Your Morfran API key (create it in the portal at https://morfran.com)."
      }
    },
    "schemas": {
      "DetectedFaceInfo": {
        "type": "object",
        "properties": {
          "Left": {
            "type": "number",
            "format": "float"
          },
          "Top": {
            "type": "number",
            "format": "float"
          },
          "Width": {
            "type": "number",
            "format": "float"
          },
          "Height": {
            "type": "number",
            "format": "float"
          },
          "AgeLow": {
            "type": "integer",
            "format": "int32"
          },
          "AgeHigh": {
            "type": "integer",
            "format": "int32"
          },
          "Gender": {
            "type": "string",
            "nullable": true
          },
          "GenderConfidence": {
            "type": "number",
            "format": "float"
          }
        },
        "additionalProperties": false
      },
      "FaceBeautifyApiRequest": {
        "type": "object",
        "properties": {
          "ImageUrl": {
            "type": "string",
            "nullable": true
          },
          "ImageBase64": {
            "type": "string",
            "nullable": true
          },
          "MaxFaces": {
            "type": "integer",
            "format": "int32"
          },
          "FaceSizeThreshold": {
            "type": "number",
            "format": "float",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "FaceDetectApiRequest": {
        "type": "object",
        "properties": {
          "ImageUrl": {
            "type": "string",
            "nullable": true
          },
          "ImageBase64": {
            "type": "string",
            "nullable": true
          },
          "FaceSizeThreshold": {
            "type": "number",
            "format": "float",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "FaceDetectResponse": {
        "type": "object",
        "properties": {
          "Success": {
            "type": "boolean"
          },
          "Message": {
            "type": "string",
            "nullable": true
          },
          "FaceCount": {
            "type": "integer",
            "format": "int32"
          },
          "Faces": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DetectedFaceInfo"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "FaceSwapApiRequest": {
        "type": "object",
        "properties": {
          "SourceImageUrl": {
            "type": "string",
            "nullable": true
          },
          "SourceImageBase64": {
            "type": "string",
            "nullable": true
          },
          "TargetImageUrl": {
            "type": "string",
            "nullable": true
          },
          "TargetImageBase64": {
            "type": "string",
            "nullable": true
          },
          "FaceSizeThreshold": {
            "type": "number",
            "format": "float",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "FaceSwapGroupApiRequest": {
        "type": "object",
        "properties": {
          "SourceImageUrl": {
            "type": "string",
            "nullable": true
          },
          "SourceImageBase64": {
            "type": "string",
            "nullable": true
          },
          "TargetImageUrl": {
            "type": "string",
            "nullable": true
          },
          "TargetImageBase64": {
            "type": "string",
            "nullable": true
          },
          "FaceSizeThreshold": {
            "type": "number",
            "format": "float",
            "nullable": true
          },
          "MaxFaces": {
            "type": "integer",
            "format": "int32"
          },
          "MatchGender": {
            "type": "boolean"
          },
          "OneToAll": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      },
      "FaceSwapMultiSourceApiRequest": {
        "type": "object",
        "properties": {
          "Sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ImageInput"
            },
            "nullable": true
          },
          "TargetImageUrl": {
            "type": "string",
            "nullable": true
          },
          "TargetImageBase64": {
            "type": "string",
            "nullable": true
          },
          "FaceSizeThreshold": {
            "type": "number",
            "format": "float",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "FaceSwapTaskResponse": {
        "type": "object",
        "properties": {
          "Success": {
            "type": "boolean"
          },
          "TaskId": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "string",
            "nullable": true
          },
          "Message": {
            "type": "string",
            "nullable": true
          },
          "ResultImageUrl": {
            "type": "string",
            "nullable": true
          },
          "FaceSwapCount": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ImageInput": {
        "type": "object",
        "properties": {
          "ImageUrl": {
            "type": "string",
            "nullable": true
          },
          "ImageBase64": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ApplyEffectRequest": {
        "type": "object",
        "required": [
          "image_url"
        ],
        "properties": {
          "image_url": {
            "type": "string",
            "description": "Public URL of the source photo (JPG, PNG or WebP)."
          },
          "quality": {
            "type": "string",
            "enum": [
              "standard",
              "pro"
            ],
            "default": "standard",
            "description": "standard = 11 credits, pro = 29 credits. Same as calling /pro."
          }
        }
      }
    }
  }
}