> ## Documentation Index
> Fetch the complete documentation index at: https://pavan-c90e8846.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate 3D Models from Text Prompts and Images

> Submit image or text inputs to generate 3D models. Configure condition modes, poll job status, and download your completed results via the API.

AI 3D Model Generator provides two primary ways to create 3D models: uploading images for image-to-3D conversion or entering text prompts for text-to-3D generation. Both methods submit jobs through the Rodin API, which processes your input and returns a downloadable 3D model after completion. You can also combine both approaches for hybrid generation that blends image reference with text description.

## Generation Methods

Choose the input method that fits your use case or combine them for more control over the result.

### Image-to-3D

Upload one or more images in JPG, PNG, or WebP format. The application automatically removes image backgrounds by default, isolating the subject before sending it to the Rodin API.

When you upload multiple images, you can choose how the API processes them together:

| Mode | Behavior | Best For |
| - | - | - |
| **concat** | Stacks images sequentially as additional views | Multiple angles of the same object |
| **fuse** | Blends images together into a single representation | Combining different reference elements |

<Note>
  Supported formats: JPG, PNG, WebP. Maximum file size limits apply based on API constraints.
</Note>

### Text-to-3D

Enter a detailed text prompt describing the 3D model you want to generate. The AI interprets your description, including materials, style, and scale references, to produce a matching 3D object.

You can combine text prompts with uploaded images for hybrid generation. When you provide both inputs, the AI uses the images as visual references while following your text description for materials, style, and modifications.

<Tip>
  Text prompts work best with detailed descriptions. Include specific materials ("brushed aluminum," "matte ceramic"), style references ("low-poly game asset," "photorealistic"), and scale indicators ("handheld device," "monument-sized") for better results.
</Tip>

## Job Lifecycle

Follow these steps to generate and retrieve your 3D model.

<Steps>
  <Step title="Prepare Input">
    Fill in the generation form with image uploads and/or a text prompt. At least one input type (image or prompt) is required. The form validates this before submission.
  </Step>

  <Step title="Configure Quality">
    Select your quality preset and additional options. Higher quality settings produce more detailed models but increase processing time.
  </Step>

  <Step title="Submit Job">
    Submit the form, which triggers a `POST /api/rodin` request with `multipart/form-data` containing your images, text prompt, and configuration options.
  </Step>

  <Step title="Poll for Status">
    The application polls `POST /api/status` using your `subscription_key` to check job progress. Status values include:

    * **queued**: Waiting to start processing
    * **processing**: Actively generating your model
    * **completed**: Model is ready for download
    * **failed**: Processing encountered an error

    The progress field returns a value from 0 to 100 during processing.
  </Step>

  <Step title="Preview Model">
    Once status reports `completed`, view your model in the interactive 3D viewer powered by Three.js. The viewer provides real-time preview with orbit controls, zoom, and material inspection.
  </Step>

  <Step title="Download">
    Trigger `POST /api/download` with your `task_uuid` to receive a download URL plus format and file size information.
  </Step>

  <Step title="Save to Account">
    Optionally save the generated model to your account for future access and management.
  </Step>
</Steps>

## API Reference

The generation flow uses three API endpoints:

### Submit Job

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://3d-aimg-pavan.vercel.app/api/rodin \
    -H "Content-Type: multipart/form-data" \
    -F "image=@model.jpg" \
    -F "prompt=sci-fi helmet with glowing visor"
  ```

  ```javascript JavaScript theme={null}
  const formData = new FormData();
  formData.append("image", imageFile);
  formData.append("prompt", "sci-fi helmet with glowing visor");

  const response = await fetch("https://3d-aimg-pavan.vercel.app/api/rodin", {
    method: "POST",
    body: formData
  });

  const result = await response.json();
  // { success: true, job_id: "abc123", subscription_key: "sub_456", estimated_time: 120 }
  ```
</CodeGroup>

**Response:**

| Field | Type | Description |
| - | - | - |
| `success` | boolean | Whether the job was accepted |
| `job_id` | string | Unique identifier for the job |
| `subscription_key` | string | Key used to poll for status updates |
| `estimated_time` | number | Estimated processing time in seconds |

### Check Status

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://3d-aimg-pavan.vercel.app/api/status \
    -H "Content-Type: application/json" \
    -d '{"subscription_key": "sub_456"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://3d-aimg-pavan.vercel.app/api/status", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ subscription_key: "sub_456" })
  });

  const result = await response.json();
  // { status: "processing", progress: 45, result_url: null, error: null }
  ```
</CodeGroup>

**Response:**

| Field | Type | Description |
| - | - | - |
| `status` | string | Current job status: queued, processing, completed, failed |
| `progress` | number | Completion percentage from 0 to 100 |
| `result_url` | string | URL to preview the finished model (null until completed) |
| `error` | string | Error message if status is failed, otherwise null |

### Download Model

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://3d-aimg-pavan.vercel.app/api/download \
    -H "Content-Type: application/json" \
    -d '{"task_uuid": "abc123"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://3d-aimg-pavan.vercel.app/api/download", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ task_uuid: "abc123" })
  });

  const result = await response.json();
  // { download_url: "https://cdn.rodin.ai/abc123.glb", format: "glb", file_size: 5242880 }
  ```
</CodeGroup>

**Response:**

| Field | Type | Description |
| - | - | - |
| `download_url` | string | Direct URL to download the generated model file |
| `format` | string | Export format of the downloaded file |
| `file_size` | number | File size in bytes |

<Warning>
  You must provide at least one image or text prompt for the form to validate and submit. The API rejects requests with no input.
</Warning>

## Real-Time Preview

After your job completes, the built-in viewer renders your model using Three.js with `@react-three/fiber` and `@react-three/drei` for React integration. The viewer supports:

* Orbit, pan, and zoom controls
* Material and texture inspection
* Real-time lighting adjustments
* Wireframe and solid view modes

This preview lets you evaluate the result before downloading, so you can iterate on your prompt or image inputs if needed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.