AI 3D Rendering API Documentation

Base URL: https://api.ideal.house
Version: v1
Updated: 2026-03-06

📖 Overview

The AI 3D Rendering API allows you to submit a 3D rendering task based on a source image, with fine-grained control over rendering degree, rendering mode, optional text prompt, and reference style images. The workflow is asynchronous and involves two steps:

Create a task — Submit your input parameters and receive a taskId.
Poll for results — Use the taskId to query task status and retrieve the generated output.

🔐 Authentication

All API requests must be authenticated using an API Key.

Include your API Key in the request header:

Header	Value
`APIKEY`	`your_api_key_here`

⚠️ Keep your API Key secure. Do not expose it in client-side code or public repositories.

💰 Credits Deduction

[!WARNING] 🪙 Credits are deducted based on the selected modelType upon successful task creation. If the task ultimately fails, the deducted credits will be automatically refunded to your account.
Insufficient credits will return error code 9051. 📄 See Credits Deduction Reference.

Model (`modelType`)	Credits Deducted
`Flash`	1 credit
`Base`	3 credits
`Pro`	10 credits

📌 API Endpoints

1. Create 3D Rendering Task

Creates a new AI 3D rendering task and returns a unique taskId for polling.

Endpoint

POST /api/v1/ai3dRendering/generate

Request Headers

Header	Required	Description
`APIKEY`	✅ Yes	Your API authentication key
`Content-Type`	✅ Yes	`application/json`

Request Body

Field	Type	Required	Description
`imageUrl`	`string`	✅ Yes	URL of the source image to render
`prompt`	`string`	❌ Optional	Additional text prompt to guide the rendering style or content
`modelType`	`string`	❌ Optional	Model quality type. Enum: `Flash`, `Base`, `Pro`. Defaults to `Flash`
`renderDegree`	`integer`	❌ Optional	Rendering intensity level. Range: `1` (lightest) – `6` (strongest). Defaults to `3`. Only effective when `modelType` is `Flash`
`renderMode`	`string`	❌ Optional	Rendering mode. Enum: `default`, `creativeMode`. Defaults to `default`
`refImageUrl`	`string`	❌ Optional	URL of a reference style image to guide the rendering output

⚠️ Note: renderDegree only takes effect when modelType is set to Flash. If modelType is not specified, Flash is used by default.

Model Types

Value	Description
`Flash`	Default. Fastest generation speed, standard quality. Supports `renderDegree` control
`Base`	Balanced speed and quality. `renderDegree` is ignored
`Pro`	Highest quality, slower generation. `renderDegree` is ignored

Render Modes

Value	Description
`default`	Default mode. Preserves the original image texture and structure during rendering (Keep Texture Mode)
`creativeMode`	Creative mode — applies more artistic and stylized rendering transformations

Render Degree

Value	Description
`1`	Lightest rendering — minimal transformation
`2` – `5`	Progressive rendering intensity
`6`	Strongest rendering — maximum transformation

📥 Request Examples

cURL

# Using Flash model with renderDegree (texture preservation mode)
curl -X POST "https://api.ideal.house/api/v1/ai3dRendering/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "modelType": "Flash",
    "renderDegree": 4,
    "renderMode": "default"
  }'

# Using Flash model with creative mode, prompt and a reference image
curl -X POST "https://api.ideal.house/api/v1/ai3dRendering/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "prompt": "A modern minimalist living room with wooden floor",
    "modelType": "Flash",
    "renderDegree": 5,
    "renderMode": "creativeMode",
    "refImageUrl": "https://example.com/style-reference.jpg"
  }'

# Using Pro model (renderDegree is ignored)
curl -X POST "https://api.ideal.house/api/v1/ai3dRendering/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "modelType": "Pro",
    "renderMode": "default"
  }'

Java (OkHttp)

import okhttp3.*;
import java.io.IOException;

public class Ai3dRenderingApiExample {

    private static final String BASE_URL = "https://api.ideal.house";
    private static final String API_KEY  = "your_api_key_here";

    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();

        // Flash model with renderDegree (renderDegree only works with Flash)
        String requestBody = """
            {
                "imageUrl": "https://example.com/room.jpg",
                "modelType": "Flash",
                "renderDegree": 4,
                "renderMode": "default"
            }
            """;

        // Pro model example (renderDegree is ignored)
        // String requestBody = """
        //     {
        //         "imageUrl": "https://example.com/room.jpg",
        //         "modelType": "Pro",
        //         "renderMode": "default"
        //     }
        //     """;

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/ai3dRendering/generate")
            .addHeader("APIKEY", API_KEY)
            .addHeader("Content-Type", "application/json")
            .post(RequestBody.create(requestBody, MediaType.parse("application/json")))
            .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println("Response: " + response.body().string());
        }
    }
}

Python (requests)

import requests

BASE_URL = "https://api.ideal.house"
API_KEY  = "your_api_key_here"

headers = {
    "APIKEY": API_KEY,
    "Content-Type": "application/json"
}

# Flash model — renderDegree takes effect (default texture preservation mode)
payload = {
    "imageUrl": "https://example.com/room.jpg",
    "modelType": "Flash",
    "renderDegree": 4,
    "renderMode": "default"
}

# Flash model with creative mode, prompt and reference image
# payload = {
#     "imageUrl": "https://example.com/room.jpg",
#     "prompt": "A modern minimalist living room with wooden floor",
#     "modelType": "Flash",
#     "renderDegree": 5,
#     "renderMode": "creativeMode",
#     "refImageUrl": "https://example.com/style-reference.jpg"
# }

# Pro model — renderDegree is ignored
# payload = {
#     "imageUrl": "https://example.com/room.jpg",
#     "modelType": "Pro",
#     "renderMode": "default"
# }

response = requests.post(
    f"{BASE_URL}/api/v1/ai3dRendering/generate",
    headers=headers,
    json=payload
)

data = response.json()
task_id = data.get("data")
print(f"Task ID: {task_id}")

Node.js (axios)

const axios = require('axios');

const BASE_URL = 'https://api.ideal.house';
const API_KEY  = 'your_api_key_here';

async function createRenderingTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/ai3dRendering/generate`,
      {
        // Flash model — renderDegree takes effect
        imageUrl: 'https://example.com/room.jpg',
        modelType: 'Flash',
        renderDegree: 4,
        renderMode: 'default'

        // Flash model with creative mode:
        // prompt: 'A modern minimalist living room with wooden floor',
        // modelType: 'Flash',
        // renderDegree: 5,
        // renderMode: 'creativeMode',
        // refImageUrl: 'https://example.com/style-reference.jpg'

        // Pro model — renderDegree is ignored:
        // imageUrl: 'https://example.com/room.jpg',
        // modelType: 'Pro',
        // renderMode: 'default'
      },
      {
        headers: {
          'APIKEY': API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );

    const taskId = response.data.data;
    console.log('Task ID:', taskId);
    return taskId;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

createRenderingTask();

📤 Response

Success Response

{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}

Field	Type	Description
`code`	`integer`	`0` indicates success
`message`	`string`	Response message
`data`	`long`	The unique task ID for polling results

2. Get Task Result

Retrieves the current status and output of a previously created rendering task.

Endpoint

GET /api/v1/ai3dRendering/result

Request Headers

Header	Required	Description
`APIKEY`	✅ Yes	Your API authentication key

Query Parameters

Parameter	Type	Required	Description
`taskId`	`long`	✅ Yes	The task ID returned from the create task endpoint

📥 Request Examples

cURL

curl -X GET "https://api.ideal.house/api/v1/ai3dRendering/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"

Java (OkHttp)

import okhttp3.*;
import java.io.IOException;

public class Ai3dRenderingResultExample {

    private static final String BASE_URL = "https://api.ideal.house";
    private static final String API_KEY  = "your_api_key_here";

    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();
        long taskId = 1234567890123456789L;

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/ai3dRendering/result?taskId=" + taskId)
            .addHeader("APIKEY", API_KEY)
            .get()
            .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println("Response: " + response.body().string());
        }
    }
}

Python (requests)

import requests
import time

BASE_URL = "https://api.ideal.house"
API_KEY  = "your_api_key_here"

headers = {
    "APIKEY": API_KEY
}

task_id = 1234567890123456789

# Poll until task is complete
while True:
    response = requests.get(
        f"{BASE_URL}/api/v1/ai3dRendering/result",
        headers=headers,
        params={"taskId": task_id}
    )

    data = response.json()
    result = data.get("data", {})
    status = result.get("status")

    print(f"Status: {status}, Progress: {result.get('percentage')}%, Queue: {result.get('waitNumber')}")

    if status in ("Success", "Failed"):
        break

    time.sleep(3)  # Poll every 3 seconds

if status == "Success":
    print("Result URL:", result["output"]["resultUrl"])
else:
    print("Task ended with status:", status)

Node.js (axios)

const axios = require('axios');

const BASE_URL = 'https://api.ideal.house';
const API_KEY  = 'your_api_key_here';

async function pollResult(taskId) {
  const headers = { 'APIKEY': API_KEY };

  while (true) {
    const response = await axios.get(
      `${BASE_URL}/api/v1/ai3dRendering/result`,
      {
        headers,
        params: { taskId }
      }
    );

    const result = response.data.data;
    const { status, percentage, waitNumber } = result;

    console.log(`Status: ${status} | Progress: ${percentage}% | Queue: ${waitNumber}`);

    if (['Success', 'Failed'].includes(status)) {
      if (status === 'Success') {
        console.log('Result URL:', result.output.resultUrl);
      } else {
        console.log('Task ended with status:', status);
      }
      break;
    }

    // Wait 3 seconds before next poll
    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

pollResult(1234567890123456789n);

📤 Response

Success Response (Task Completed)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "modelType": "Flash",
      "renderDegree": 4,
      "renderMode": "default"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/rendered_result.jpg",
      "width": 1024,
      "height": 1024
    }
  }
}

Response (Task Processing / In Queue)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 50,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "modelType": "Flash",
      "renderDegree": 4,
      "renderMode": "default"
    },
    "output": null
  }
}

Response (Task Failed)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Failed",
    "waitNumber": 0,
    "percentage": 0,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "modelType": "Flash",
      "renderDegree": 4,
      "renderMode": "default"
    },
    "output": null
  }
}

Response Fields

Field	Type	Description
`id`	`long`	Task unique identifier
`status`	`string`	Current task status (see Task Status)
`waitNumber`	`integer`	Number of tasks ahead in the queue (`0` means currently processing)
`percentage`	`integer`	Task completion percentage (`0–100`)
`input`	`object`	The original input parameters of the task
`input.imageUrl`	`string`	Source image URL (if provided)
`input.prompt`	`string`	Source text prompt (if provided)
`input.modelType`	`string`	Model type used
`input.renderDegree`	`integer`	Rendering intensity level used (`1–6`)
`input.renderMode`	`string`	Rendering mode used (`default` or `creativeMode`)
`input.refImageUrl`	`string`	Reference style image URL (if provided)
`output`	`object`	Generation result (only available when `status` is `Success`)
`output.resultUrl`	`string`	URL to the rendered output image
`output.width`	`integer`	Output width in pixels
`output.height`	`integer`	Output height in pixels

📊 Task Status

Status	Description
`Unprocessed`	Task has been created but not yet started
`Processing`	Task is currently being processed
`Success`	Task completed successfully — output is available
`Failed`	Task failed due to an error

💡 Polling Recommendation: Poll the result endpoint every 3–5 seconds. Avoid polling too frequently to prevent rate limiting.

❌ Error Responses

All error responses share the same JSON structure:

{
  "code": 5002,
  "message": "Invalid API Key",
  "data": null
}

Error Code Reference

Code	Name	Description	Suggested Action
`1001`	`FAILED`	Request failed (generic error)	Check the `message` field for specific error details
`1003`	`INTERNAL_ERROR`	Internal server error	Retry after a short delay; contact support if it persists
`1011`	`PARAM_ERROR`	Request parameter error	Verify all required parameters are provided and correctly formatted
`5002`	`API_KEY_INVALID`	Invalid or missing API Key	Ensure the `APIKEY` header is present and the value is correct
`9010`	`SCAN_TEXT_ERROR`	Text prompt failed content review	Modify the prompt to remove any sensitive or prohibited content
`9038`	`PROHIBITED_CONTENT`	Generated output image contains prohibited content	Adjust prompt/style/inputs and retry
`9051`	`COINS_NOT_ENOUGH`	Insufficient coins / credits	Top up your account credits and retry

📄 For the complete list of common API error codes, refer to the Error Code Reference.

🔄 Recommended Integration Flow

┌─────────────────────────────────────────────────────────┐
│                                                         │
│  1. POST /api/v1/ai3dRendering/generate                 │
│     → Receive taskId                                    │
│                                                         │
│  2. Wait 3–5 seconds                                    │
│                                                         │
│  3. GET /api/v1/ai3dRendering/result?taskId={taskId}    │
│     → Check status field                               │
│                                                         │
│     ┌──────────────────────────────────────────────┐   │
│     │ status == "Unprocessed" or "Processing"       │   │
│     │   → waitNumber: position in queue             │   │
│     │   → percentage: current progress              │   │
│     │   → Repeat step 2 & 3                         │   │
│     └──────────────────────────────────────────────┘   │
│                                                         │
│     ┌──────────────────────────────────────────────┐   │
│     │ status == "Success"                           │   │
│     │   → output.resultUrl: rendered image          │   │
│     └──────────────────────────────────────────────┘   │
│                                                         │
│     ┌──────────────────────────────────────────────┐   │
│     │ status == "Failed"                            │   │
│     │   → Handle error accordingly                  │   │
│     └──────────────────────────────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘