> ## 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 UGC Ad Generator > Create a spoken UGC video from a prepared image and script. Returns a project ID; poll GET /v1/video-projects/{id} for status and downloads. To compose an image, generate the image separately with the Image Editor API and supply its download URL. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/ai-ugc-ad openapi: 3.0.2 info: title: Magic Hour API version: beta description: > Magic Hour provides a REST API (beta) for generating and editing video, images, and audio 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**: API generation and editing requests consume account credits. Cost varies by tool, model, and settings; see [API pricing](https://magichour.ai/api#api-cost-calculator). termsOfService: https://magichour.ai/terms-of-service servers: - url: https://api.magichour.ai security: [] tags: - name: Video Projects description: API related to video projects - name: Image Projects description: API related to image projects - name: Audio Projects description: API related to audio projects - name: Files description: API related to uploading and reusing assets - name: Account description: API related to the account that owns the API key paths: /v1/ai-ugc-ad: post: tags: - Video Projects summary: AI UGC Ad Generator description: >- Create a spoken UGC video from a prepared image and script. Returns a project ID; poll GET /v1/video-projects/{id} for status and downloads. To compose an image, generate the image separately with the Image Editor API and supply its download URL. operationId: aiUgcAd.createVideo parameters: [] requestBody: required: true description: Body content: application/json: schema: type: object properties: assets: type: object properties: image_file_path: type: string minLength: 1 description: > Prepared image to animate. This value is either - a direct URL to the file. The URL path must end in a supported file extension. - `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/image.jpg required: - image_file_path additionalProperties: false script: type: string minLength: 1 description: >- The words the actor should speak. Character limits apply after trimming: * kling-3.0: 2500 characters. * ltx-2.5: 1804 characters. * veo3.1: 2500 characters. LTX's dialogue wrapper counts toward its model prompt limit. example: Meet your new everyday essential. end_seconds: type: number minimum: 1 description: >- Video duration in seconds. Supported values by model: * kling-3.0: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 seconds. * ltx-2.5: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60 seconds. * veo3.1: 4, 6, 8, 15, 22, 29, 36, 43, 50, 57, 64, 71, 78, 85, 92, 99, 106, 113, 120, 127, 134, 141 seconds. Free plans are limited to 5 seconds unless a credit pack has been purchased. example: 4 model: type: string enum: - kling-3.0 - ltx-2.5 - veo3.1 description: >- Defaults to kling-3.0 on paid plans and ltx-2.5 on free plans. resolution: type: string enum: - 480p - 720p - 1080p description: >- Defaults to 720p on paid plans and 480p on free plans. Unsupported model/resolution combinations and resolutions unavailable for your plan are rejected. required: - assets - script - end_seconds additionalProperties: false 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 - 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: '422' 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("MAGIC_HOUR_API_KEY")) res = client.v1.ai_ugc_ad.create( assets={"image_file_path": "api-assets/id/image.jpg"}, end_seconds=4.0, script="Meet your new everyday essential.", ) - lang: javascript source: >- import { Client } from "magic-hour"; const client = new Client({ token: process.env["MAGIC_HOUR_API_KEY"] }); const res = await client.v1.aiUgcAd.create({ assets: { imageFilePath: "api-assets/id/image.jpg" }, endSeconds: 4.0, script: "Meet your new everyday essential.", }); - lang: go source: "package main\n\nimport (\n\tos \"os\"\n\n\tsdk \"github.com/magichourhq/magic-hour-go/client\"\n\tai_ugc_ad \"github.com/magichourhq/magic-hour-go/resources/v1/ai_ugc_ad\"\n\ttypes \"github.com/magichourhq/magic-hour-go/types\"\n)\n\nfunc main() {\n\tclient := sdk.NewClient(\n\t\tsdk.WithBearerAuth(os.Getenv(\"MAGIC_HOUR_API_KEY\")),\n\t)\n\tres, err := client.V1.AiUgcAd.Create(ai_ugc_ad.CreateRequest{\n\t\tAssets: types.V1AiUgcAdCreateBodyAssets{\n\t\t\tImageFilePath: \"api-assets/id/image.jpg\",\n\t\t},\n\t\tEndSeconds: 4.0,\n\t\tScript: \"Meet your new everyday essential.\",\n\t})\n}" - lang: rust source: |- let client = magic_hour::Client::default() .with_bearer_auth(&std::env::var("MAGIC_HOUR_API_KEY").unwrap()); let res = client .v1() .ai_ugc_ad() .create(magic_hour::resources::v1::ai_ugc_ad::CreateRequest { assets: magic_hour::models::V1AiUgcAdCreateBodyAssets { image_file_path: "api-assets/id/image.jpg".to_string(), ..Default::default() }, end_seconds: 4.0, script: "Meet your new everyday essential.".to_string(), ..Default::default() }) .await; - lang: curl source: |- curl --request POST \ --url https://api.magichour.ai/v1/ai-ugc-ad \ --header 'accept: application/json' \ --header "authorization: Bearer $MAGIC_HOUR_API_KEY" \ --header 'content-type: application/json' \ --data ' { "assets": { "image_file_path": "api-assets/id/image.jpg" }, "script": "Meet your new everyday essential.", "end_seconds": 4, "model": "kling-3.0", "resolution": "480p" } ' - lang: php source: |- "https://api.magichour.ai/v1/ai-ugc-ad", 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([ 'assets' => [ 'image_file_path' => 'api-assets/id/image.jpg' ], 'script' => 'Meet your new everyday essential.', 'end_seconds' => 4, 'model' => 'kling-3.0', 'resolution' => '480p' ]), 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-ugc-ad") .header("accept", "application/json") .header("content-type", "application/json") .header("authorization", "Bearer ") .body("{\"assets\":{\"image_file_path\":\"api-assets/id/image.jpg\"},\"script\":\"Meet your new everyday essential.\",\"end_seconds\":4,\"model\":\"kling-3.0\",\"resolution\":\"480p\"}") .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". ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.