> ## 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 Image Editor > Edit images with AI. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/ai-image-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://docs.magichour.ai/webhook-reference). 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/developer?tab=api-keys&utm_source=docs&utm_medium=referral&utm_campaign=api-reference). 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 and reusing assets - 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 - name: Account description: API related to the account that owns the API key paths: /v1/ai-image-editor: post: tags: - Image Projects summary: AI Image Editor description: Edit images with AI. operationId: aiImageEditor.createImage 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 Ai Image Editor image default: Ai Image Editor - dateTime image_count: type: number enum: - 1 - 4 - 9 - 16 description: >- Number of images to generate. Maximum varies by model. Defaults to 1 if not specified. example: 1 default: 1 model: type: string enum: - default - nano-banana-2 - gpt-image-2 - gpt-image-2.5-flare - flux-2-klein - nano-banana-2-lite - qwen-edit - krea-2 - seedream-v4 - seedream-v4.5 - seedream-v5-pro - nano-banana - nano-banana-pro description: > The AI model to use for image editing. Each model has different capabilities and costs. **Models:** - `default` - Use the model we recommend, which will change over time. This is recommended unless you need a specific model. This is the default behavior. - `flux-2-klein` - from 5 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: free, creator, pro, business - Max additional input images: 5 - `gpt-image-2` - from 50 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `gpt-image-2.5-flare` - from 100 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `krea-2` - from 10 credits/image - Supported resolutions: 640px, 1k - Available for tiers: free, creator, pro, business - Max additional input images: 1 - `nano-banana` - from 50 credits/image - Supported resolutions: 640px, 1k - Available for tiers: creator, pro, business - Max additional input images: 9 - `nano-banana-2` - from 100 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `nano-banana-2-lite` - from 50 credits/image - Supported resolutions: 640px, 1k - Available for tiers: creator, pro, business - Max additional input images: 9 - `nano-banana-pro` - from 150 credits/image - Supported resolutions: 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `qwen-edit` - from 10 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: free, creator, pro, business - Max additional input images: 2 - `seedream-v4` - from 40 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `seedream-v4.5` - from 50 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Max additional input images: 9 - `seedream-v5-pro` - from 75 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: creator, pro, business - Max additional input images: 9 example: default aspect_ratio: type: string enum: - auto - '16:9' - '9:16' - '4:3' - '3:2' - '1:1' - '4:5' - '2:3' description: >- The aspect ratio of the output image(s). If not specified, defaults to `auto`. example: '1:1' resolution: type: string enum: - auto - 640px - 1k - 2k - 4k description: >- Maximum resolution (longest edge) for the output image. **Options:** - `640px` — up to 640px - `1k` — up to 1024px - `2k` — up to 2048px - `4k` — up to 4096px - `auto` — **Deprecated.** Mapped server-side from your subscription tier to the best matching resolution the model supports **Per-model support:** - `flux-2-klein` - 640px, 1k, 2k - `gpt-image-2` - 640px, 1k, 2k, 4k - `gpt-image-2.5-flare` - 640px, 1k, 2k, 4k - `krea-2` - 640px, 1k - `nano-banana` - 640px, 1k - `nano-banana-2` - 640px, 1k, 2k, 4k - `nano-banana-2-lite` - 640px, 1k - `nano-banana-pro` - 1k, 2k, 4k - `qwen-edit` - 640px, 1k, 2k - `seedream-v4` - 640px, 1k, 2k, 4k - `seedream-v4.5` - 640px, 1k, 2k, 4k - `seedream-v5-pro` - 640px, 1k, 2k Note: Resolution availability depends on the model and your subscription tier. example: 1k style: type: object properties: prompt: type: string minLength: 1 maxLength: 15000 description: The prompt used to edit the image. example: Give me sunglasses required: - prompt assets: type: object properties: image_file_paths: type: array items: type: string minLength: 1 maxItems: 10 description: > The image(s) used in the edit, maximum of 10 images. 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 - api-assets/id/1235.png description: Provide the assets for image edit required: - style - assets 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: 50 required: - id - credits_charged description: Success '400': description: Invalid Request content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - invalid_request description: >- Machine-readable error code. - `invalid_request`: Fix request syntax or validation errors before retrying. message: type: string description: Human-readable error message. '401': description: Unauthorized content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - unauthorized description: |- Machine-readable error code. - `unauthorized`: Provide a valid API key before retrying. message: type: string description: Human-readable error message. '402': description: Payment Required content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - insufficient_credits - subscription_required - plan_upgrade_required description: >- Machine-readable error code. - `insufficient_credits`: Purchase credits before retrying. - `subscription_required`: Start a subscription before retrying. - `plan_upgrade_required`: Upgrade the subscription plan before retrying. message: type: string description: Human-readable error message. '404': description: Not Found content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - not_found description: |- Machine-readable error code. - `not_found`: Check the route or resource identifier. message: type: string description: Human-readable error message. '422': description: Unprocessable Entity content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - unprocessable_entity description: >- Machine-readable error code. - `unprocessable_entity`: Change the request values before retrying. message: type: string description: Human-readable error message. '500': description: Internal Server Error content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - internal_server_error description: >- Machine-readable error code. - `internal_server_error`: Retry later or contact support if the error continues. message: type: string description: Human-readable error message. 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_image_editor.generate( assets={"image_file_path": "/path/to/1234.png"}, style={"prompt": "Give me sunglasses"}, name="Ai Image 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.aiImageEditor.generate( { assets: { imageFilePaths: ["/path/to/1234.png", "/path/to/1235.png"] }, name: "Ai Image Editor image", style: { prompt: "Give me sunglasses" }, }, { 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_image_editor \"github.com/magichourhq/magic-hour-go/resources/v1/ai_image_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.AiImageEditor.Create(ai_image_editor.CreateRequest{\n\t\tAspectRatio: nullable.NewValue(types.V1AiImageEditorCreateBodyAspectRatioEnum11),\n\t\tAssets: types.V1AiImageEditorCreateBodyAssets{\n\t\t\tImageFilePaths: nullable.NewValue([]string{\n\t\t\t\t\"api-assets/id/1234.png\",\n\t\t\t\t\"api-assets/id/1235.png\",\n\t\t\t}),\n\t\t},\n\t\tImageCount: nullable.NewValue(1.0),\n\t\tModel: nullable.NewValue(types.V1AiImageEditorCreateBodyModelEnumDefault),\n\t\tName: nullable.NewValue(\"My Ai Image Editor image\"),\n\t\tResolution: nullable.NewValue(types.V1AiImageEditorCreateBodyResolutionEnum1k),\n\t\tStyle: types.V1AiImageEditorCreateBodyStyle{\n\t\t\tPrompt: \"Give me sunglasses\",\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_image_editor() .create(magic_hour::resources::v1::ai_image_editor::CreateRequest { aspect_ratio: Some( magic_hour::models::V1AiImageEditorCreateBodyAspectRatioEnum::Enum11, ), assets: magic_hour::models::V1AiImageEditorCreateBodyAssets { image_file_paths: Some( vec![ "api-assets/id/1234.png".to_string(), "api-assets/id/1235.png" .to_string() ], ), ..Default::default() }, image_count: Some(1.0), model: Some(magic_hour::models::V1AiImageEditorCreateBodyModelEnum::Default), name: Some("My Ai Image Editor image".to_string()), resolution: Some( magic_hour::models::V1AiImageEditorCreateBodyResolutionEnum::Enum1k, ), style: magic_hour::models::V1AiImageEditorCreateBodyStyle { prompt: "Give me sunglasses".to_string(), ..Default::default() }, }) .await; - lang: curl source: |- curl --request POST \ --url https://api.magichour.ai/v1/ai-image-editor \ --header 'accept: application/json' \ --header 'authorization: Bearer ' \ --header 'content-type: application/json' \ --data ' { "name": "My Ai Image Editor image", "image_count": 1, "model": "default", "aspect_ratio": "1:1", "resolution": "1k", "style": { "prompt": "Give me sunglasses" }, "assets": { "image_file_paths": [ "api-assets/id/1234.png", "api-assets/id/1235.png" ] } } ' - lang: php source: |- "https://api.magichour.ai/v1/ai-image-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 Ai Image Editor image', 'image_count' => 1, 'model' => 'default', 'aspect_ratio' => '1:1', 'resolution' => '1k', 'style' => [ 'prompt' => 'Give me sunglasses' ], 'assets' => [ 'image_file_paths' => [ 'api-assets/id/1234.png', 'api-assets/id/1235.png' ] ] ]), 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-image-editor") .header("accept", "application/json") .header("content-type", "application/json") .header("authorization", "Bearer ") .body("{\"name\":\"My Ai Image Editor image\",\"image_count\":1,\"model\":\"default\",\"aspect_ratio\":\"1:1\",\"resolution\":\"1k\",\"style\":{\"prompt\":\"Give me sunglasses\"},\"assets\":{\"image_file_paths\":[\"api-assets/id/1234.png\",\"api-assets/id/1235.png\"]}}") .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&utm_source=docs&utm_medium=referral&utm_campaign=api-reference) and click "Create new API Key". ````