Magic Editor API Documentation

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

📖 Overview

The Magic Editor API allows you to intelligently edit and transform images using AI. By providing a source image and an optional text prompt, the AI will apply smart modifications to the image based on the selected model mode. The workflow is asynchronous and involves two steps:

Create a task — Submit your image and parameters, then receive a taskId.
Poll for results — Use the taskId to query task status and retrieve the edited image.

🔐 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 Magic Editor Task

Creates a new AI magic editor task and returns a unique taskId for polling.

Endpoint

POST /api/v1/magicEditor/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 edit
`prompt`	`string`	⚠️ Conditional	Text prompt describing the desired edits. Required when `modelType` is `Base`; optional for `Flash` and `Pro` modes
`modelType`	`string`	❌ Optional	Model type. Enum: `Flash`, `Base`, `Pro`. Defaults to `Flash`

Model Types

Value	Description	Prompt Required
`Flash`	Default. Fast editing with automatic AI-driven smart generation	❌ Optional
`Base`	Text-guided editing — uses your prompt to precisely control the output	✅ Required
`Pro`	Higher quality editing with more detailed results	❌ Optional

⚠️ Important: When modelType is Base, the prompt field must be provided. Requests with modelType=Base and no prompt will return a parameter error.

📥 Request Examples

cURL

# Flash mode (default) — prompt is optional
curl -X POST "https://api.ideal.house/api/v1/magicEditor/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "modelType": "Flash"
  }'

# Base mode — prompt is required
curl -X POST "https://api.ideal.house/api/v1/magicEditor/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "prompt": "Change the wall color to warm beige and add wooden flooring",
    "modelType": "Base"
  }'

# Pro mode — prompt is optional
curl -X POST "https://api.ideal.house/api/v1/magicEditor/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "prompt": "Modern Scandinavian style interior",
    "modelType": "Pro"
  }'

Java (OkHttp)

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

public class MagicEditorApiExample {

    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 mode (default) — no prompt needed
        String requestBody = """
            {
                "imageUrl": "https://example.com/room.jpg",
                "modelType": "Flash"
            }
            """;

        // Base mode — prompt is required
        // String requestBody = """
        //     {
        //         "imageUrl": "https://example.com/room.jpg",
        //         "prompt": "Change the wall color to warm beige and add wooden flooring",
        //         "modelType": "Base"
        //     }
        //     """;

        // Pro mode — prompt is optional
        // String requestBody = """
        //     {
        //         "imageUrl": "https://example.com/room.jpg",
        //         "prompt": "Modern Scandinavian style interior",
        //         "modelType": "Pro"
        //     }
        //     """;

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/magicEditor/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 mode (default) — no prompt needed
payload = {
    "imageUrl": "https://example.com/room.jpg",
    "modelType": "Flash"
}

# Base mode — prompt is required
# payload = {
#     "imageUrl": "https://example.com/room.jpg",
#     "prompt": "Change the wall color to warm beige and add wooden flooring",
#     "modelType": "Base"
# }

# Pro mode — prompt is optional
# payload = {
#     "imageUrl": "https://example.com/room.jpg",
#     "prompt": "Modern Scandinavian style interior",
#     "modelType": "Pro"
# }

response = requests.post(
    f"{BASE_URL}/api/v1/magicEditor/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 createMagicEditorTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/magicEditor/generate`,
      {
        // Flash mode (default) — no prompt needed
        imageUrl: 'https://example.com/room.jpg',
        modelType: 'Flash'

        // Base mode — prompt is required:
        // imageUrl: 'https://example.com/room.jpg',
        // prompt: 'Change the wall color to warm beige and add wooden flooring',
        // modelType: 'Base'

        // Pro mode — prompt is optional:
        // imageUrl: 'https://example.com/room.jpg',
        // prompt: 'Modern Scandinavian style interior',
        // modelType: 'Pro'
      },
      {
        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);
  }
}

createMagicEditorTask();

📤 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 magic editor task.

Endpoint

GET /api/v1/magicEditor/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/magicEditor/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"

Java (OkHttp)

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

public class MagicEditorResultExample {

    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/magicEditor/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/magicEditor/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", "Termination"):
        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/magicEditor/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', 'Termination'].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;
    }

    // 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",
      "prompt": "Change the wall color to warm beige and add wooden flooring",
      "modelType": "Base"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/magic_editor_result.jpg",
      "width": 1024,
      "height": 1024
    }
  }
}

Response (Task Processing / In Queue)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 40,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "modelType": "Flash"
    },
    "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"
    },
    "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
`input.prompt`	`string`	Text prompt (if provided)
`input.modelType`	`string`	Model type used
`output`	`object`	Generation result (only available when `status` is `Success`)
`output.resultUrl`	`string`	URL to the edited 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
`Termination`	Task was interrupted or terminated

💡 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 — e.g., `prompt` missing when `modelType=Base`	Ensure `prompt` is provided when using `Base` mode
`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/magicEditor/generate                   │
│     → Receive taskId                                    │
│                                                         │
│  2. Wait 3–5 seconds                                    │
│                                                         │
│  3. GET /api/v1/magicEditor/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: edited image            │   │
│     └──────────────────────────────────────────────┘   │
│                                                         │
│     ┌──────────────────────────────────────────────┐   │
│     │ status == "Failed" or "Termination"           │   │
│     │   → Handle error accordingly                  │   │
│     └──────────────────────────────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘