Ideal House
Pular para o conteúdo

Documentação da API Exterior Renovator#

URL Base: https://api.ideal.house
Versão: v1
Atualizado: 2026-05-20


📖 Visão Geral#

A API Exterior Renovator permite renovar ou reformar a fachada de um edifício a partir de uma imagem de entrada. Você fornece uma imagem fonte e, opcionalmente, adiciona orientação textual, uma imagem de referência, estilo de edifício ou preferência de ambiente para orientar o resultado da renovação.

O fluxo de trabalho é assíncrono e envolve duas etapas:

  1. Criar uma tarefa — Envie sua imagem externa e orientações opcionais, então receba um taskId.
  2. Consultar resultados — Use o taskId para consultar o status da tarefa e recuperar a imagem gerada.

🔐 Autenticação#

Todas as requisições da API devem ser autenticadas usando uma Chave de API.

Inclua sua Chave de API no cabeçalho da requisição:

CabeçalhoValor
APIKEYyour_api_key_here

⚠️ Mantenha sua Chave de API segura. Não a exponha em código do lado do cliente ou repositórios públicos.


💰 Dedução de Créditos#

[!WARNING] 🪙 1 crédito é deduzido após a criação bem-sucedida da tarefa. Se a tarefa finalmente falhar, o crédito deduzido será automaticamente reembolsado para sua conta.
Créditos insuficientes retornarão o código de erro 9051. 📄 Consulte Referência de Dedução de Créditos.

OperaçãoCréditos Deduzidos
Tarefa Exterior Renovator1 crédito

Para regras detalhadas de créditos, consulte Referência de Dedução de Créditos.


📌 Endpoints da API#


1. Criar Tarefa Exterior Renovator#

Cria uma nova tarefa de renovação externa e retorna um taskId único para consulta.

Endpoint

Texto simples
POST /api/v1/exteriorRenovator/generate

Cabeçalhos da Requisição

CabeçalhoObrigatórioDescrição
APIKEY✅ SimSua chave de autenticação da API
Content-Type✅ Simapplication/json

Corpo da Requisição

CampoTipoObrigatórioDescrição
imageUrlstring✅ SimURL da imagem externa fonte a ser renovada
promptstring❌ OpcionalOrientação textual opcional para o resultado da renovação
referenceUrlstring❌ OpcionalURL de imagem de referência opcional para orientar o estilo visual
buildingStyleIdstring❌ OpcionalID do estilo do edifício
environmentIdstring❌ OpcionalID do estilo de ambiente ou cena. Suporta múltiplos IDs separados por vírgula, por exemplo id1,id2

⚠️ Somente imageUrl é obrigatório. Todos os demais campos do corpo da requisição são opcionais.

🖼️ Requisitos de imagem: Todas as imagens fonte e de referência devem usar JPG/JPEG, PNG ou WebP. Cada imagem deve ter no máximo 20 MB, com dimensões de 128 × 128 px até 6,000 × 6,000 px (inclusivo). Imagens que excedam as dimensões máximas em pixels serão redimensionadas proporcionalmente automaticamente para caber dentro de 6,000 × 6,000 px antes do processamento. Os URLs das imagens devem ser acessíveis diretamente pelo servidor da API.


🎨 Opções de Estilo#

buildingStyleId e environmentId podem ser selecionados no endpoint de Configuração de Estilo da API.

Uso:

Texto simples
GET /api/v1/style/exterior_renovator/getStyles
Grupo de EstiloCampo na RequisiçãoDescrição
buildingStylebuildingStyleIdOpção de estilo do edifício
environmentenvironmentIdOpção de ambiente ou cena. Suporta múltiplos IDs de opção separados por vírgula, por exemplo id1,id2

Cada opção contém name, id e url. Passe o id da opção no campo correspondente da requisição.


📥 Exemplos de Requisição#

cURL
bash
# Minimal request
curl -X POST "https://api.ideal.house/api/v1/exteriorRenovator/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/exterior.jpg"
  }'

# Request with optional guidance
curl -X POST "https://api.ideal.house/api/v1/exteriorRenovator/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/exterior.jpg",
    "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
    "referenceUrl": "https://example.com/reference-house.jpg",
    "buildingStyleId": "modern-farmhouse",
    "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class ExteriorRenovatorApiExample {

    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/exterior.jpg",
                    "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
                    "referenceUrl": "https://example.com/reference-house.jpg",
                    "buildingStyleId": "modern-farmhouse",
                    "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/exteriorRenovator/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/exterior.jpg",
    "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
    "referenceUrl": "https://example.com/reference-house.jpg",
    "buildingStyleId": "modern-farmhouse",
    "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
}

response = requests.post(
    f"{BASE_URL}/api/v1/exteriorRenovator/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 createExteriorRenovatorTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/exteriorRenovator/generate`,
      {
        imageUrl: 'https://example.com/exterior.jpg',
        prompt: 'Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping',
        referenceUrl: 'https://example.com/reference-house.jpg',
        buildingStyleId: 'modern-farmhouse',
        environmentId: 'Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day'
      },
      {
        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);
  }
}

createExteriorRenovatorTask();

📤 Resposta#

Resposta de Sucesso

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
CampoTipoDescrição
codeinteger0 indica sucesso
messagestringMensagem da resposta
datalongO ID único da tarefa para consulta dos resultados

2. Obter Resultado da Tarefa#

Recupera o status atual e a saída de uma tarefa de renovação externa criada anteriormente.

Endpointo

Texto simples
GET /api/v1/exteriorRenovator/result

Cabeçalhos da Requisição

CabeçalhoObrigatórioDescrição
APIKEY✅ SimSua chave de autenticação da API

Parâmetros de Consulta

ParâmetroTipoObrigatórioDescrição
taskIdlong✅ SimO ID da tarefa retornado pelo endpoint de criação

📥 Exemplos de Requisição#

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

import java.io.IOException;

public class ExteriorRenovatorResultExample {

    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/exteriorRenovator/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/exteriorRenovator/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 failed")
Node.js (axios)
javascript
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/exteriorRenovator/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 failed');
      }
      break;
    }

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

pollResult(1234567890123456789);

📤 Resposta#

Resposta de Sucesso (Tarefa Concluída)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/exterior.jpg",
      "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
      "refImageUrl": "https://example.com/reference-house.jpg",
      "buildingStyleId": "modern-farmhouse",
      "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/exterior_renovator_result.jpg",
      "width": 1024,
      "height": 1024
    }
  }
}

Resposta (Tarefa em Processamento / Em Fila)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 50,
    "input": {
      "imageUrl": "https://example.com/exterior.jpg"
    },
    "output": null
  }
}

Resposta (Tarefa Falhou)

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

Campos da Resposta

CampoTipoDescrição
idlongIdentificador único da tarefa
statusstringStatus atual da tarefa (ver Status da Tarefa)
waitNumberintegerNúmero de tarefas à frente na fila (0 significa em processamento atual)
percentageintegerPorcentagem de conclusão da tarefa (0–100)
inputobjectOs parâmetros de entrada originais da tarefa
input.imageUrlstringURL da imagem externa fonte
input.promptstringOrientação textual opcional, se fornecida
input.refImageUrlstringURL de imagem de referência opcional, se fornecida
input.buildingStyleIdstringID do estilo do edifício opcional, se fornecido
input.environmentIdstringID do estilo de ambiente ou cena opcional, se fornecido. Pode conter múltiplos IDs separados por vírgula
outputobjectResultado da geração (disponível apenas quando status é Success)
output.resultUrlstringURL para a imagem do resultado da renovação externa
output.widthintegerLargura da saída em pixels
output.heightintegerAltura da saída em pixels

📊 Status da Tarefa#

StatusDescrição
UnprocessedA tarefa foi criada, mas ainda não começou
ProcessingA tarefa está sendo processada atualmente
SuccessTarefa concluída com sucesso — a saída está disponível
FailedTarefa falhou devido a um erro

Consulte a cada 3-5 segundos. Consulte Limite de Tarefas da API.


❌ Respostas de Erro#

Todas as respostas de erro compartilham a mesma estrutura JSON:

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

Referência de Códigos de Erro#

CódigoNomeDescriçãoAção Sugerida
1001FAILEDFalha na requisição (erro genérico)Verifique o campo message para detalhes específicos do erro
1003INTERNAL_ERRORErro interno do servidorTente novamente após um curto intervalo; entre em contato com o suporte se persistir
1011PARAM_ERRORErro nos parâmetros da requisiçãoCertifique-se de que os parâmetros da requisição estão formatados corretamente
5002API_KEY_INVALIDChave de API inválida ou ausenteCertifique-se de que o cabeçalho APIKEY está presente e o valor está correto
9010SCAN_TEXT_ERRORO prompt textual falhou na análise de conteúdoModifique o prompt para remover qualquer conteúdo sensível ou proibido
9038PROHIBITED_CONTENTA imagem de saída gerada contém conteúdo proibidoAjuste o prompt/estilo/inputs e tente novamente
9051COINS_NOT_ENOUGHMoedas/créditos insuficientesRecarregue os créditos da sua conta e tente novamente. Consulte Referência de Dedução de Créditos

📄 Para a lista completa de códigos de erro comuns da API, consulte a Referência de Códigos de Erro.