Ideal House
İçeriğe atla

Plan Görselleştirici API Belgeseli#

Temel URL: https://api.ideal.house
Sürüm: v1
Güncellendi: 2026-05-21


📖 Genel Bakış#

Plan Görselleştirici API, bir plan görüntüsünü yapay zekâ görselleştirmesine dönüştürür. İsteğe bağlı metin yönlendirmesi, plan türü, görsel stil, görünüm seçenekleri ve model modlarını destekler.

İş akışı asenkrondur:

  1. Görev oluşturimageUrl'ü ve isteğe bağlı parametreleri gönderin, ardından bir taskId alın.
  2. Sonuçları sorgula — Görev durumunu ve üretilen görüntüyü almak için taskId kullanın.

🔐 Kimlik Doğrulama#

BaşlıkDeğer
APIKEYyour_api_key_here

💰 Kredi Kesintisi#

[!WARNING] Krediler, bir görev başarıyla oluşturulduğunda kesilir. Görev nihayetinde başarısız olursa, kesilen krediler otomatik olarak iade edilir.
Yetersiz kredi 9051 hata kodunu döndürür. Kredi Kesintisi Referansı bölümüne bakın.

Model (modelType)Kesilen Kredi
Base3 kredi
Pro10 kredi

modelType sağlanmazsa, varsayılan olarak Base kullanılır.


🎨 Stil Seçenekleri#

Bu API, API Stil Yapılandırması uç noktası tarafından döndürülen isteğe bağlı stil parametrelerini destekler.

Kullanım:

Düz metin
GET /api/v1/style/ai_plan_visualizer/getStyles
Stil Grubuİstek AlanıAçıklama
planTypeplanStyleIdPlan türü seçeneği
stylestyleIdGörselleştirme stili seçeneği
viewviewIdKamera/görünüm seçeneği

Her seçenek name, id ve url içerir. Seçenek id'ünü ilgili istek alanına geçirin.


📌 API Uç Noktaları#

1. Plan Görselleştirici Görevi Oluştur#

Uç nokta

Düz metin
POST /api/v1/planVisualizer/generate

İstek Başlıkları

BaşlıkZorunluAçıklama
APIKEY✅ EvetAPI kimlik doğrulama anahtarınız
Content-Type✅ Evetapplication/json

İstek Gövdesi

AlanTürZorunluAçıklama
imageUrlstring✅ EvetKaynak plan görüntüsünün URL'ı
promptstring❌ İsteğe bağlıİstenen görselleştirme için metin yönlendirmesi
planStyleIdstring❌ İsteğe bağlıplanType stil seçeneklerinden plan türü kimliği
styleIdstring❌ İsteğe bağlıstyle stil seçeneklerinden görselleştirme stili kimliği
viewIdstring❌ İsteğe bağlıview stil seçeneklerinden görünüm kimliği
modelTypestring❌ İsteğe bağlıEnum: Base, Pro. Varsayılan Base

Yalnızca imageUrl zorunludur. Diğer tüm alanlar isteğe bağlıdır.

🖼️ Görüntü gereksinimleri: Tüm kaynak ve referans görüntüler JPG/JPEG, PNG veya WebP kullanmalıdır. Her görüntü en fazla 20 MB boyutunda olmalı, boyutları 128 × 128 px ile 6,000 × 6,000 px (dahil) arasında olmalıdır. Maksimum piksel boyutlarını aşan görüntüler, işlemeden önce 6,000 × 6,000 px içine sığacak şekilde orantılı olarak otomatik olarak küçültülür. Görüntü URLs'ları API sunucusu tarafından doğrudan erişilebilir olmalıdır.

📥 İstek Örnekleri#

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/planVisualizer/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/floor-plan.jpg",
    "prompt": "bright modern residential visualization",
    "planStyleId": "AI plan visualizer_Plan type_Master plan",
    "styleId": "AI plan visualizer_Style_Marker pen",
    "viewId": "AI plan visualizer_View_Top-Down View",
    "modelType": "Base"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class PlanVisualizerApiExample {

    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();

        String requestBody = """
                {
                    "imageUrl": "https://example.com/floor-plan.jpg",
                    "prompt": "bright modern residential visualization",
                    "planStyleId": "AI plan visualizer_Plan type_Master plan",
                    "styleId": "AI plan visualizer_Style_Marker pen",
                    "viewId": "AI plan visualizer_View_Top-Down View",
                    "modelType": "Base"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/planVisualizer/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)
python
import requests

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

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

payload = {
    "imageUrl": "https://example.com/floor-plan.jpg",
    "prompt": "bright modern residential visualization",
    "planStyleId": "AI plan visualizer_Plan type_Master plan",
    "styleId": "AI plan visualizer_Style_Marker pen",
    "viewId": "AI plan visualizer_View_Top-Down View",
    "modelType": "Base"
}

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

data = response.json()
task_id = data.get("data")
print(f"Task ID: {task_id}")
Node.js (axios)
javascript
const axios = require('axios');

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

async function createPlanVisualizerTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/planVisualizer/generate`,
      {
        imageUrl: 'https://example.com/floor-plan.jpg',
        prompt: 'bright modern residential visualization',
        planStyleId: 'AI plan visualizer_Plan type_Master plan',
        styleId: 'AI plan visualizer_Style_Marker pen',
        viewId: 'AI plan visualizer_View_Top-Down View',
        modelType: 'Base'
      },
      {
        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);
  }
}

createPlanVisualizerTask();

📤 Yanıt#

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

2. Görev Sonucunu Al#

Uç nokta

Düz metin
GET /api/v1/planVisualizer/result

İstek Başlıkları

BaşlıkZorunluAçıklama
APIKEY✅ EvetAPI kimlik doğrulama anahtarınız

Sorgu Parametreleri

ParametreTürZorunluAçıklama
taskIdlong✅ EvetOluşturma uç noktası tarafından döndürülen görev kimliği

📥 İstek Örnekleri#

cURL
bash
curl -X GET "https://api.ideal.house/api/v1/planVisualizer/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class PlanVisualizerResultExample {

    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/planVisualizer/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)
python
import requests
import time

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

headers = {"APIKEY": API_KEY}
task_id = 1234567890123456789

while True:
    response = requests.get(
        f"{BASE_URL}/api/v1/planVisualizer/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)

if status == "Success":
    print("Result URL:", result["output"]["resultUrl"])
else:
    print("Task ended with status:", status)
Node.js (axios)
javascript
const axios = require('axios');

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

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

  while (true) {
    const response = await axios.get(
      `${BASE_URL}/api/v1/planVisualizer/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);
        console.log('Size:', result.output.width, 'x', result.output.height);
      } else {
        console.log('Task ended with status:', status);
      }
      break;
    }

    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

pollPlanVisualizerResult(1234567890123456789n);

📤 Yanıt Örneği#

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/floor-plan.jpg",
      "prompt": "bright modern residential visualization",
      "planStyleId": "AI plan visualizer_Plan type_Master plan",
      "styleId": "AI plan visualizer_Style_Marker pen",
      "viewId": "AI plan visualizer_View_Top-Down View",
      "modelType": "Base"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/plan_visualizer_result.jpg",
      "width": 1024,
      "height": 1024
    }
  }
}

Yanıt (Görev İşleniyor / Sırada)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 45,
    "input": {
      "imageUrl": "https://example.com/floor-plan.jpg",
      "modelType": "Base"
    },
    "output": null
  }
}

Yanıt (Görev Başarısız)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Failed",
    "waitNumber": 0,
    "percentage": 0,
    "input": {
      "imageUrl": "https://example.com/floor-plan.jpg",
      "modelType": "Base"
    },
    "output": null
  }
}

📊 Görev Durumu#

DurumAçıklama
UnprocessedGörev oluşturuldu ve sırada bekliyor
ProcessingGörev şu anda çalışıyor
SuccessGörev başarıyla tamamlandı
FailedGörev başarısız oldu ve çıktı üretilmedi

Her 3-5 saniyede sorgulayın. API Görev Sınırı bölümüne bakın.


❌ Hata Yanıtları#

KodAdAçıklama
1011PARAM_ERRORİstek parametresi hatası
5002API_KEY_INVALIDGeçersiz veya eksik API anahtarı
9010SCAN_TEXT_ERRORİstem içerik incelemesinden geçemedi
9038PROHIBITED_CONTENTÜretilen görüntü yasaklı içerik barındırıyor
9051COINS_NOT_ENOUGHYetersiz kredi

Tamamlayıcı ortak hata tanımları için Hata Kodu Referansı bölümüne bakın.