> ## Documentation Index > Fetch the complete documentation index at: https://docs.magichour.ai/llms.txt > Use this file to discover all available pages before exploring further. # AI Face Editor API Reference - Magic Hour Docs > Edit facial features of an image using AI. Each edit costs 1 frame. The height/width of the output image depends on your subscription. Please refer to our [pricing](https://magichour.ai/pricing) page for more details ## OpenAPI ````yaml post /v1/ai-face-editor openapi: 3.0.2 info: title: Magic Hour API version: beta description: > Magic Hour provides an API (beta) that can be integrated into your own application to generate videos and images using AI. Webhook documentation can be found [here](https://magichour.ai/docs/webhook). If you have any questions, please reach out to us via [discord](https://discord.gg/JX5rgsZaJp). # Authentication Every request requires an API key. To get started, first generate your API key [here](https://magichour.ai/settings/developer). Then, add the `Authorization` header to the request. | Key | Value | |-|-| | Authorization | Bearer mhk_live_apikey | > **Warning**: any API call that renders a video will utilize credits in your account. termsOfService: https://magichour.ai/terms-of-service servers: - url: https://api.magichour.ai security: [] tags: - name: Files description: API related to uploading assets used for video generation - name: Image Projects description: API related to image projects - name: Video Projects description: API related to video projects - name: Audio Projects description: API related to audio projects paths: /v1/ai-face-editor: post: tags: - Image Projects summary: AI Face Editor description: >- Edit facial features of an image using AI. Each edit costs 1 frame. The height/width of the output image depends on your subscription. Please refer to our [pricing](https://magichour.ai/pricing) page for more details operationId: aiFaceEditor.editImage parameters: [] requestBody: required: true description: Body content: application/json: schema: type: object properties: name: type: string description: Give your image a custom name for easy identification. example: My Face Editor image default: Face Editor - dateTime assets: type: object properties: image_file_path: type: string minLength: 1 description: > This is the image whose face will be edited. This value is either - a direct URL to the video file - `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls). See the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details. example: api-assets/id/1234.png required: - image_file_path description: Provide the assets for face editor style: type: object properties: enhance_face: default: false type: boolean description: Enhance face features example: false eyebrow_direction: default: 0 type: number minimum: -100 maximum: 100 multipleOf: 5 description: Eyebrow direction (-100 to 100), in increments of 5 example: 0 eye_gaze_horizontal: default: 0 type: number minimum: -100 maximum: 100 multipleOf: 5 description: Horizontal eye gaze (-100 to 100), in increments of 5 example: 0 eye_gaze_vertical: default: 0 type: number minimum: -100 maximum: 100 multipleOf: 5 description: Vertical eye gaze (-100 to 100), in increments of 5 example: 0 eye_open_ratio: default: 0 type: number minimum: -100 maximum: 100 multipleOf: 5 description: Eye open ratio (-100 to 100), in increments of 5 example: 0 lip_open_ratio: default: 0 type: number minimum: -100 maximum: 100 multipleOf: 5 description: Lip open ratio (-100 to 100), in increments of 5 example: 0 head_roll: default: 0 type: number minimum: -100 maximum: 100 multipleOf: 5 description: Head roll (-100 to 100), in increments of 5 example: 0 mouth_grim: default: 0 type: number minimum: -100 maximum: 100 multipleOf: 5 description: Mouth grim (-100 to 100), in increments of 5 example: 0 mouth_pout: default: 0 type: number minimum: -100 maximum: 100 multipleOf: 5 description: Mouth pout (-100 to 100), in increments of 5 example: 0 mouth_purse: default: 0 type: number minimum: -100 maximum: 100 multipleOf: 5 description: Mouth purse (-100 to 100), in increments of 5 example: 0 mouth_smile: default: 0 type: number minimum: -100 maximum: 100 multipleOf: 5 description: Mouth smile (-100 to 100), in increments of 5 example: 0 mouth_position_horizontal: default: 0 type: number minimum: -100 maximum: 100 multipleOf: 5 description: >- Horizontal mouth position (-100 to 100), in increments of 5 example: 0 mouth_position_vertical: default: 0 type: number minimum: -100 maximum: 100 multipleOf: 5 description: >- Vertical mouth position (-100 to 100), in increments of 5 example: 0 head_pitch: default: 0 type: number minimum: -100 maximum: 100 multipleOf: 5 description: Head pitch (-100 to 100), in increments of 5 example: 0 head_yaw: default: 0 type: number minimum: -100 maximum: 100 multipleOf: 5 description: Head yaw (-100 to 100), in increments of 5 example: 0 description: Face editing parameters required: - assets - style responses: '200': description: Success content: application/json: schema: type: object properties: id: type: string example: cuid-example description: >- Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads. credits_charged: type: integer description: >- The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. If an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund. example: 1 required: - id - frame_cost - credits_charged description: Success '400': description: Invalid Request content: application/json: schema: type: object properties: message: type: string required: - message description: The request is invalid example: message: Missing request body '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string enum: - Unauthorized required: - message description: The request is not properly authenticated example: message: Unauthorized '402': description: Payment Required content: application/json: schema: type: object properties: message: type: string required: - message description: The request requires payment example: message: Payment required '404': description: Not Found content: application/json: schema: type: object properties: message: type: string enum: - Not Found required: - message description: Requested resource is not found example: message: Not Found '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string example: Unable to create image required: - message description: Unprocessable Entity security: - bearerAuth: [] x-codeSamples: - lang: python source: |- from magic_hour import Client from os import getenv client = Client(token=getenv("API_TOKEN")) res = client.v1.ai_face_editor.generate( assets={"image_file_path": "/path/to/1234.png"}, style={ "enhance_face": False, "eye_gaze_horizontal": 0.0, "eye_gaze_vertical": 0.0, "eye_open_ratio": 0.0, "eyebrow_direction": 0.0, "head_pitch": 0.0, "head_roll": 0.0, "head_yaw": 0.0, "lip_open_ratio": 0.0, "mouth_grim": 0.0, "mouth_position_horizontal": 0.0, "mouth_position_vertical": 0.0, "mouth_pout": 0.0, "mouth_purse": 0.0, "mouth_smile": 0.0, }, name="Face Editor image", wait_for_completion=True, download_outputs=True, download_directory="." ) - lang: javascript source: |- import { Client } from "magic-hour"; const client = new Client({ token: process.env["API_TOKEN"]!! }); const res = await client.v1.aiFaceEditor.generate( { assets: { imageFilePath: "/path/to/1234.png" }, name: "Face Editor image", style: { enhanceFace: false, eyeGazeHorizontal: 0.0, eyeGazeVertical: 0.0, eyeOpenRatio: 0.0, eyebrowDirection: 0.0, headPitch: 0.0, headRoll: 0.0, headYaw: 0.0, lipOpenRatio: 0.0, mouthGrim: 0.0, mouthPositionHorizontal: 0.0, mouthPositionVertical: 0.0, mouthPout: 0.0, mouthPurse: 0.0, mouthSmile: 0.0, }, }, { waitForCompletion: true, downloadOutputs: true, downloadDirectory: ".", }, ); - lang: go source: "package main\n\nimport (\n\tos \"os\"\n\n\tsdk \"github.com/magichourhq/magic-hour-go/client\"\n\tnullable \"github.com/magichourhq/magic-hour-go/nullable\"\n\tai_face_editor \"github.com/magichourhq/magic-hour-go/resources/v1/ai_face_editor\"\n\ttypes \"github.com/magichourhq/magic-hour-go/types\"\n)\n\nfunc main() {\n\tclient := sdk.NewClient(\n\t\tsdk.WithBearerAuth(os.Getenv(\"API_TOKEN\")),\n\t)\n\tres, err := client.V1.AiFaceEditor.Create(ai_face_editor.CreateRequest{\n\t\tAssets: types.V1AiFaceEditorCreateBodyAssets{\n\t\t\tImageFilePath: \"api-assets/id/1234.png\",\n\t\t},\n\t\tName: nullable.NewValue(\"My Face Editor image\"),\n\t\tStyle: types.V1AiFaceEditorCreateBodyStyle{\n\t\t\tEnhanceFace: nullable.NewValue(false),\n\t\t\tEyeGazeHorizontal: nullable.NewValue(0.0),\n\t\t\tEyeGazeVertical: nullable.NewValue(0.0),\n\t\t\tEyeOpenRatio: nullable.NewValue(0.0),\n\t\t\tEyebrowDirection: nullable.NewValue(0.0),\n\t\t\tHeadPitch: nullable.NewValue(0.0),\n\t\t\tHeadRoll: nullable.NewValue(0.0),\n\t\t\tHeadYaw: nullable.NewValue(0.0),\n\t\t\tLipOpenRatio: nullable.NewValue(0.0),\n\t\t\tMouthGrim: nullable.NewValue(0.0),\n\t\t\tMouthPositionHorizontal: nullable.NewValue(0.0),\n\t\t\tMouthPositionVertical: nullable.NewValue(0.0),\n\t\t\tMouthPout: nullable.NewValue(0.0),\n\t\t\tMouthPurse: nullable.NewValue(0.0),\n\t\t\tMouthSmile: nullable.NewValue(0.0),\n\t\t},\n\t})\n}" - lang: rust source: |- let client = magic_hour::Client::default() .with_bearer_auth(&std::env::var("API_TOKEN").unwrap()); let res = client .v1() .ai_face_editor() .create(magic_hour::resources::v1::ai_face_editor::CreateRequest { assets: magic_hour::models::V1AiFaceEditorCreateBodyAssets { image_file_path: "api-assets/id/1234.png".to_string(), }, name: Some("My Face Editor image".to_string()), style: magic_hour::models::V1AiFaceEditorCreateBodyStyle { enhance_face: Some(false), eye_gaze_horizontal: Some(0.0), eye_gaze_vertical: Some(0.0), eye_open_ratio: Some(0.0), eyebrow_direction: Some(0.0), head_pitch: Some(0.0), head_roll: Some(0.0), head_yaw: Some(0.0), lip_open_ratio: Some(0.0), mouth_grim: Some(0.0), mouth_position_horizontal: Some(0.0), mouth_position_vertical: Some(0.0), mouth_pout: Some(0.0), mouth_purse: Some(0.0), mouth_smile: Some(0.0), }, }) .await; - lang: curl source: |- curl --request POST \ --url https://api.magichour.ai/v1/ai-face-editor \ --header 'accept: application/json' \ --header 'authorization: Bearer ' \ --header 'content-type: application/json' \ --data ' { "name": "My Face Editor image", "assets": { "image_file_path": "api-assets/id/1234.png" }, "style": { "enhance_face": false, "eyebrow_direction": 0, "eye_gaze_horizontal": 0, "eye_gaze_vertical": 0, "eye_open_ratio": 0, "lip_open_ratio": 0, "head_roll": 0, "mouth_grim": 0, "mouth_pout": 0, "mouth_purse": 0, "mouth_smile": 0, "mouth_position_horizontal": 0, "mouth_position_vertical": 0, "head_pitch": 0, "head_yaw": 0 } } ' - lang: php source: |- "https://api.magichour.ai/v1/ai-face-editor", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => json_encode([ 'name' => 'My Face Editor image', 'assets' => [ 'image_file_path' => 'api-assets/id/1234.png' ], 'style' => [ 'enhance_face' => false, 'eyebrow_direction' => 0, 'eye_gaze_horizontal' => 0, 'eye_gaze_vertical' => 0, 'eye_open_ratio' => 0, 'lip_open_ratio' => 0, 'head_roll' => 0, 'mouth_grim' => 0, 'mouth_pout' => 0, 'mouth_purse' => 0, 'mouth_smile' => 0, 'mouth_position_horizontal' => 0, 'mouth_position_vertical' => 0, 'head_pitch' => 0, 'head_yaw' => 0 ] ]), CURLOPT_HTTPHEADER => [ "accept: application/json", "authorization: Bearer ", "content-type: application/json" ], ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } - lang: java source: >- HttpResponse response = Unirest.post("https://api.magichour.ai/v1/ai-face-editor") .header("accept", "application/json") .header("content-type", "application/json") .header("authorization", "Bearer ") .body("{\"name\":\"My Face Editor image\",\"assets\":{\"image_file_path\":\"api-assets/id/1234.png\"},\"style\":{\"enhance_face\":false,\"eyebrow_direction\":0,\"eye_gaze_horizontal\":0,\"eye_gaze_vertical\":0,\"eye_open_ratio\":0,\"lip_open_ratio\":0,\"head_roll\":0,\"mouth_grim\":0,\"mouth_pout\":0,\"mouth_purse\":0,\"mouth_smile\":0,\"mouth_position_horizontal\":0,\"mouth_position_vertical\":0,\"head_pitch\":0,\"head_yaw\":0}}") .asString(); components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer authentication header of the form `Bearer `, where `` is your API key. To get your API key, go to [Developer Hub](https://magichour.ai/developer?tab=api-keys) and click "Create new API Key". ````