> ## 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 Generator API Reference - Magic Hour Docs > Create an AI image with advanced model selection and quality controls. ## OpenAPI ````yaml post /v1/ai-image-generator 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-image-generator: post: tags: - Image Projects summary: AI Image Generator description: Create an AI image with advanced model selection and quality controls. operationId: aiImageGenerator.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 image default: Ai Image - dateTime image_count: type: integer minimum: 1 maximum: 16 description: Number of images to generate. Maximum varies by model. example: 1 model: type: string enum: - default - flux-schnell - z-image-turbo - seedream-v4 - nano-banana - nano-banana-2 - nano-banana-pro - gpt-image-2 - seedream description: > The AI model to use for image generation. 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-schnell` - from 5 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: free, creator, pro, business - Image count allowed: 1, 2, 3, 4 - `z-image-turbo` - from 5 credits/image - Supported resolutions: 640px, 1k, 2k - Available for tiers: free, creator, pro, business - Image count allowed: 1, 2, 3, 4 - `seedream-v4` - from 40 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: free, creator, pro, business - Image count allowed: 1, 2, 3, 4 - `nano-banana` - from 50 credits/image - Supported resolutions: 640px, 1k - Available for tiers: free, creator, pro, business - Image count allowed: 1, 2, 3, 4 - `nano-banana-2` - from 100 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: free, creator, pro, business - Image count allowed: 1, 4, 9, 16 - `nano-banana-pro` - from 150 credits/image - Supported resolutions: 1k, 2k, 4k - Available for tiers: creator, pro, business - Image count allowed: 1, 4, 9, 16 - `gpt-image-2` - from 50 credits/image - Supported resolutions: 640px, 1k, 2k, 4k - Available for tiers: creator, pro, business - Image count allowed: 1, 2, 3, 4 **Deprecated Enum Values:** - `seedream` - Use `seedream-v4` instead. example: default aspect_ratio: type: string enum: - '1:1' - '16:9' - '9:16' description: >- The aspect ratio of the output image(s). If not specified, defaults to `1:1` (square). example: '1:1' resolution: default: auto 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-schnell` - 640px, 1k, 2k - `z-image-turbo` - 640px, 1k, 2k - `seedream-v4` - 640px, 1k, 2k, 4k - `nano-banana` - 640px, 1k - `nano-banana-2` - 640px, 1k, 2k, 4k - `nano-banana-pro` - 1k, 2k, 4k - `gpt-image-2` - 640px, 1k, 2k, 4k Note: Resolution availability depends on the model and your subscription tier. example: auto style: type: object properties: prompt: type: string minLength: 1 description: The prompt used for the image(s). example: Cool image tool: default: general type: string enum: - ai-anime-generator - ai-art-generator - ai-background-generator - ai-character-generator - ai-face-generator - ai-fashion-generator - ai-icon-generator - ai-illustration-generator - ai-interior-design-generator - ai-landscape-generator - ai-logo-generator - ai-manga-generator - ai-outfit-generator - ai-pattern-generator - ai-photo-generator - ai-sketch-generator - ai-tattoo-generator - album-cover-generator - animated-characters-generator - architecture-generator - book-cover-generator - comic-book-generator - dark-fantasy-ai - disney-ai-generator - dnd-ai-art-generator - emoji-generator - fantasy-map-generator - graffiti-generator - movie-poster-generator - optical-illusion-generator - pokemon-generator - south-park-character-generator - superhero-generator - thumbnail-maker - general description: >- The art style to use for image generation. Defaults to 'general' if not provided. example: ai-anime-generator required: - prompt description: The art style to use for image generation. required: - image_count - 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 example: 5 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. 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_image_generator.generate( image_count=1, style={ "prompt": "Cool image", "tool": "ai-anime-generator", }, aspect_ratio="1:1", model="default", name="My Ai Image image", resolution="auto", 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.aiImageGenerator.generate( { aspectRatio: "1:1", imageCount: 1, model: "default", name: "My Ai Image image", resolution: "auto", style: { prompt: "Cool image", tool: "ai-anime-generator" }, }, { 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_generator \"github.com/magichourhq/magic-hour-go/resources/v1/ai_image_generator\"\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.AiImageGenerator.Create(ai_image_generator.CreateRequest{\n\t\tAspectRatio: nullable.NewValue(types.V1AiImageGeneratorCreateBodyAspectRatioEnum11),\n\t\tImageCount: 1,\n\t\tModel: nullable.NewValue(types.V1AiImageGeneratorCreateBodyModelEnumDefault),\n\t\tName: nullable.NewValue(\"My Ai Image image\"),\n\t\tResolution: nullable.NewValue(types.V1AiImageGeneratorCreateBodyResolutionEnumAuto),\n\t\tStyle: types.V1AiImageGeneratorCreateBodyStyle{\n\t\t\tPrompt: \"Cool image\",\n\t\t\tTool: nullable.NewValue(types.V1AiImageGeneratorCreateBodyStyleToolEnumAiAnimeGenerator),\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_generator() .create(magic_hour::resources::v1::ai_image_generator::CreateRequest { aspect_ratio: Some( magic_hour::models::V1AiImageGeneratorCreateBodyAspectRatioEnum::Enum11, ), image_count: 1, model: Some( magic_hour::models::V1AiImageGeneratorCreateBodyModelEnum::Default, ), name: Some("My Ai Image image".to_string()), resolution: Some( magic_hour::models::V1AiImageGeneratorCreateBodyResolutionEnum::Auto, ), style: magic_hour::models::V1AiImageGeneratorCreateBodyStyle { prompt: "Cool image".to_string(), tool: Some( magic_hour::models::V1AiImageGeneratorCreateBodyStyleToolEnum::AiAnimeGenerator, ), ..Default::default() }, ..Default::default() }) .await; - lang: curl source: |- curl --request POST \ --url https://api.magichour.ai/v1/ai-image-generator \ --header 'accept: application/json' \ --header 'authorization: Bearer ' \ --header 'content-type: application/json' \ --data ' { "name": "My Ai Image image", "image_count": 1, "model": "default", "aspect_ratio": "1:1", "resolution": "auto", "style": { "prompt": "Cool image", "tool": "ai-anime-generator" } } ' - lang: php source: |- "https://api.magichour.ai/v1/ai-image-generator", 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 image', 'image_count' => 1, 'model' => 'default', 'aspect_ratio' => '1:1', 'resolution' => 'auto', 'style' => [ 'prompt' => 'Cool image', 'tool' => 'ai-anime-generator' ] ]), 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-generator") .header("accept", "application/json") .header("content-type", "application/json") .header("authorization", "Bearer ") .body("{\"name\":\"My Ai Image image\",\"image_count\":1,\"model\":\"default\",\"aspect_ratio\":\"1:1\",\"resolution\":\"auto\",\"style\":{\"prompt\":\"Cool image\",\"tool\":\"ai-anime-generator\"}}") .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". ````