Ideal House
Pular para o conteúdo

Documentação da Change Furniture API#

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


📖 Visão Geral#

A Change Furniture API redefine o estilo ou troca mobília em uma imagem de interior. Envie uma imagem de origem e orientação de estilo opcional, depois consulte o resultado da tarefa assincronamente.

  1. Criar uma tarefa — Envie imageUrl e orientação opcional, então receba um taskId.
  2. Consultar resultados — Use taskId para consultar o status da tarefa e a imagem de saída.

🔐 Autenticação#

Todas as requisições da API devem incluir uma chave API no cabeçalho da requisição.

CabeçalhoValor
APIKEYyour_api_key_here

💰 Dedução de Créditos#

[!WARNING] 🪙 1 crédito é deduzido quando uma tarefa é criada com sucesso. Se a tarefa finalmente falhar, o crédito deduzido será reembolsado automaticamente.
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 de Troca de Mobília1 crédito

🎨 Opções de Estilo#

Esta API suporta parâmetros de estilo opcionais retornados pelo endpoint Configuração de Estilo da API.

Uso:

Texto simples
GET /api/v1/style/change_furniture/getStyles
Grupo de EstiloCampo da RequisiçãoDescrição
roomTypeindoorTypeIdOpção de tipo de cômodo
styleindoorStyleIdOpção de estilo de interior
elementsindoorElemIdOpção de elemento do cômodo. Suporta múltiplos IDs de opção separados por vírgula, por exemplo id1,id2

Cada opção contém:

CampoDescrição
nameNome da opção multilíngue
idValor a passar no campo da requisição
urlImagem de pré-visualização da opção

📌 Endpoints da API#

1. Criar Tarefa de Troca de Mobília#

Endpoint

Texto simples
POST /api/v1/changeFurniture/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 de interior de origem
promptstring❌ OpcionalOrientação por texto para o resultado desejado
indoorTypeIdstring❌ OpcionalID do tipo de cômodo das opções de estilo roomType
indoorStyleIdstring❌ OpcionalID do estilo de interior das opções de estilo style
indoorElemIdstring❌ OpcionalID do elemento do cômodo das opções de estilo elements. Suporta múltiplos IDs separados por vírgula, por exemplo id1,id2

Apenas imageUrl é obrigatório. Todos os outros campos são opcionais.

🖼️ Requisitos de imagem: Use 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 (inclusive). Imagens que excedem as dimensões máximas em pixels são automaticamente reduzidas proporcionalmente para caber dentro de 6,000 × 6,000 px antes do processamento. A URL da imagem deve ser diretamente acessível pelo servidor da API.

📥 Exemplos de Requisição#

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/changeFurniture/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/living-room.jpg",
    "prompt": "replace the sofa with a modern warm neutral sofa",
    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
    "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class ChangeFurnitureApiExample {

    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/living-room.jpg",
                    "prompt": "replace the sofa with a modern warm neutral sofa",
                    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
                    "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
                    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/changeFurniture/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/living-room.jpg",
    "prompt": "replace the sofa with a modern warm neutral sofa",
    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
    "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
}

response = requests.post(
    f"{BASE_URL}/api/v1/changeFurniture/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 createChangeFurnitureTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/changeFurniture/generate`,
      {
        imageUrl: 'https://example.com/living-room.jpg',
        prompt: 'replace the sofa with a modern warm neutral sofa',
        indoorTypeId: 'Interior Design_Interior Scene_Living Room',
        indoorStyleId: 'Interior_Interior Style_Popular_Modern Country',
        indoorElemId: 'Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table'
      },
      {
        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);
  }
}

createChangeFurnitureTask();

📤 Resposta#

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
CampoTipoDescrição
codeinteger0 indica sucesso
messagestringMensagem de resposta
datalongID da tarefa para consulta de resultados

2. Obter Resultado da Tarefa#

Endpoint

Texto simples
GET /api/v1/changeFurniture/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✅ SimID da tarefa retornado pelo endpoint de criação

📥 Exemplos de Requisição#

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

import java.io.IOException;

public class ChangeFurnitureResultExample {

    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/changeFurniture/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/changeFurniture/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 pollChangeFurnitureResult(taskId) {
  const headers = { APIKEY: API_KEY };

  while (true) {
    const response = await axios.get(
      `${BASE_URL}/api/v1/changeFurniture/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));
  }
}

pollChangeFurnitureResult(1234567890123456789n);

📤 Exemplo de Resposta#

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/living-room.jpg",
      "prompt": "replace the sofa with a modern warm neutral sofa",
      "indoorTypeId": "Interior Design_Interior Scene_Living Room",
      "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
      "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/change_furniture_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": 45,
    "input": {
      "imageUrl": "https://example.com/living-room.jpg",
      "prompt": "replace the sofa with a modern warm neutral sofa"
    },
    "output": null
  }
}

Resposta (Tarefa Falhou)

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

📊 Status da Tarefa#

StatusDescrição
UnprocessedTarefa foi criada e está aguardando na fila
ProcessingTarefa está atualmente em execução
SuccessTarefa concluída com sucesso
FailedTarefa falhou e nenhuma saída foi produzida

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


❌ Respostas de Erro#

CódigoNomeDescrição
1011PARAM_ERRORErro no parâmetro da requisição
5002API_KEY_INVALIDChave API inválida ou ausente
9010SCAN_TEXT_ERRORAnálise de conteúdo do prompt falhou
9038PROHIBITED_CONTENTImagem gerada contém conteúdo proibido
9051COINS_NOT_ENOUGHCréditos insuficientes

Para definições completas de erros comuns, consulte Referência de Códigos de Erro.