# Studio API ### Authentication All API requests require authentication using an API key. The API key should be included in the request headers as `x-api-key`. To obtain an API key: 1. Register for an account at [Holoworld](https://app.holoworld.com/) 2. Navigate to your profile > settings 3. Copy the API key. From now on, this key be referenced as `YOUR_API_KEY`
### Before getting started Ensure you have an Agent with a valid body created on Holoworld (consult [create-agent](https://docs.holoworld.com/holoworld/agent-market/create-agent "mention") for more information). Go to your agent's profile page and copy the Agent ID (the agent ID is the last part of the URL after the slash on the Agent's profile page)
From now on, this will be referenced as `YOUR_AGENT_ID.` {% hint style="info" %} Currently only Live2D models are supported. 3D support coming soon... {% endhint %} You will also need Holo credits. Whenever you submit a new Job Render and the Job starts executing, credits will be detracted from your account. For more information about Holo Credits and how to purchase them see [credits-system](https://docs.holoworld.com/holoworld/agent-market/credits-system "mention"). For more information about API pricing, please see [#pricing](#pricing "mention") ### API Endpoints #### Create Video Rendering Job \``` /api/studio/render` `` Initiates a new video rendering job with the specified parameters. * **URL:** `https://app.holoworld.com/api/studio/render` * **Method:** `POST` * **Headers:** * `Content-Type: application/json` * `x-api-key: YOUR_API_KEY` **Request Body** ```json { "renderPayload": { "aspectRatio": "1/1", // or "9/16" "withCaption": true, "brainrot": false, "scenes": [ { "text": "The text that will be spoken by the AI model", "background": { "type": "image", "source": "https://example.com/background.jpg" }, "includeOutro": true, "modelConfig": { "id": YOUR_AGENT_ID, "scale": 1.0, "x": 50, "y": 50 } } ] } } ``` **Response** ```json { "id": "render-12345678-abcd-9876-efgh-123456789abc", // This is the RENDER_ID, use it to pool the status "status": "queued" // Possible values: 'queued' | 'processing' | 'completed' | 'failed' // Other job info... } ``` #### Get Video Rendering Status \``` api/studio/render/{renderId}` `` Retrieves the current status of a video rendering job. * **URL:** `https://app.holoworld.com/api/studio/render/{renderId}` * **Method:** `GET` * **Headers:** * `Content-Type: application/json` * `x-api-key: YOUR_API_KEY` **Response** ```json { "id": RENDER_ID, "status": "completed", // Possible values: 'queued' | 'processing' | 'completed' | 'fail "url": "https://cdn.holoworld.com/videos/12345678-abcd-9876-efgh-123456789abc.mp4" // The link to the video } ``` ### Request and Response Formats All requests and responses are in JSON format. ### Parameters #### Render Payload Parameters | Parameter | Type | Required | Description | | ------------- | ------- | -------- | -------------------------------------------------------------- | | `aspectRatio` | string | Yes | Aspect ratio of the output video. Options: `"1/1"`, `"9`/16`"` | | `withCaption` | boolean | Yes | Whether to include captions/subtitles in the video. | | `brainrot` | boolean | Yes | Generate a brainrot-style video. | | `scenes` | array | Yes | Array of scene objects that make up the video. | #### Scene Parameters | Parameter | Type | Required | Description | | -------------- | ------- | -------- | --------------------------------------------------------------------------- | | `text` | string | Yes | The text that will be spoken by the AI model | | `background` | object | Yes | Configuration for the scene background | | `includeOutro` | boolean | Yes | Whether your agent should include an emote after speaking is done speaking. | | `modelConfig` | object | Yes | Configuration for the AI model in this scene | #### Background Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- | | `type` | string | Yes |

Type of background. Options: "image"
More options coming soon...

| | `source` | string | Yes | URL for image. Use 1200 x 1200 for 1/1 and 1080 x 1920 for 9/16 | #### Model Configuration Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Yes | ID of the Agent to use. This will be used to determined the voice, body, and personality to use during the video. | | `scale` | number | Yes |

Size of the model relative to the frame (0.1-2.0).
You can figure this out from

| | `x` | number | Yes | Horizontal position of the model. You can figure this out from | | `y` | number | Yes | Vertical position of the model. You can figure this out from | ### Limitations and Best Practices #### Limitations * Maximum text length: try to keep the text under 200 characters per scene * Maximum scenes: 5 per video * Supported background image formats: JPG, PNG * Maximum file size for background images: try to keep the images under 5MB ### Pricing Each scene costs 0.3 credits. If a scene also has subtitles that adds an extra 0.1 credits. ### Sample Backgrounds We provide these sample background to easily getting up and running. But you can always add your own! (Just make sure the sizes are correct!) ```javascript // Sample backgrounds for 1/1 videos (1200x1200) [ 'https://hologramxyz.s3.us-east-1.amazonaws.com/backgrounds/video/square/background0.jpg', 'https://hologramxyz.s3.us-east-1.amazonaws.com/backgrounds/video/square/background1.jpg', 'https://hologramxyz.s3.us-east-1.amazonaws.com/backgrounds/video/square/background2.jpg', 'https://hologramxyz.s3.us-east-1.amazonaws.com/backgrounds/video/square/background3.jpg', 'https://hologramxyz.s3.us-east-1.amazonaws.com/backgrounds/video/square/background4.jpg', 'https://hologramxyz.s3.us-east-1.amazonaws.com/backgrounds/video/square/background5.jpg', 'https://hologramxyz.s3.us-east-1.amazonaws.com/backgrounds/video/square/background6.jpg', ]; // Sample backgrounds for 9/16 videos (1080 x 1920) [ 'https://hologramxyz.s3.us-east-1.amazonaws.com/backgrounds/video/vertical/background0.jpg', 'https://hologramxyz.s3.us-east-1.amazonaws.com/backgrounds/video/vertical/background1.jpg', 'https://hologramxyz.s3.us-east-1.amazonaws.com/backgrounds/video/vertical/background2.jpg', 'https://hologramxyz.s3.us-east-1.amazonaws.com/backgrounds/video/vertical/background3.jpg', 'https://hologramxyz.s3.us-east-1.amazonaws.com/backgrounds/video/vertical/background4.jpg', 'https://hologramxyz.s3.us-east-1.amazonaws.com/backgrounds/video/vertical/background5.jpg', 'https://hologramxyz.s3.us-east-1.amazonaws.com/backgrounds/video/vertical/background6.jpg', ]; ``` ### Examples #### Watching the video rendering status in Typescript ```typescript const renderId = '123'; // Await for the video to be completed! while (true) { const response = await fetch( `https://app.holoworld.com/api/studio/render/${renderId}`, { method: 'GET', headers: { 'Content-Type': 'application/json', 'x-api-key': YOUR_API_KEY, }, }, ); if (!response.ok) { const errorData = await response.json(); throw new Error( `HTTP error while polling video render status! status: ${response.status} data: ${errorData}`, ); } const data = await response.json(); if (data.status === 'completed') { return data.url; } if (data.status === 'failed') { throw new Error(`Failed to render video! Reason: ${data.errorMessage}`); } await new Promise((resolve) => setTimeout(resolve, 1000)); } ```