Text-to-3D API Integration Guide for Developers

Adding AI text-to-3D generation directly into your application opens up possibilities for automated asset pipelines, custom creative tools, and on-demand 3D content generation. This guide walks through the technical integration aspects using HiPtah's API as the reference implementation.

API Overview

The HiPtah API provides programmatic access to text-to-3D and image-to-3D generation. It is available on the Creator ($19/mo, 100 generations) and Pro ($39/mo, 300 generations + API) plans. The API uses REST with JSON payloads and requires an API key for authentication.

Base URL: https://api.hiptah.com/v1

Authentication

All API requests require a bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Generate and manage API keys in the HiPtah dashboard under Settings → API Keys. Keys are scoped to specific generation endpoints and have configurable rate limits.

Core Endpoint: Generate 3D Model

POST /generate

Request body:

{
  "prompt": "a medieval wooden cart with iron wheels",
  "format": "glb",
  "quality": "high",
  "callback_url": "https://yourapp.com/webhooks/hiptah"
}

Response (immediate, returns job ID):

{
  "job_id": "gen_abc123xyz",
  "status": "queued",
  "estimated_time_seconds": 30
}

Polling for Results

Since 3D generation takes ~30 seconds, the API uses an async job model. Poll the status endpoint:

GET /job/gen_abc123xyz

{
  "job_id": "gen_abc123xyz",
  "status": "completed",
  "model_url": "https://cdn.hiptah.com/models/gen_abc123xyz.glb",
  "expires_at": "2026-06-15T12:00:00Z"
}

Recommended polling interval: 2 seconds. Most jobs complete in 25-40 seconds. Timeout after 120 seconds and retry with exponential backoff.

Webhook Integration

For production applications, use webhooks instead of polling to reduce server load:

1. Register your webhook URL in the dashboard or via API: POST /webhooks

   {
     "url": "https://yourapp.com/webhooks/hiptah",
     "events": ["job.completed", "job.failed"]
   }
   

2. Your endpoint receives POST payloads:

   {
     "event": "job.completed",
     "job_id": "gen_abc123xyz",
     "model_url": "https://cdn.hiptah.com/models/gen_abc123xyz.glb"
   }
   

3. Validate webhook signatures to ensure requests are from HiPtah

Error Handling

Common error codes and their meanings:

| Code | Meaning | Action | |---|---|---| | 400 | Invalid prompt | Check prompt length (max 500 chars), no special HTML | | 401 | Invalid API key | Verify key in dashboard | | 403 | Plan limit reached | Upgrade plan or wait for monthly reset | | 422 | Format not supported | Use glb, fbx, usdz, stl, or 3mf | | 429 | Rate limit exceeded | Add delay between requests, check plan limits | | 500 | Server error | Retry with exponential backoff |

Rate Limits by Plan

• Creator: 100 generations/month, max 10 concurrent requests
• Pro: 300 generations/month, max 30 concurrent requests
• Enterprise: Custom limits negotiated

Implement a generation queue in your application to respect these limits during high-volume workflows.

Code Examples

JavaScript/Node.js

async function generate3D(prompt) {
  const response = await fetch('https://api.hiptah.com/v1/generate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.HIPT AH_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ prompt, format: 'glb', quality: 'high' })
  });
  const { job_id } = await response.json();
  
  // Poll for completion
  while (true) {
    const status = await fetch(`https://api.hiptah.com/v1/job/${job_id}`, {
      headers: { 'Authorization': `Bearer ${process.env.HIPT AH_API_KEY}` }
    });
    const data = await status.json();
    if (data.status === 'completed') return data.model_url;
    if (data.status === 'failed') throw new Error('Generation failed');
    await sleep(2000);
  }
}

Python

import requests
import time

def generate_3d(prompt):
    headers = {'Authorization': f'Bearer {HIPT AH_API_KEY}'}
    r = requests.post('https://api.hiptah.com/v1/generate',
                      json={'prompt': prompt, 'format': 'glb', 'quality': 'high'},
                      headers=headers)
    job_id = r.json()['job_id']
    
    while True:
        status = requests.get(f'https://api.hiptah.com/v1/job/{job_id}', headers=headers)
        data = status.json()
        if data['status'] == 'completed':
            return data['model_url']
        elif data['status'] == 'failed':
            raise Exception('Generation failed')
        time.sleep(2)

Use Cases

• Game asset marketplaces: Auto-generate preview thumbnails and 3D previews from product descriptions
• E-commerce configurators: Let shoppers customize products visualized as 3D models in real time
• Archviz automation: Generate multiple property visualization variants from structured data
• VR/AR applications: On-demand asset generation for spatial experiences
• Creative tools: Embed generation directly in browser-based 3D design tools