> ## 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. # Auto Subtitle Generator API Reference - Magic Hour Docs > Automatically generate subtitles for your video in multiple languages. ## OpenAPI ````yaml post /v1/auto-subtitle-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/auto-subtitle-generator: post: tags: - Video Projects summary: Auto Subtitle Generator description: Automatically generate subtitles for your video in multiple languages. operationId: autoSubtitleGenerator.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 Auto Subtitle video default: Auto Subtitle - dateTime start_seconds: type: number minimum: 0 description: Start time of your clip (seconds). Must be ≥ 0. format: float example: 0 end_seconds: type: number minimum: 0.1 description: >- End time of your clip (seconds). Must be greater than start_seconds. format: float example: 15 assets: type: object properties: video_file_path: type: string minLength: 1 description: > This is the video used to add subtitles. 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.mp4 required: - video_file_path description: Provide the assets for auto subtitle generator style: type: object properties: template: type: string enum: - karaoke - cinematic - minimalist - highlight description: >- Preset subtitle templates. Please visit https://magichour.ai/create/auto-subtitle-generator to see the style of the existing templates. custom_config: type: object properties: font: type: string description: >- Font name from Google Fonts. Not all fonts support all languages or character sets. We recommend verifying language support and appearance directly on https://fonts.google.com before use. example: Noto Sans font_size: type: number description: >- Font size in pixels. If not provided, the font size is automatically calculated based on the video resolution. example: 24 font_style: type: string description: Font style (e.g., normal, italic, bold) example: normal text_color: type: string description: Primary text color in hex format example: '#FFFFFF' highlighted_text_color: type: string description: Color used to highlight the current spoken text example: '#FFD700' stroke_color: type: string description: Stroke (outline) color of the text example: '#000000' stroke_width: type: number description: >- Width of the text stroke in pixels. If `stroke_color` is provided, but `stroke_width` is not, the `stroke_width` will be calculated automatically based on the font size. example: 1 vertical_position: type: string description: >- Vertical alignment of the text (e.g., top, center, bottom) example: bottom horizontal_position: type: string description: >- Horizontal alignment of the text (e.g., left, center, right) example: center description: Custom subtitle configuration. description: > Style of the subtitle. At least one of `.style.template` or `.style.custom_config` must be provided. * If only `.style.template` is provided, default values for the template will be used. * If both are provided, the fields in `.style.custom_config` will be used to overwrite the fields in `.style.template`. * If only `.style.custom_config` is provided, then all fields in `.style.custom_config` will be used. To use custom config only, the following `custom_config` params are required: * `.style.custom_config.font` * `.style.custom_config.text_color` * `.style.custom_config.vertical_position` * `.style.custom_config.horizontal_position` required: - start_seconds - end_seconds - assets - style 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.auto_subtitle_generator.generate( assets={"video_file_path": "/path/to/1234.mp4"}, end_seconds=15.0, start_seconds=0.0, style={}, name="Auto Subtitle 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.autoSubtitleGenerator.generate( { assets: { videoFilePath: "/path/to/1234.mp4" }, endSeconds: 15.0, name: "Auto Subtitle video", startSeconds: 0.0, style: {}, }, { 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\tauto_subtitle_generator \"github.com/magichourhq/magic-hour-go/resources/v1/auto_subtitle_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.AutoSubtitleGenerator.Create(auto_subtitle_generator.CreateRequest{\n\t\tAssets: types.V1AutoSubtitleGeneratorCreateBodyAssets{\n\t\t\tVideoFilePath: \"api-assets/id/1234.mp4\",\n\t\t},\n\t\tEndSeconds: 15.0,\n\t\tName: nullable.NewValue(\"My Auto Subtitle video\"),\n\t\tStartSeconds: 0.0,\n\t\tStyle: types.V1AutoSubtitleGeneratorCreateBodyStyle{},\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() .auto_subtitle_generator() .create(magic_hour::resources::v1::auto_subtitle_generator::CreateRequest { assets: magic_hour::models::V1AutoSubtitleGeneratorCreateBodyAssets { video_file_path: "api-assets/id/1234.mp4".to_string(), }, end_seconds: 15.0, name: Some("My Auto Subtitle video".to_string()), start_seconds: 0.0, style: magic_hour::models::V1AutoSubtitleGeneratorCreateBodyStyle { ..Default::default() }, }) .await; - lang: curl source: |- curl --request POST \ --url https://api.magichour.ai/v1/auto-subtitle-generator \ --header 'accept: application/json' \ --header 'authorization: Bearer ' \ --header 'content-type: application/json' \ --data ' { "name": "My Auto Subtitle video", "start_seconds": 0, "end_seconds": 15, "assets": { "video_file_path": "api-assets/id/1234.mp4" }, "style": { "template": "karaoke", "custom_config": { "font": "Noto Sans", "font_size": 24, "font_style": "normal", "text_color": "#FFFFFF", "highlighted_text_color": "#FFD700", "stroke_color": "#000000", "stroke_width": 1, "vertical_position": "bottom", "horizontal_position": "center" } } } ' - lang: php source: |- "https://api.magichour.ai/v1/auto-subtitle-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 Auto Subtitle video', 'start_seconds' => 0, 'end_seconds' => 15, 'assets' => [ 'video_file_path' => 'api-assets/id/1234.mp4' ], 'style' => [ 'template' => 'karaoke', 'custom_config' => [ 'font' => 'Noto Sans', 'font_size' => 24, 'font_style' => 'normal', 'text_color' => '#FFFFFF', 'highlighted_text_color' => '#FFD700', 'stroke_color' => '#000000', 'stroke_width' => 1, 'vertical_position' => 'bottom', 'horizontal_position' => 'center' ] ] ]), 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/auto-subtitle-generator") .header("accept", "application/json") .header("content-type", "application/json") .header("authorization", "Bearer ") .body("{\"name\":\"My Auto Subtitle video\",\"start_seconds\":0,\"end_seconds\":15,\"assets\":{\"video_file_path\":\"api-assets/id/1234.mp4\"},\"style\":{\"template\":\"karaoke\",\"custom_config\":{\"font\":\"Noto Sans\",\"font_size\":24,\"font_style\":\"normal\",\"text_color\":\"#FFFFFF\",\"highlighted_text_color\":\"#FFD700\",\"stroke_color\":\"#000000\",\"stroke_width\":1,\"vertical_position\":\"bottom\",\"horizontal_position\":\"center\"}}}") .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". ````