> ## 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. # Animation API Reference - Magic Hour Docs > Create a Animation video. The estimated frame cost is calculated based on the `fps` and `end_seconds` input. ## OpenAPI ````yaml post /v1/animation 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/animation: post: tags: - Video Projects summary: Animation description: >- Create a Animation video. The estimated frame cost is calculated based on the `fps` and `end_seconds` input. operationId: animation.createVideo parameters: [] requestBody: required: true description: Body content: application/json: schema: type: object properties: name: type: string description: Give your video a custom name for easy identification. example: My Animation video default: Animation - dateTime fps: type: number minimum: 1 description: The desire output video frame rate example: 12 end_seconds: type: number minimum: 0.1 description: This value determines the duration of the output video. format: float example: 15 height: type: integer minimum: 64 description: >- The height of the final output video. The maximum height depends on your subscription. Please refer to our [pricing page](https://magichour.ai/pricing) for more details example: 960 width: type: integer minimum: 64 description: >- The width of the final output video. The maximum width depends on your subscription. Please refer to our [pricing page](https://magichour.ai/pricing) for more details example: 512 style: type: object properties: art_style: type: string enum: - Custom - Painterly Illustration - Vibrant Matte Illustration - Traditional Watercolor - Cyberpunk - Ink and Watercolor Portrait - Intricate Abstract Lines Portrait - 3D Render - Old School Comic - Bold Colored Illustration - Synthwave - Minimal Cold Futurism - Futuristic Anime - Cinematic Miyazaki - Studio Ghibli Film Still - Soft Delicate Matte Portrait - Cinematic Landscape - Landscape Painting - Photograph - Jackson Pollock - Cubist - Abstract Minimalist - Impressionism - Van Gogh - Woodcut - Oil Painting - Vintage Japanese Anime - Pixar - Cosmic - Pixel Art - Fantasy - Arcane - Sin City - Double Exposure - Painted Cityscape - 90s Streets - Overgrown - Postapocalyptic - Spooky - Miniatures - Low Poly - Art Deco - Inkpunk - Dark Graphic Illustration - Dark Watercolor - Faded Illustration - Directed by AI description: The art style used to create the output video example: Painterly Illustration art_style_custom: type: string description: >- Describe custom art style. This field is required if `art_style` is `Custom` camera_effect: type: string enum: - Simple Zoom Out - Simple Zoom In - Bounce Out - Spin Bounce - Rolling Bounces - Rise and Climb - Dramatic Zoom In - Dramatic Zoom Out - Sway Out - Boost Zoom In - Boost Zoom Out - Heartbeat - Bounce in Place - Earthquake Bounce - Slice Bounce - Bounce In And Out - Jump - Road Trip - Traverse - Rubber Band - Rodeo - Accelerate - Speed of Light - Drift Spin - Vertigo - Cog in the Machine - Quadrant - Tron - Pusher - Roll In - Hesitate In - Zoom In - Audio Sync - Pulse - Audio Sync - Aggressive Zoom In - Audio Sync - Roll In - Audio Sync - Zoom Out - Audio Sync - Aggressive Zoom Out - Audio Sync - Sway Out - Audio Sync - Bounce and Spin - Audio Sync - Zoom In and Spin - Audio Sync - Vertigo - Audio Sync - Bounce Out - Audio Sync - Earthquake Bounce - Audio Sync - Pusher - Audio Sync - Evolve - Audio Sync - Devolve - Audio Sync - Slideshow - Pan Left - Pan Right - Tilt Up - Tilt Down - Directed by AI description: The camera effect used to create the output video example: Simple Zoom In prompt_type: type: string enum: - custom - use_lyrics - ai_choose example: custom description: >- * `custom` - Use your own prompt for the video. * `use_lyrics` - Use the lyrics of the audio to create the prompt. If this option is selected, then `assets.audio_source` must be `file` or `youtube`. * `ai_choose` - Let AI write the prompt. If this option is selected, then `assets.audio_source` must be `file` or `youtube`. prompt: type: string description: >- The prompt used for the video. Prompt is required if `prompt_type` is `custom`. Otherwise this value is ignored example: Cyberpunk city transition_speed: type: integer minimum: 1 maximum: 10 description: >- Change determines how quickly the video's content changes across frames. * Higher = more rapid transitions. * Lower = more stable visual experience. example: 5 required: - art_style - camera_effect - prompt_type - transition_speed description: Defines the style of the output video assets: type: object properties: audio_source: type: string enum: - none - file - youtube description: >- Optionally add an audio source if you'd like to incorporate audio into your video example: file audio_file_path: type: string minLength: 1 description: > The path of the input audio. This field is required if `audio_source` is `file`. 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.mp3 youtube_url: type: string format: uri minLength: 1 description: >- Using a youtube video as the input source. This field is required if `audio_source` is `youtube` image_file_path: type: string minLength: 1 description: > An initial image to use a the first frame of the video. 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: - audio_source description: Provide the assets for animation. required: - fps - end_seconds - height - width - style - assets responses: '200': description: Success content: application/json: schema: type: object properties: id: type: string example: cuid-example description: >- Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads. credits_charged: type: integer description: >- The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. If video generation fails, credits will be refunded, and this field will be updated to include the refund. example: 450 required: - id - estimated_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 video 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.animation.generate( assets={ "audio_file_path": "/path/to/1234.mp3", "audio_source": "file", "image_file_path": "/path/to/1234.png", }, end_seconds=15.0, fps=12.0, height=960, style={ "art_style": "Painterly Illustration", "camera_effect": "Simple Zoom In", "prompt": "Cyberpunk city", "prompt_type": "custom", "transition_speed": 5, }, width=512, name="Animation video", 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.animation.generate( { assets: { audioFilePath: "/path/to/1234.mp3", audioSource: "file", imageFilePath: "/path/to/1234.png", }, endSeconds: 15.0, fps: 12.0, height: 960, name: "Animation video", style: { artStyle: "Painterly Illustration", cameraEffect: "Simple Zoom In", prompt: "Cyberpunk city", promptType: "custom", transitionSpeed: 5, }, width: 512, }, { 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\tanimation \"github.com/magichourhq/magic-hour-go/resources/v1/animation\"\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.Animation.Create(animation.CreateRequest{\n\t\tAssets: types.V1AnimationCreateBodyAssets{\n\t\t\tAudioFilePath: nullable.NewValue(\"api-assets/id/1234.mp3\"),\n\t\t\tAudioSource: types.V1AnimationCreateBodyAssetsAudioSourceEnumFile,\n\t\t\tImageFilePath: nullable.NewValue(\"api-assets/id/1234.png\"),\n\t\t},\n\t\tEndSeconds: 15.0,\n\t\tFps: 12.0,\n\t\tHeight: 960,\n\t\tName: nullable.NewValue(\"My Animation video\"),\n\t\tStyle: types.V1AnimationCreateBodyStyle{\n\t\t\tArtStyle: types.V1AnimationCreateBodyStyleArtStyleEnumPainterlyIllustration,\n\t\t\tCameraEffect: types.V1AnimationCreateBodyStyleCameraEffectEnumSimpleZoomIn,\n\t\t\tPrompt: nullable.NewValue(\"Cyberpunk city\"),\n\t\t\tPromptType: types.V1AnimationCreateBodyStylePromptTypeEnumCustom,\n\t\t\tTransitionSpeed: 5,\n\t\t},\n\t\tWidth: 512,\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() .animation() .create(magic_hour::resources::v1::animation::CreateRequest { assets: magic_hour::models::V1AnimationCreateBodyAssets { audio_file_path: Some("api-assets/id/1234.mp3".to_string()), audio_source: magic_hour::models::V1AnimationCreateBodyAssetsAudioSourceEnum::File, image_file_path: Some("api-assets/id/1234.png".to_string()), ..Default::default() }, end_seconds: 15.0, fps: 12.0, height: 960, name: Some("My Animation video".to_string()), style: magic_hour::models::V1AnimationCreateBodyStyle { art_style: magic_hour::models::V1AnimationCreateBodyStyleArtStyleEnum::PainterlyIllustration, camera_effect: magic_hour::models::V1AnimationCreateBodyStyleCameraEffectEnum::SimpleZoomIn, prompt: Some("Cyberpunk city".to_string()), prompt_type: magic_hour::models::V1AnimationCreateBodyStylePromptTypeEnum::Custom, transition_speed: 5, ..Default::default() }, width: 512, }) .await; - lang: curl source: |- curl --request POST \ --url https://api.magichour.ai/v1/animation \ --header 'accept: application/json' \ --header 'authorization: Bearer ' \ --header 'content-type: application/json' \ --data ' { "name": "My Animation video", "fps": 12, "end_seconds": 15, "height": 960, "width": 512, "style": { "art_style": "Painterly Illustration", "art_style_custom": "string", "camera_effect": "Simple Zoom In", "prompt_type": "custom", "prompt": "Cyberpunk city", "transition_speed": 5 }, "assets": { "audio_source": "file", "audio_file_path": "api-assets/id/1234.mp3", "youtube_url": "string", "image_file_path": "api-assets/id/1234.png" } } ' - lang: php source: |- "https://api.magichour.ai/v1/animation", 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 Animation video', 'fps' => 12, 'end_seconds' => 15, 'height' => 960, 'width' => 512, 'style' => [ 'art_style' => 'Painterly Illustration', 'art_style_custom' => 'string', 'camera_effect' => 'Simple Zoom In', 'prompt_type' => 'custom', 'prompt' => 'Cyberpunk city', 'transition_speed' => 5 ], 'assets' => [ 'audio_source' => 'file', 'audio_file_path' => 'api-assets/id/1234.mp3', 'youtube_url' => 'string', 'image_file_path' => 'api-assets/id/1234.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/animation") .header("accept", "application/json") .header("content-type", "application/json") .header("authorization", "Bearer ") .body("{\"name\":\"My Animation video\",\"fps\":12,\"end_seconds\":15,\"height\":960,\"width\":512,\"style\":{\"art_style\":\"Painterly Illustration\",\"art_style_custom\":\"string\",\"camera_effect\":\"Simple Zoom In\",\"prompt_type\":\"custom\",\"prompt\":\"Cyberpunk city\",\"transition_speed\":5},\"assets\":{\"audio_source\":\"file\",\"audio_file_path\":\"api-assets/id/1234.mp3\",\"youtube_url\":\"string\",\"image_file_path\":\"api-assets/id/1234.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) and click "Create new API Key". ````