feat: clarify API guides and shorten the path to first usage

api-reference/openapi.json

@@ -836,7 +836,7 @@
         "x-codeSamples": [
           {
             "lang": "python",
-            "source": "from magic_hour import Client\nfrom os import getenv\n\nclient = Client(token=getenv(\"API_TOKEN\"))\nres = client.v1.face_detection.generate(\n    assets={\"target_file_path\": \"/path/to/1234.png\"}, confidence_score=0.5\n    wait_for_completion=True,\n    download_outputs=True,\n    download_directory=\".\"\n)"
+            "source": "from magic_hour import Client\nfrom os import getenv\n\nclient = Client(token=getenv(\"API_TOKEN\"))\nres = client.v1.face_detection.generate(\n    assets={\"target_file_path\": \"/path/to/1234.png\"}, confidence_score=0.5,\n    wait_for_completion=True,\n    download_outputs=True,\n    download_directory=\".\"\n)"
           },
           {
             "lang": "javascript",
@@ -6226,7 +6226,7 @@
         "x-codeSamples": [
           {
             "lang": "python",
-            "source": "from magic_hour import Client\nfrom os import getenv\n\nclient = Client(token=getenv(\"API_TOKEN\"))\nres = client.v1.ai_headshot_generator.generate(\n    assets={\"image_file_path\": \"/path/to/1234.png\"}, name=\"Ai Headshot image\"\n    wait_for_completion=True,\n    download_outputs=True,\n    download_directory=\".\"\n)"
+            "source": "from magic_hour import Client\nfrom os import getenv\n\nclient = Client(token=getenv(\"API_TOKEN\"))\nres = client.v1.ai_headshot_generator.generate(\n    assets={\"image_file_path\": \"/path/to/1234.png\"}, name=\"Ai Headshot image\",\n    wait_for_completion=True,\n    download_outputs=True,\n    download_directory=\".\"\n)"
           },
           {
             "lang": "javascript",
@@ -8378,7 +8378,7 @@
         "x-codeSamples": [
           {
             "lang": "python",
-            "source": "from magic_hour import Client\nfrom os import getenv\n\nclient = Client(token=getenv(\"API_TOKEN\"))\nres = client.v1.photo_colorizer.generate(\n    assets={\"image_file_path\": \"/path/to/1234.png\"}, name=\"Photo Colorizer image\"\n    wait_for_completion=True,\n    download_outputs=True,\n    download_directory=\".\"\n)"
+            "source": "from magic_hour import Client\nfrom os import getenv\n\nclient = Client(token=getenv(\"API_TOKEN\"))\nres = client.v1.photo_colorizer.generate(\n    assets={\"image_file_path\": \"/path/to/1234.png\"}, name=\"Photo Colorizer image\",\n    wait_for_completion=True,\n    download_outputs=True,\n    download_directory=\".\"\n)"
           },
           {
             "lang": "javascript",

billing/overview.mdx

@@ -1,5 +1,6 @@
 ---
-title: Pricing Overview
+title: Magic Hour API Pricing
+sidebarTitle: Pricing Overview
 description: Understand API credits and choose a subscription, one-time credit packs, or usage-based billing.
 ---
 
@@ -100,3 +101,10 @@ Usage-based billing is currently available by request. Contact
   **Not sure?** Start with the Free tier. Starter credits and account-specific rewards may be
   available; check your account balance, then choose a payment method after measuring real usage.
 </Info>
+
+## Make your first API request
+
+[Create an API key](https://magichour.ai/developer?tab=api-keys&ref=docs-billing-overview&utm_source=docs&utm_medium=referral&utm_campaign=billing),
+then follow the [quickstart](/get-started/quick-start) to generate an image or video.
+The [account endpoint](/api-reference/account/get-account-details) returns your credit balance and
+subscription details so you can check them before submitting a job.

docs.json

@@ -35,8 +35,8 @@
     ],
     "primary": {
       "type": "button",
-      "label": "Dashboard",
-      "href": "https://magichour.ai/developer?ref=docs-navbar&utm_source=docs&utm_medium=referral&utm_campaign=navbar"
+      "label": "Get API key",
+      "href": "https://magichour.ai/developer?tab=api-keys&ref=docs-navbar&utm_source=docs&utm_medium=referral&utm_campaign=navbar"
     }
   },
   "footer": {
@@ -84,6 +84,7 @@
             "pages": [
               "integration/overview",
               "integration/first-integration",
+              "integration/postman",
               "integration/adding-api-to-your-app",
               "integration/inputs-and-outputs",
               "integration/development-and-testing",
@@ -273,6 +274,16 @@
     ],
     "global": {
       "anchors": [
+        {
+          "anchor": "API quickstart",
+          "href": "/get-started/quick-start",
+          "icon": "forward-fast"
+        },
+        {
+          "anchor": "API pricing",
+          "href": "/billing/overview",
+          "icon": "credit-card"
+        },
         {
           "anchor": "Community",
           "href": "https://discord.com/invite/JX5rgsZaJp",

get-started/quick-start.mdx

@@ -1,10 +1,15 @@
 ---
-title: "Quick Start"
-description: "Generate an API key and make your first call in under 3 minutes."
+title: "Magic Hour API Quickstart"
+sidebarTitle: "Quick Start"
+description: "Create a Magic Hour API key and generate your first image or video with Python, Node.js, Go, Rust, or cURL."
 ---
 
 Magic Hour is an AI video and image generation platform. You submit a job, we render it, and you download the result. This guide gets you to your first output in a few minutes.
 
+Compare [API pricing and payment options](/billing/overview) and
+[per-model credit costs](/api-reference/models) before running a generation. You can use the
+[account endpoint](/api-reference/account/get-account-details) to check your balance.
+
 ## Choose your path
 
 <CardGroup cols={3}>
@@ -69,7 +74,7 @@ export MAGIC_HOUR_API_KEY="your_api_key_here"
 ```
 
 ```cmd Windows
-setx MAGIC_HOUR_API_KEY "your_api_key_here"
+set MAGIC_HOUR_API_KEY=your_api_key_here
 ```
 
 ```powershell PowerShell
@@ -173,6 +178,9 @@ result. Choose the example that matches what you want to build:
 
 Create an image from a text prompt. This is the cheapest way to verify your setup end to end.
 
+See the [image generation guide](/tools/image/image-generator) for prompt examples and the
+[Image Generator API reference](/api-reference/image-projects/ai-image-generator) for every request field.
+
 **Why these parameters:**
 
 - `image_count: 1` - Generate one image (costs 5 credits)

introduction.mdx

@@ -1,5 +1,5 @@
 ---
-title: Welcome to Magic Hour API
+title: Magic Hour API Documentation
 sidebarTitle: Introduction
 description: Magic Hour API documentation - generate videos, images, and audio using AI.
 "og:title": "API Documentation | Magic Hour"
@@ -8,6 +8,9 @@ description: Magic Hour API documentation - generate videos, images, and audio u
 
 Magic Hour API is an API for AI-powered video and image generation. You can run models for creating videos, images, and audio through a single REST API.
 
+[Create an API key](https://magichour.ai/developer?tab=api-keys&ref=docs-introduction&utm_source=docs&utm_medium=referral&utm_campaign=introduction),
+follow the [quickstart](/get-started/quick-start), or compare [API pricing](/billing/overview).
+
 ## Choose how to use Magic Hour
 
 Magic Hour supports three ways to create, depending on how much control and automation you need:
@@ -47,7 +50,7 @@ If you're new to Magic Hour, start here to learn the essentials and make your fi
   <Card title="Quick Start" icon="forward-fast" href="/get-started/quick-start">
     First request in 3 minutes.
   </Card>
-  <Card title="API Reference" icon="webhook" href="/api-reference">
+  <Card title="API Reference" icon="webhook" href="/api-reference/overview">
     All endpoints in one place.
   </Card>
   <Card

snippets/tool-section.mdx

@@ -6,13 +6,39 @@ export const ToolSection = ({
   apiSlug = "" 
 }) => (
   <>
+    <CardGroup cols={2}>
+      <Card
+        title={`${title} API reference`}
+        icon="webhook"
+        horizontal
+        href={`/api-reference/${type}-projects/${apiSlug}`}
+      >
+        Request fields, responses, and examples
+      </Card>
+      <Card
+        title="API quickstart"
+        icon="forward-fast"
+        horizontal
+        href="/get-started/quick-start"
+      >
+        Install an SDK and complete your first generation
+      </Card>
+    </CardGroup>
+
+    <p>
+      Check <a href="/billing/overview">API pricing</a> and <a href="/api-reference/models">model credit costs</a>, then <a href={`https://magichour.ai/developer?tab=api-keys&ref=docs-tool-${apiSlug}&utm_source=docs&utm_medium=referral&utm_campaign=tools`}>create an API key</a>.
+    </p>
+    <p>
+      To try {title} without code, use the <a href={`https://magichour.ai/products/${productSlug}${productSlug.includes("?") ? "&" : "?"}utm_source=docs&utm_medium=referral&utm_campaign=tools`}>browser tool</a>.
+    </p>
+
     {outputs && outputs.length > 0 && (
       <Tabs>
         {outputs.map((output, idx) => (
           <Tab key={idx} title={`Example Output ${idx + 1}`}>
             <Frame>
               {type === "video" ? (
-                <video 
+                <video
                   controls
                   preload="metadata"
                   playsInline
@@ -22,7 +48,7 @@ export const ToolSection = ({
                 >
                 </video>
               ) : type === "audio" ? (
-                <audio 
+                <audio
                   controls
                   preload="metadata"
                   className="w-full"
@@ -31,10 +57,11 @@ export const ToolSection = ({
                   Your browser does not support the audio element.
                 </audio>
               ) : (
-                <img 
-                  height="320" 
-                  className="rounded-lg h-80" 
-                  src={output.src} 
+                <img
+                  alt={`${title} example output ${idx + 1}`}
+                  height="320"
+                  className="rounded-lg h-80"
+                  src={output.src}
                 />
               )}
             </Frame>
@@ -43,24 +70,5 @@ export const ToolSection = ({
       </Tabs>
     )}
 
-    <CardGroup cols={2}>
-      <Card
-        title="API Spec"
-        icon="webhook"
-        horizontal
-        href={`/api-reference/${type}-projects/${apiSlug}`}
-      >
-        See API details
-      </Card>
-      <Card
-        title="Product Page"
-        icon="video"
-        horizontal
-        href={`https://magichour.ai/products/${productSlug}${productSlug.includes("?") ? "&" : "?"}utm_source=docs&utm_medium=referral&utm_campaign=tools`}
-      >
-        Learn more about {title}
-      </Card>
-    </CardGroup>
-
   </>
 );

tools/audio/voice-cloner.mdx

@@ -1,5 +1,5 @@
 ---
-title: AI Voice Cloner Tool - Magic Hour Docs
+title: AI Voice Cloner API
 sidebarTitle: Voice Cloner
 description: Clone any voice and generate realistic speech audio from text using custom voice samples.
 ---
@@ -117,18 +117,22 @@ import { Client } from "magic-hour";
 
 const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY });
 
-const result = await client.v1.aiVoiceCloner.generate({
-  assets: {
-    audioFilePath: "path/to/voice_sample.mp3",
-  },
-  style: {
-    prompt: "Hello! This is a test of the Magic Hour voice cloner. Pretty cool, right?",
+const result = await client.v1.aiVoiceCloner.generate(
+  {
+    assets: {
+      audioFilePath: "path/to/voice_sample.mp3",
+    },
+    style: {
+      prompt: "Hello! This is a test of the Magic Hour voice cloner. Pretty cool, right?",
+    },
+    name: "Voice Cloner audio",
   },
-  name: "Voice Cloner audio",
-  waitForCompletion: true,
-  downloadOutputs: true,
-  downloadDirectory: ".",
-});
+  {
+    waitForCompletion: true,
+    downloadOutputs: true,
+    downloadDirectory: ".",
+  }
+);
 
 console.log(`✅ Voice cloning complete!`);
 console.log(`Status: ${result.status}`);
@@ -149,7 +153,7 @@ result = client.v1.ai_voice_cloner.generate(
     style={
         "prompt": "Welcome to the show! Today we're going to talk about something really exciting."
     },
-    name: "Voice Cloner audio",
+    name="Voice Cloner audio",
     wait_for_completion=True,
     download_outputs=True,
     download_directory="."
@@ -166,18 +170,22 @@ else:
 ```
 
 ```javascript Node.js
-const result = await client.v1.aiVoiceCloner.generate({
-  assets: {
-    audioFilePath: "https://example.com/voice_sample.mp3",
-  },
-  style: {
-    prompt: "Welcome to the show! Today we're going to talk about something really exciting.",
+const result = await client.v1.aiVoiceCloner.generate(
+  {
+    assets: {
+      audioFilePath: "https://example.com/voice_sample.mp3",
+    },
+    style: {
+      prompt: "Welcome to the show! Today we're going to talk about something really exciting.",
+    },
+    name: "Voice Cloner audio",
   },
-  name: "Voice Cloner audio",
-  waitForCompletion: true,
-  downloadOutputs: true,
-  downloadDirectory: ".",
-});
+  {
+    waitForCompletion: true,
+    downloadOutputs: true,
+    downloadDirectory: ".",
+  }
+);
 
 console.log(`✅ Downloaded to: ${result.downloadedPaths}`);
 ```
@@ -213,18 +221,22 @@ else:
 ```
 
 ```javascript Node.js
-const result = await client.v1.aiVoiceCloner.generate({
-  assets: {
-    audioFilePath: "path/to/narrator_voice.mp3",
-  },
-  style: {
-    prompt: "In a world where technology meets creativity, Magic Hour brings your ideas to life.",
+const result = await client.v1.aiVoiceCloner.generate(
+  {
+    assets: {
+      audioFilePath: "path/to/narrator_voice.mp3",
+    },
+    style: {
+      prompt: "In a world where technology meets creativity, Magic Hour brings your ideas to life.",
+    },
+    name: "Voice Cloner audio",
   },
-  name: "Voice Cloner audio",
-  waitForCompletion: true,
-  downloadOutputs: true,
-  downloadDirectory: ".",
-});
+  {
+    waitForCompletion: true,
+    downloadOutputs: true,
+    downloadDirectory: ".",
+  }
+);
 
 console.log(`✅ Downloaded to: ${result.downloadedPaths}`);
 ```
@@ -288,11 +300,11 @@ print("lip_status:", lip_sync_result.status, "paths:", getattr(lip_sync_result,
 
 Voice cloning costs **0.1 credits per character** of generated text, rounded up to the nearest whole number. Inputs support up to 1,000 characters.
 
-| Text Length                       | Credits     |
-| :-------------------------------- | :---------- |
-| 100 characters (1-2 sentences)    | 10 credits  |
-| 500 characters (a paragraph)      | 50 credits  |
-| 1,000 characters (maximum)         | 100 credits |
+| Text Length                    | Credits     |
+| :----------------------------- | :---------- |
+| 100 characters (1-2 sentences) | 10 credits  |
+| 500 characters (a paragraph)   | 50 credits  |
+| 1,000 characters (maximum)     | 100 credits |
 
 <Tip>
   **Try this in our Google Colab Cookbook:** [Run this API with sample