# Introduction to Hydrilla AI > Hydrilla AI provides developers, game studios, and 3D pipelines with programmatic access to our proprietary BlueFox 3D neural reconstruction engine and multi-modal 2D concept models. Canonical URL: https://docs.hydrilla.ai/introduction ## Base URL `https://backend.hydrilla.ai` ## Capabilities - **BlueFox 3D cascade pipeline**: Reconstruct dense 3D meshes up to 1536 resolution with watertight geometry, automated UV unwrapping, and PBR textures ready for Blender, Unreal, and Unity. - **Multi-model 2D generation**: Choose between OpenAI (GPT Image 2.5 Flare & Sunburst) and Google Gemini (Flash & Pro Image) for concept art generation and precise image editing. - **Automated prompt-to-mesh**: Single-call Text-to-3D handles prompt expansion, multi-view concept rendering, background removal, and 3D reconstruction automatically. - **Zero-waste refund guarantee**: Credits are checked upfront, deducted atomically, and 100% refunded if an upstream model or GPU worker encounters an error. ## Sections on this page - Capabilities (https://docs.hydrilla.ai/introduction#capabilities) - System architecture (https://docs.hydrilla.ai/introduction#system-architecture) - Next steps (https://docs.hydrilla.ai/introduction#next-steps) Full documentation index: https://docs.hydrilla.ai/llms.txt --- # Quickstart Guide > Get up and running with the Hydrilla AI API in 3 simple steps: authenticate, submit a 3D reconstruction task, and poll for the downloadable GLB mesh. Canonical URL: https://docs.hydrilla.ai/quickstart ## Step 1: Get your API key Generate a key in the Hydrilla Studio dashboard (`https://hydrilla.co/app/api-keys`). Keys are prefixed with `hyd_live_`. ```bash export HYDRILLA_API_KEY="hyd_live_your_api_key_here" ``` ## Step 2: Submit a 3D generation job ```bash curl -X POST https://backend.hydrilla.ai/v1/3d/text-to-3d \ -H "Authorization: Bearer $HYDRILLA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "Futuristic cyberpunk vehicle, high details, game ready prop", "resolution": 1536}' ``` ## Step 3: Poll for completion and download the mesh Poll `GET /v1/3d/tasks/:taskId` every 2–3 seconds until `status` is `SUCCEEDED`, then download `result.mesh_url` (`.glb`). ```bash curl -X GET https://backend.hydrilla.ai/v1/3d/tasks/job_c18ab44d03e192a40 \ -H "Authorization: Bearer $HYDRILLA_API_KEY" ``` ## Sections on this page - Create your API key (https://docs.hydrilla.ai/quickstart#step-1) - Trigger 3D reconstruction (https://docs.hydrilla.ai/quickstart#step-2) - Poll for completion and download the mesh (https://docs.hydrilla.ai/quickstart#step-3) - Complete Python example (https://docs.hydrilla.ai/quickstart#complete-python-example) - Next steps (https://docs.hydrilla.ai/quickstart#next-steps) Full documentation index: https://docs.hydrilla.ai/llms.txt --- # Authentication > The Hydrilla AI API uses secure Bearer keys to authenticate requests. Manage your keys and monitor usage through the developer dashboard. Canonical URL: https://docs.hydrilla.ai/authentication ## Authorization headers Pass your API key in the `Authorization` header using Bearer authentication (recommended): ```bash curl -X GET https://backend.hydrilla.ai/v1/user/me \ -H "Authorization: Bearer hyd_live_your_api_key_here" ``` Or pass it in the `x-api-key` header: ```bash curl -X GET https://backend.hydrilla.ai/v1/user/me \ -H "x-api-key: hyd_live_your_api_key_here" ``` ## Error codes - `401 Unauthorized`: Invalid, missing, or revoked API key. - `402 Payment Required`: Account credit balance is insufficient for the requested generation. ## Sections on this page - Authorization headers (https://docs.hydrilla.ai/authentication#authorization-headers) - Key security and hashing (https://docs.hydrilla.ai/authentication#key-security) - Error codes (https://docs.hydrilla.ai/authentication#error-codes) Full documentation index: https://docs.hydrilla.ai/llms.txt --- # Models & Engines > Hydrilla AI orchestrates specialized neural architectures across 3D reconstruction and 2D concept rendering. Canonical URL: https://docs.hydrilla.ai/models ## Available Models & Credit Costs | Model ID | Modality | Resolution / Tier | Credits | | --- | --- | --- | --- | | `bluefox-1` | Image-to-3D / Text-to-3D | 1024 standard / 1536 high-detail | 2–5 credits | | `gemini/flash` | 2D Concept Image | Fast concept generation | 1 credit | | `gemini/pro` | 2D Concept Image | Studio-grade concept generation | 2 credits | | `openai/flare` | 2D Concept Image | High-contrast stylized concept | 2 credits | | `openai/sunburst` | 2D Concept Image | Photorealistic lighting & materials | 3 credits | ## Sections on this page - 3D reconstruction models (https://docs.hydrilla.ai/models#3d-reconstruction-models) - 2D concept and image editing models (https://docs.hydrilla.ai/models#2d-image-models) Full documentation index: https://docs.hydrilla.ai/llms.txt --- # Python Integration Guide > Easily integrate Hydrilla 3D and 2D generation into your Python scripts, Blender add-ons, or backend services. Canonical URL: https://docs.hydrilla.ai/sdks/python ## Installation ```bash pip install requests ``` ## Example usage ```python from hydrilla import Hydrilla client = Hydrilla(api_key="hyd_live_your_api_key_here") task_id = client.text_to_3d(prompt="Cyberpunk drone quadcopter", resolution=1536) result = client.poll_task(task_id) print("Download GLB mesh:", result["mesh_url"]) ``` ## Sections on this page - Installation (https://docs.hydrilla.ai/sdks/python#installation) - Python client implementation (https://docs.hydrilla.ai/sdks/python#python-client-implementation) - Example usage (https://docs.hydrilla.ai/sdks/python#example-usage) Full documentation index: https://docs.hydrilla.ai/llms.txt --- # TypeScript Integration Guide > Full TypeScript definitions and helper client for Next.js, Node.js, Bun, or Cloudflare Workers. Canonical URL: https://docs.hydrilla.ai/sdks/typescript ## Example usage ```typescript import { Hydrilla } from "./hydrilla"; const client = new Hydrilla({ apiKey: process.env.HYDRILLA_API_KEY! }); const { id } = await client.textTo3d("Futuristic cyberpunk street lamp", 1536); const result = await client.pollUntilReady(id); console.log("GLB Mesh Ready:", result.mesh_url); ``` ## Sections on this page - TypeScript client implementation (https://docs.hydrilla.ai/sdks/typescript#typescript-client-implementation) - Example usage (https://docs.hydrilla.ai/sdks/typescript#example-usage) Full documentation index: https://docs.hydrilla.ai/llms.txt --- # MCP Server > Connect Claude Code, Cursor, Codex and other MCP clients to Hydrilla. Your agent generates 3D models, places them in your open app, and builds in Blender and 3ds Max. Canonical URL: https://docs.hydrilla.ai/integrations/mcp The server is the npm package `hydrilla-mcp`, a local stdio Model Context Protocol server. It needs Node.js 20 or newer, works on every plan, and generating uses your credits. ## Install Run the command in your terminal (not the agent chat), replace the placeholder with a key from https://hydrilla.ai/app/api-keys, then restart the client. Claude Code (macOS / Linux): ```bash claude mcp add -s user hydrilla --env HYDRILLA_API_KEY=hyd_live_your_api_key_here -- npx -y hydrilla-mcp@latest ``` Claude Code (Windows): ```bash claude mcp add -s user hydrilla --env HYDRILLA_API_KEY=hyd_live_your_api_key_here "--" cmd /c npx -y hydrilla-mcp@latest ``` Codex: ```bash codex mcp add hydrilla --env HYDRILLA_API_KEY=hyd_live_your_api_key_here -- npx -y hydrilla-mcp@latest ``` Cursor (`~/.cursor/mcp.json`), VS Code, Claude Desktop, Windsurf and other JSON clients: ```json { "mcpServers": { "hydrilla": { "command": "npx", "args": ["-y", "hydrilla-mcp@latest"], "env": { "HYDRILLA_API_KEY": "hyd_live_your_api_key_here" } } } } ``` If a Hydrilla plugin on this computer already has your key, leave `env` out: the server reads `~/.hydrilla/config.json`. Check it works by asking the agent: ```text Check that the Hydrilla MCP server is connected: call hydrilla_me and tell me my Hydrilla credit balance. It's free. ``` ## Environment variables - `HYDRILLA_API_KEY`: Your hyd_live_ key. Optional when a Hydrilla plugin on this computer already has the key: the server then reads ~/.hydrilla/config.json on every call. - `HYDRILLA_API_BASE`: API address. Defaults to the production backend. - `HYDRILLA_MAX_TOOLS`: full (default with Hydrilla for 3ds Max installed) lists every 3ds Max tool; progressive lists only three tools that list, describe and run the rest; off hides them. ## Tools - `hydrilla_me`: Plan and credit balance. Free; use it to check the connection. - `hydrilla_text_to_3d`: Generate a textured GLB from a prompt. Uses credits. Optional send_to and name. - `hydrilla_image_to_3d`: Generate a textured GLB from a public image URL. Uses credits. Optional send_to and name. - `hydrilla_get_task`: Status, progress and, once it has succeeded, the mesh URL. Waits up to about 45 seconds per call; wait: false checks instantly. - `hydrilla_list_tasks`: Recent models on the account, newest first. Free. - `hydrilla_cancel_task`: Stop a running task. Unused credits are refunded. - `hydrilla_list_apps`: Which apps on this computer have their Bridge running. - `hydrilla_send_to_app`: Put an existing model into an open app. Free. ## Long-running generations A model takes 10 to 20 minutes. A generate call returns the `task_id` with the progress so far within about a minute; the agent then calls `hydrilla_get_task` until the task succeeds. Hydrilla fails and refunds a task that runs longer than 20 minutes. ## Sending models into an app Pass `send_to` to a generate tool or `hydrilla_get_task`, or call `hydrilla_send_to_app`. The app's Hydrilla plugin must have its Bridge running on 127.0.0.1: - Blender: `send_to: "blender"`, port 7345. Starts with Blender; Run in the Bridge section of the Hydrilla tab. - Maya: `send_to: "maya"`, port 7346. Run Bridge in the Hydrilla window. - 3ds Max: `send_to: "3dsmax"`, port 7347. Run Bridge in Hydrilla › Generate and import…. - Unreal Engine: `send_to: "unreal"`, port 7348. Hydrilla › Run Bridge. - Unity: `send_to: "unity"`, port 7349. Run Bridge in Window › Hydrilla. - Godot 4: `send_to: "godot"`, port 7350. Run Bridge in the Hydrilla dock. ## Blender tools With the Blender add-on 2.1 or newer and its Bridge running: - `hydrilla_blender_scene_info`: Objects in the open Blender scene with world location, rotation, scale and bounding-box size. Read-only. - `hydrilla_blender_run_python`: Run Python (bpy) on Blender's main thread and return what it printed. Needs Let AI edit this scene. Each call is one Ctrl+Z step. - `hydrilla_blender_screenshot`: The 3D viewport as an image. Read-only. Scripts only run after the user turns on **Let AI edit this scene** in the Bridge section of the add-on's Hydrilla tab (off by default). ## 3ds Max tools On Windows with Hydrilla for 3ds Max installed, the server also lists 178 `hydrilla_max_*` tools. Set `HYDRILLA_MAX_TOOLS=progressive` for clients with a tool limit. Agent guide: MCP resource `hydrilla://3dsmax/guide`. ## Sections on this page - Install (https://docs.hydrilla.ai/integrations/mcp#install) - Environment variables (https://docs.hydrilla.ai/integrations/mcp#environment) - Tools (https://docs.hydrilla.ai/integrations/mcp#tools) - Long-running generations (https://docs.hydrilla.ai/integrations/mcp#long-running) - Sending models into an app (https://docs.hydrilla.ai/integrations/mcp#send-to-app) - Blender tools (https://docs.hydrilla.ai/integrations/mcp#blender) - 3ds Max tools (https://docs.hydrilla.ai/integrations/mcp#3dsmax) Full documentation index: https://docs.hydrilla.ai/llms.txt --- # Blender Add-on > Generate from a prompt or image inside Blender, receive models from Studio and your agent over the local Bridge, and let Hydrilla Agent or your own MCP agent build the open scene. Canonical URL: https://docs.hydrilla.ai/integrations/blender ## Install Blender 3.0 or newer, on Windows, macOS or Linux. 1. Download hydrilla-blender.zip from https://hydrilla.ai/plugins/hydrilla-blender.zip. 2. In Blender, open Edit › Preferences › Add-ons. 3. Open the menu at the top right and choose Install from Disk (on Blender 4.1 and older, click Install…). 4. Select hydrilla-blender.zip and tick the box to enable Hydrilla. 5. In the 3D Viewport, press N and open the Hydrilla tab. The add-on updates itself in place when Blender starts (Check looks again; Auto turns it off). ## API key Paste a `hyd_live_` key from https://hydrilla.ai/app/api-keys into the Hydrilla tab. It is saved in `~/.hydrilla/config.json`, not in the .blend file, and shared with the other Hydrilla plugins and the MCP server. There is no browser sign-in. ## Generate Choose Text or Image under Generate and click Generate. Cancel refunds unused credits. The GLB is imported into the open scene; Your models lists recent generations to import again. ## Bridge Listens on `127.0.0.1:7345` and starts with Blender by default (Run and Stop in the Bridge section). `GET /health`; `POST /import` or `/import-file` with `mesh_url` or `file_base64`, plus optional `name` and `job_id`. GLB only. Requests with an `Origin` header are accepted only from Hydrilla's sites or this computer. ```bash curl -X POST http://127.0.0.1:7345/import \ -H "Content-Type: application/json" \ -d '{"mesh_url": "https://…/model.glb", "name": "treasure-chest"}' ``` ## Hydrilla Agent With the key saved, **Connect to Hydrilla Agent** (on by default, add-on 2.3 or newer) links Blender to Hydrilla Agent at https://hydrilla.ai/app/agent. The add-on connects out to the backend; nothing listens on the network for it. Scripts also need Let AI edit this scene. ## Scene tools for MCP agents - `hydrilla_blender_scene_info`: Objects in the open Blender scene with world location, rotation, scale and bounding-box size. Read-only. - `hydrilla_blender_run_python`: Run Python (bpy) on Blender's main thread and return what it printed. Needs Let AI edit this scene. Each call is one Ctrl+Z step. - `hydrilla_blender_screenshot`: The 3D viewport as an image. Read-only. `hydrilla_blender_run_python` only runs while **Let AI edit this scene** is on (off by default). `POST /command` refuses requests with `Origin` or `Sec-Fetch-Site` and needs the `X-Hydrilla-Token` header; the token is written to `~/.hydrilla/bridge/blender.token` (mode 600) each time the Bridge starts. ## Troubleshooting - Key not accepted: paste a new key into the Hydrilla tab. - Nothing arrives: check the Bridge section says Bridge on (click Run if it says Bridge off). - The agent may not change the scene: turn on Let AI edit this scene. - Hydrilla Agent says Blender is not connected: check the key is saved, Connect to Hydrilla Agent is on, and the add-on is 2.3 or newer. - Wrong size: Blender works in meters with Z up. ## Sections on this page - Install (https://docs.hydrilla.ai/integrations/blender#install) - API key (https://docs.hydrilla.ai/integrations/blender#api-key) - Generate (https://docs.hydrilla.ai/integrations/blender#generate) - Bridge (https://docs.hydrilla.ai/integrations/blender#bridge) - Hydrilla Agent (https://docs.hydrilla.ai/integrations/blender#hydrilla-agent) - Scene tools for MCP agents (https://docs.hydrilla.ai/integrations/blender#mcp-tools) - Troubleshooting (https://docs.hydrilla.ai/integrations/blender#troubleshooting) Full documentation index: https://docs.hydrilla.ai/llms.txt --- # 3ds Max Plugin > Install Hydrilla for 3ds Max once and Claude, Cursor, Codex and other MCP apps can read and edit the open 3ds Max scene through 178 hydrilla_max_* tools. It also generates models and imports them. Canonical URL: https://docs.hydrilla.ai/integrations/3dsmax ## Install Windows, 3ds Max 2023 to 2027. No admin rights or separate Python needed. 1. Download hydrilla-3dsmax.mzp from https://hydrilla.ai/integrations/3dsmax. 2. In 3ds Max, choose Scripting › Run Script…, pick the file and click Open (or drag it onto the viewport). Do not use Install Max Creation Graph (.mcg) Package…. 3. Click Yes when Hydrilla asks to install. It confirms when it is done. 4. Restart 3ds Max once. ## Hydrilla menu - `Generate and import…`: Opens the window that generates models from a prompt or picture and runs the Bridge. - `AI connection status`: Says whether AI apps can reach this 3ds Max. - `Connect an AI app…`: Opens the MCP setup steps. - `Use this 3ds Max for AI`: Sends AI requests to this window when several are open. - `Check for updates`: Looks for a newer version now. Hydrilla also checks once a day when 3ds Max starts. - `Uninstall Hydrilla…`: Removes Hydrilla for 3ds Max. ## Connect an AI app Add the Hydrilla MCP server (see /integrations/mcp) to your AI app on the same computer and restart it. Then ask: ```text Use Hydrilla to tell me what is in my open 3ds Max scene. ``` Hydrilla Agent works in Blender only for now; in 3ds Max use your own AI app through the MCP server. ## Tools 178 `hydrilla_max_…` tools: Connection and session, Scripting, Scene state and edits, Inspection, Objects and organization, Modeling and modifiers, Materials and textures, Lighting, Controllers, animation and wiring, Viewport, Render, Effects and state sets, .max files, Autodesk Cosmos assets, Data Channel, Max Creation Graph, tyFlow, RailClone, Forest Pack, Pulze Scene Manager. `HYDRILLA_MAX_TOOLS=progressive` exposes only `hydrilla_max_list_toolsets`, `hydrilla_max_describe_toolset` and `hydrilla_max_call_tool`; `off` hides them. ## How it works The .mzp installs `%APPDATA%\Autodesk\ApplicationPlugins\Hydrilla3dsMax` (C++ plugin, MAXScript listener, menu) and the engine with its own Python in `%LOCALAPPDATA%\Hydrilla\3dsmax` (`install.json`). The MCP server registers the tools when it sees `install.json`, starts the engine on the first call, and the engine talks to 3ds Max over a local named pipe. The engine is the open-source 3dsmax-mcp project (MIT). ## Safety Everything runs locally; every change is one Ctrl+Z step; safe mode (on by default, `%LOCALAPPDATA%\3dsmax-mcp\mcp_config.ini`) blocks scripts that run programs or delete files; unsaved work is never discarded without asking. ## Generate and import Hydrilla › Generate and import…: paste your API key under Account, then Generate from text or Generate from image. Run Bridge (Bridge ON) receives models from Studio or `send_to: "3dsmax"` on port 7347. If 3ds Max cannot import glTF, the GLB is saved and its path shown. ## Troubleshooting - No hydrilla_max tools: restart the AI app (Windows only, with Hydrilla for 3ds Max installed). - Not connected: check Hydrilla › AI connection status; restart 3ds Max once after installing. - Several windows: Hydrilla › Use this 3ds Max for AI. - Remove: Hydrilla › Uninstall Hydrilla…, then restart 3ds Max. ## Sections on this page - Install (https://docs.hydrilla.ai/integrations/3dsmax#install) - Hydrilla menu (https://docs.hydrilla.ai/integrations/3dsmax#menu) - Connect an AI app (https://docs.hydrilla.ai/integrations/3dsmax#connect) - Tools (https://docs.hydrilla.ai/integrations/3dsmax#tools) - How it works (https://docs.hydrilla.ai/integrations/3dsmax#how-it-works) - Safety (https://docs.hydrilla.ai/integrations/3dsmax#safety) - Generate and import (https://docs.hydrilla.ai/integrations/3dsmax#generate) - Troubleshooting (https://docs.hydrilla.ai/integrations/3dsmax#troubleshooting) Full documentation index: https://docs.hydrilla.ai/llms.txt --- # Image to 3D Reconstruction > Reconstruct a production-ready 3D mesh (.glb) from a single concept image via JSON image URL or multipart file upload. Canonical URL: https://docs.hydrilla.ai/api/image-to-3d **Endpoint:** `POST https://backend.hydrilla.ai/v1/3d/image-to-3d` **Credit cost:** 2 credits (1024) / 4 credits (1536) ## Overview Reconstruct a production-ready 3D mesh (.glb) from a single concept image. Supports either JSON image URL or multipart file upload. ## Authentication `Authorization: Bearer hyd_live_your_api_key_here` ## Base URL `https://backend.hydrilla.ai` ## Request body | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `image_url` | `string` | optional | — | Public HTTPS URL of the reference concept image (optional if uploading a file via multipart). | | `image` | `file` | optional | — | Direct binary upload of PNG, JPEG, or WebP image via multipart/form-data. | | `resolution` | `number` | optional | 1536 | Cascade mesh resolution: 1024 (fast draft) or 1536 (ultra high resolution). | | `webhook_url` | `string` | optional | — | Optional HTTPS webhook endpoint to notify when reconstruction finishes. | ## Request example (cURL) ```bash curl -X POST https://backend.hydrilla.ai/v1/3d/image-to-3d \ -H "Authorization: Bearer hyd_live_your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "image_url": "https://storage.googleapis.com/assets/concept-drone.png", "resolution": 1536 }' ``` ## Request example (Python) ```python import requests url = "https://backend.hydrilla.ai/v1/3d/image-to-3d" headers = { "Authorization": "Bearer hyd_live_your_api_key_here", "Content-Type": "application/json" } payload = { "image_url": "https://storage.googleapis.com/assets/concept-drone.png", "resolution": 1536 } response = requests.post(url, headers=headers, json=payload) data = response.json() print("Task queued:", data["id"]) ``` ## Request example (TypeScript) ```typescript const response = await fetch("https://backend.hydrilla.ai/v1/3d/image-to-3d", { method: "POST", headers: { "Authorization": "Bearer hyd_live_your_api_key_here", "Content-Type": "application/json" }, body: JSON.stringify({ image_url: "https://storage.googleapis.com/assets/concept-drone.png", resolution: 1536 }) }); const data = await response.json(); console.log("Task ID:", data.id); ``` ## Response 200 OK ```json { "id": "job_9b1deb4d3b7d4e8b82", "status": "queued", "resolution": 1536, "created_at": "2026-09-30T10:00:00.000Z", "eta_seconds": 45, "links": { "poll": "https://backend.hydrilla.ai/v1/3d/tasks/job_9b1deb4d3b7d4e8b82" } } ``` ## Response 401 Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or revoked API key." } ``` ## Response 402 Payment Required ```json { "error": "Insufficient credits", "credits_required": 2, "credits_available": 0, "upgrade_url": "https://hydrilla.co/app/settings" } ``` --- # Text to 3D Generation > Run the end-to-end pipeline: optimize a text prompt, render a multi-view concept image, and reconstruct a 3D mesh. Canonical URL: https://docs.hydrilla.ai/api/text-to-3d **Endpoint:** `POST https://backend.hydrilla.ai/v1/3d/text-to-3d` **Credit cost:** 3 credits (1024) / 5 credits (1536) ## Overview Automated end-to-end pipeline: optimizes your text prompt, generates a multi-view 2D concept render via OpenAI or Gemini, and reconstructs into a 3D mesh via BlueFox 3D. ## Authentication `Authorization: Bearer hyd_live_your_api_key_here` ## Base URL `https://backend.hydrilla.ai` ## Request body | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `prompt` | `string` | required | — | Text description of the 3D model (e.g. 'A futuristic cyberpunk cybernetic samurai helmet, matte titanium, emissive neon cyan visor'). | | `image_model` | `object` | optional | — | Optional provider settings: { provider: 'openai' | 'gemini', quality: 'standard' | 'high', aspect: '1:1' } | | `resolution` | `number` | optional | 1536 | Mesh cascade resolution: 1024 or 1536. | ## Request example (cURL) ```bash curl -X POST https://backend.hydrilla.ai/v1/3d/text-to-3d \ -H "Authorization: Bearer hyd_live_your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Futuristic cyberpunk vehicle, high details, game ready prop", "image_model": { "provider": "openai", "quality": "high" }, "resolution": 1536 }' ``` ## Request example (Python) ```python import requests url = "https://backend.hydrilla.ai/v1/3d/text-to-3d" headers = { "Authorization": "Bearer hyd_live_your_api_key_here", "Content-Type": "application/json" } payload = { "prompt": "Futuristic cyberpunk vehicle, high details, game ready prop", "image_model": { "provider": "openai", "quality": "high" }, "resolution": 1536 } response = requests.post(url, headers=headers, json=payload) data = response.json() print("Task ID:", data["id"]) ``` ## Request example (TypeScript) ```typescript const response = await fetch("https://backend.hydrilla.ai/v1/3d/text-to-3d", { method: "POST", headers: { "Authorization": "Bearer hyd_live_your_api_key_here", "Content-Type": "application/json" }, body: JSON.stringify({ prompt: "Futuristic cyberpunk vehicle, high details, game ready prop", image_model: { provider: "openai", quality: "high" }, resolution: 1536 }) }); const data = await response.json(); console.log("Task ID:", data.id); ``` ## Response 200 OK ```json { "id": "job_c18ab44d03e192a40", "status": "queued", "prompt": "Futuristic cyberpunk vehicle, high details, game ready prop", "resolution": 1536, "concept_image_url": "https://hydrilla-assets.s3.amazonaws.com/generated/concept_c18ab.png", "created_at": "2026-09-30T10:00:00.000Z", "eta_seconds": 60, "links": { "poll": "https://backend.hydrilla.ai/v1/3d/tasks/job_c18ab44d03e192a40" } } ``` ## Response 401 Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or revoked API key." } ``` ## Response 402 Payment Required ```json { "error": "Insufficient credits", "credits_required": 3, "credits_available": 0, "upgrade_url": "https://hydrilla.co/app/settings" } ``` --- # Tasks & Polling > Poll the current progress and download URLs of an asynchronous 3D generation job. Canonical URL: https://docs.hydrilla.ai/api/tasks **Endpoint:** `GET https://backend.hydrilla.ai/v1/3d/tasks/:taskId` **Credit cost:** Free (0 credits) ## Overview Poll the current progress and download URLs of an asynchronous 3D generation job. The status moves from PENDING to IN_PROGRESS, then ends as SUCCEEDED, FAILED or CANCELLED. Poll every 2–3 seconds; generation usually takes a few minutes. Failed and cancelled jobs refund their credits automatically. ## Authentication `Authorization: Bearer hyd_live_your_api_key_here` ## Base URL `https://backend.hydrilla.ai` ## Path & query parameters | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `taskId` | `string` | required | — | The job identifier returned by /v1/3d/text-to-3d or /v1/3d/image-to-3d. | ## Request example (cURL) ```bash curl -X GET https://backend.hydrilla.ai/v1/3d/tasks/job_9b1deb4d3b7d4e8b82 \ -H "Authorization: Bearer hyd_live_your_api_key_here" ``` ## Request example (Python) ```python import requests import time taskId = "job_9b1deb4d3b7d4e8b82" headers = {"Authorization": "Bearer hyd_live_your_api_key_here"} while True: res = requests.get(f"https://backend.hydrilla.ai/v1/3d/tasks/{taskId}", headers=headers).json() status = res.get("status") print(f"Status: {status} ({res.get('progress', 0)}%)") if status == "SUCCEEDED": print("Download GLB:", res["result"]["mesh_url"]) break elif status in ("FAILED", "CANCELLED"): print("Job failed:", res.get("error")) break time.sleep(3) ``` ## Request example (TypeScript) ```typescript const taskId = "job_9b1deb4d3b7d4e8b82"; const headers = { "Authorization": "Bearer hyd_live_your_api_key_here" }; const pollTask = async () => { const res = await fetch(`https://backend.hydrilla.ai/v1/3d/tasks/${taskId}`, { headers }); const data = await res.json(); if (data.status === "SUCCEEDED") { console.log("3D Mesh ready:", data.result.mesh_url); return data.result; } if (data.status === "FAILED" || data.status === "CANCELLED") { throw new Error(data.error); } await new Promise((r) => setTimeout(r, 3000)); return pollTask(); }; ``` ## Response 200 OK ```json { "id": "job_9b1deb4d3b7d4e8b82", "object": "task", "type": "text-to-3d", "status": "SUCCEEDED", "progress": 100, "status_message": null, "model": "bluefox-1", "result": { "mesh_url": "https://storage.googleapis.com/hydrilla-meshes/job_9b1deb4d3b7d4e8b82.glb", "preview_image_url": "https://storage.googleapis.com/hydrilla-meshes/job_9b1deb4d3b7d4e8b82_thumb.png", "format": "glb", "model": "bluefox-1" }, "error": null, "created_at": 1790762400, "updated_at": 1790762442 } ``` ## Response 401 Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or revoked API key." } ``` --- # List Tasks > List your recent 3D generation tasks, newest first, with download URLs for finished ones. Canonical URL: https://docs.hydrilla.ai/api/tasks-list **Endpoint:** `GET https://backend.hydrilla.ai/v1/3d/tasks` **Credit cost:** Free (0 credits) ## Overview List the account's recent 3D generation tasks, newest first. Use it to find a model that already exists instead of generating it again, or to resume after your app restarts. Finished tasks include result.mesh_url. ## Authentication `Authorization: Bearer hyd_live_your_api_key_here` ## Base URL `https://backend.hydrilla.ai` ## Path & query parameters | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `limit` | `integer` | optional | 20 | How many tasks to return, from 1 to 100. | ## Request example (cURL) ```bash curl -X GET "https://backend.hydrilla.ai/v1/3d/tasks?limit=10" \ -H "Authorization: Bearer hyd_live_your_api_key_here" ``` ## Request example (Python) ```python import requests headers = {"Authorization": "Bearer hyd_live_your_api_key_here"} res = requests.get("https://backend.hydrilla.ai/v1/3d/tasks", params={"limit": 10}, headers=headers).json() for task in res["data"]: mesh = (task.get("result") or {}).get("mesh_url") print(task["id"], task["status"], mesh or "") ``` ## Request example (TypeScript) ```typescript const res = await fetch("https://backend.hydrilla.ai/v1/3d/tasks?limit=10", { headers: { "Authorization": "Bearer hyd_live_your_api_key_here" }, }); const { data } = await res.json(); const ready = data.filter((task) => task.status === "SUCCEEDED"); console.log(ready.map((task) => task.result.mesh_url)); ``` ## Response 200 OK ```json { "object": "list", "data": [ { "id": "job_9b1deb4d3b7d4e8b82", "object": "task", "type": "text-to-3d", "status": "SUCCEEDED", "prompt": "a medieval treasure chest", "model": "bluefox-1", "result": { "mesh_url": "https://storage.googleapis.com/hydrilla-meshes/job_9b1deb4d3b7d4e8b82.glb", "preview_image_url": "https://storage.googleapis.com/hydrilla-meshes/job_9b1deb4d3b7d4e8b82_thumb.png", "format": "glb", "model": "bluefox-1" }, "error": null, "created_at": 1790762400, "updated_at": 1790762442 } ], "has_more": false } ``` ## Response 401 Unauthorized ```json { "error": { "message": "Invalid API key.", "type": "authentication_error" } } ``` --- # Cancel Task > Stop a 3D generation task that is still running. Unused credits are refunded. Canonical URL: https://docs.hydrilla.ai/api/tasks-cancel **Endpoint:** `DELETE https://backend.hydrilla.ai/v1/3d/tasks/:taskId` **Credit cost:** Free (0 credits) ## Overview Stop a task that is still PENDING or IN_PROGRESS. Its credits are refunded automatically. Cancelling a task that has already finished changes nothing and returns its current status. ## Authentication `Authorization: Bearer hyd_live_your_api_key_here` ## Base URL `https://backend.hydrilla.ai` ## Path & query parameters | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `taskId` | `string` | required | — | The job identifier returned by /v1/3d/text-to-3d or /v1/3d/image-to-3d. | ## Request example (cURL) ```bash curl -X DELETE https://backend.hydrilla.ai/v1/3d/tasks/job_9b1deb4d3b7d4e8b82 \ -H "Authorization: Bearer hyd_live_your_api_key_here" ``` ## Request example (Python) ```python import requests headers = {"Authorization": "Bearer hyd_live_your_api_key_here"} res = requests.delete("https://backend.hydrilla.ai/v1/3d/tasks/job_9b1deb4d3b7d4e8b82", headers=headers).json() print(res["status"]) # CANCELLED ``` ## Request example (TypeScript) ```typescript const res = await fetch("https://backend.hydrilla.ai/v1/3d/tasks/job_9b1deb4d3b7d4e8b82", { method: "DELETE", headers: { "Authorization": "Bearer hyd_live_your_api_key_here" }, }); console.log((await res.json()).status); // CANCELLED ``` ## Response 200 OK ```json { "id": "job_9b1deb4d3b7d4e8b82", "object": "task", "status": "CANCELLED" } ``` ## Response 401 Unauthorized ```json { "error": { "message": "Invalid API key.", "type": "authentication_error" } } ``` --- # Generate Concept Image > Render high-fidelity 2D concept art and orthographic visual references. Canonical URL: https://docs.hydrilla.ai/api/images-generate **Endpoint:** `POST https://backend.hydrilla.ai/v1/images/generate` **Credit cost:** 1 credit ## Overview Render high-fidelity 2D concept art and orthographic visual references using leading vision models (OpenAI Flare / Sunburst or Google Gemini Flash / Pro Image). ## Authentication `Authorization: Bearer hyd_live_your_api_key_here` ## Base URL `https://backend.hydrilla.ai` ## Request body | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `prompt` | `string` | required | — | Detailed description of the asset to illustrate. | | `model` | `string` | optional | gpt-image-2.5-flare | Target model: gpt-image-2.5-flare, gpt-image-2.5-sunburst, gemini-3.1-flash-image, or gemini-3-pro-image. | | `aspect_ratio` | `string` | optional | 1:1 | Image aspect ratio: '1:1', '3:2', or '2:3'. | ## Request example (cURL) ```bash curl -X POST https://backend.hydrilla.ai/v1/images/generate \ -H "Authorization: Bearer hyd_live_your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Sci-fi tactical rover with solar panels, clean studio render", "model": "gpt-image-2.5-flare", "aspect_ratio": "1:1" }' ``` ## Request example (Python) ```python import requests url = "https://backend.hydrilla.ai/v1/images/generate" headers = { "Authorization": "Bearer hyd_live_your_api_key_here", "Content-Type": "application/json" } payload = { "prompt": "Sci-fi tactical rover with solar panels, clean studio render", "model": "gpt-image-2.5-flare" } response = requests.post(url, headers=headers, json=payload) print("Image URL:", response.json()["image_url"]) ``` ## Request example (TypeScript) ```typescript const response = await fetch("https://backend.hydrilla.ai/v1/images/generate", { method: "POST", headers: { "Authorization": "Bearer hyd_live_your_api_key_here", "Content-Type": "application/json" }, body: JSON.stringify({ prompt: "Sci-fi tactical rover with solar panels, clean studio render", model: "gpt-image-2.5-flare" }) }); const data = await response.json(); console.log("Rendered Image:", data.image_url); ``` ## Response 200 OK ```json { "image_url": "https://hydrilla-assets.s3.amazonaws.com/generated/img_20260930_rover.png", "model": "gpt-image-2.5-flare", "prompt": "Sci-fi tactical rover with solar panels, clean studio render", "width": 1024, "height": 1024 } ``` ## Response 401 Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or revoked API key." } ``` --- # Edit Concept Image > Modify an existing concept render using natural language prompts and optional masks. Canonical URL: https://docs.hydrilla.ai/api/images-edit **Endpoint:** `POST https://backend.hydrilla.ai/v1/images/edit` **Credit cost:** 1 credit ## Overview Modify an existing concept render using natural language prompts and optional masks. ## Authentication `Authorization: Bearer hyd_live_your_api_key_here` ## Base URL `https://backend.hydrilla.ai` ## Request body | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `image_url` | `string` | required | — | Public HTTPS URL of the base image to modify. | | `prompt` | `string` | required | — | Description of the modifications (e.g. 'Add glowing orange lights and weathered rust scratches'). | | `model` | `string` | optional | gpt-image-2.5-flare | Model to use for editing. | ## Request example (cURL) ```bash curl -X POST https://backend.hydrilla.ai/v1/images/edit \ -H "Authorization: Bearer hyd_live_your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "image_url": "https://hydrilla-assets.s3.amazonaws.com/generated/img_20260930_rover.png", "prompt": "Add heavy battle damage and glowing warning lights", "model": "gpt-image-2.5-flare" }' ``` ## Request example (Python) ```python import requests url = "https://backend.hydrilla.ai/v1/images/edit" headers = { "Authorization": "Bearer hyd_live_your_api_key_here", "Content-Type": "application/json" } payload = { "image_url": "https://hydrilla-assets.s3.amazonaws.com/generated/img_20260930_rover.png", "prompt": "Add heavy battle damage and glowing warning lights" } response = requests.post(url, headers=headers, json=payload) print("Edited Image:", response.json()["image_url"]) ``` ## Request example (TypeScript) ```typescript const response = await fetch("https://backend.hydrilla.ai/v1/images/edit", { method: "POST", headers: { "Authorization": "Bearer hyd_live_your_api_key_here", "Content-Type": "application/json" }, body: JSON.stringify({ image_url: "https://hydrilla-assets.s3.amazonaws.com/generated/img_20260930_rover.png", prompt: "Add heavy battle damage and glowing warning lights" }) }); const data = await response.json(); console.log("Edited Image:", data.image_url); ``` ## Response 200 OK ```json { "image_url": "https://hydrilla-assets.s3.amazonaws.com/generated/img_20260930_rover_edited.png", "model": "gpt-image-2.5-flare", "prompt": "Add heavy battle damage and glowing warning lights" } ``` ## Response 401 Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or revoked API key." } ``` --- # List Models & Capabilities > Returns all currently available 3D reconstruction and 2D concept generation models, active versions, and credit costs. Canonical URL: https://docs.hydrilla.ai/api/models-list **Endpoint:** `GET https://backend.hydrilla.ai/v1/models` **Credit cost:** Free (0 credits) ## Overview Returns all currently available 3D reconstruction and 2D concept generation models, active versions, and credit costs. ## Authentication `Authorization: Bearer hyd_live_your_api_key_here` ## Base URL `https://backend.hydrilla.ai` ## Request example (cURL) ```bash curl -X GET https://backend.hydrilla.ai/v1/models \ -H "Authorization: Bearer hyd_live_your_api_key_here" ``` ## Request example (Python) ```python import requests res = requests.get("https://backend.hydrilla.ai/v1/models", headers={"Authorization": "Bearer hyd_live_..."}) for model in res.json()["models"]: print(model["id"], model["type"], model["credits"]) ``` ## Request example (TypeScript) ```typescript const res = await fetch("https://backend.hydrilla.ai/v1/models", { headers: { "Authorization": "Bearer hyd_live_..." } }); const { models } = await res.json(); console.table(models); ``` ## Response 200 OK ```json { "models": [ { "id": "bluefox-1", "type": "3d", "provider": "hydrilla", "name": "BlueFox 3D v1", "credits": 2, "max_resolution": 1536 }, { "id": "gpt-image-2.5-flare", "type": "image", "provider": "openai", "name": "GPT Image 2.5 Flare", "credits": 1 }, { "id": "gemini-3.1-flash-image", "type": "image", "provider": "gemini", "name": "Gemini 3.1 Flash Image", "credits": 1 } ] } ``` ## Response 401 Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or revoked API key." } ``` --- # Account & Credits > Inspect your developer account credentials, active tier, and remaining credit balance. Canonical URL: https://docs.hydrilla.ai/api/user-me **Endpoint:** `GET https://backend.hydrilla.ai/v1/user/me` **Credit cost:** Free (0 credits) ## Overview Inspect your developer account credentials, active tier, and remaining credit balance. ## Authentication `Authorization: Bearer hyd_live_your_api_key_here` ## Base URL `https://backend.hydrilla.ai` ## Request example (cURL) ```bash curl -X GET https://backend.hydrilla.ai/v1/user/me \ -H "Authorization: Bearer hyd_live_your_api_key_here" ``` ## Request example (Python) ```python import requests res = requests.get("https://backend.hydrilla.ai/v1/user/me", headers={"Authorization": "Bearer hyd_live_..."}) print("Remaining credits:", res.json()["credits"]) ``` ## Request example (TypeScript) ```typescript const res = await fetch("https://backend.hydrilla.ai/v1/user/me", { headers: { "Authorization": "Bearer hyd_live_..." } }); const me = await res.json(); console.log(`Credits remaining: ${me.credits}`); ``` ## Response 200 OK ```json { "user_id": "usr_94f8a120cb9e", "email": "developer@studio.com", "credits": 250, "plan": "pro", "key_prefix": "hyd_live_d81a..." } ``` ## Response 401 Unauthorized ```json { "error": "Unauthorized", "message": "Invalid or revoked API key." } ```