Ideogram Core Workflow B -- Edit, Remix, Upscale, Describe, Reframe

Overview

Secondary workflows for Ideogram beyond text-to-image generation. Covers five endpoints: Edit (Magic Fill inpainting), Remix (style transfer with image weight), Upscale (enhance resolution), Describe (image-to-text), and Reframe (extend canvas to new aspect ratio). All image-input endpoints use multipart form data.

Prerequisites

• Completed ideogram-install-auth setup
• Source images in JPEG, PNG, or WebP format (max 10MB each)
• For editing: a black-and-white mask image matching source dimensions

Instructions

Step 1: Edit (Magic Fill / Inpainting)

Replace specific regions of an image using a mask. Black regions in the mask indicate areas to regenerate.

import { readFileSync, writeFileSync, mkdirSync } from "fs";

async function editImage(imagePath: string, maskPath: string, prompt: string, options: {
  style_type?: string;
  rendering_speed?: string;
  magic_prompt?: string;
} = {}) {
  const form = new FormData();
  form.append("image", new Blob([readFileSync(imagePath)]), "image.png");
  form.append("mask", new Blob([readFileSync(maskPath)]), "mask.png");
  form.append("prompt", prompt);
  form.append("style_type", options.style_type ?? "GENERAL");
  form.append("rendering_speed", options.rendering_speed ?? "DEFAULT");
  form.append("magic_prompt", options.magic_prompt ?? "AUTO");

  const response = await fetch("https://api.ideogram.ai/v1/ideogram-v3/edit", {
    method: "POST",
    headers: { "Api-Key": process.env.IDEOGRAM_API_KEY! },
    body: form,
  });

  if (!response.ok) throw new Error(`Edit failed: ${response.status} ${await response.text()}`);
  const result = await response.json();

  // Download immediately
  const imgResp = await fetch(result.data[0].url);
  const buffer = Buffer.from(await imgResp.arrayBuffer());
  mkdirSync("./output", { recursive: true });
  writeFileSync(`./output/edited-${result.data[0].seed}.png`, buffer);
  return result;
}

// Example: Replace background
await editImage("product.png", "background-mask.png",
  "Clean white studio background with soft shadows");

// Example: Add text to existing image
await editImage("poster.png", "text-area-mask.png",
  'Bold red text saying "SALE 50% OFF"', { style_type: "DESIGN" });

Step 2: Remix (Style Transfer / Variation)

Generate a new image influenced by a source image. The image_weight parameter (1-100) controls how closely the output matches the original.

async function remixImage(imagePath: string, prompt: string, options: {
  image_weight?: number;
  aspect_ratio?: string;
  style_type?: string;
  rendering_speed?: string;
} = {}) {
  const form = new FormData();
  form.append("image", new Blob([readFileSync(imagePath)]), "image.png");
  form.append("prompt", prompt);
  form.append("image_weight", String(options.image_weight ?? 50));
  form.append("aspect_ratio", options.aspect_ratio ?? "1x1");
  form.append("style_type", options.style_type ?? "GENERAL");
  form.append("rendering_speed", options.rendering_speed ?? "DEFAULT");

  const response = await fetch("https://api.ideogram.ai/v1/ideogram-v3/remix", {
    method: "POST",
    headers: { "Api-Key": process.env.IDEOGRAM_API_KEY! },
    body: form,
  });

  if (!response.ok) throw new Error(`Remix failed: ${response.status}`);
  return response.json();
}

// Low weight = more creative freedom, high weight = closer to original
await remixImage("photo.jpg", "Same scene but in watercolor painting style", { image_weight: 30 });
await remixImage("logo.png", "Same logo but with neon glow effect", { image_weight: 80 });

Step 3: Upscale (Enhance Resolution)

async function upscaleImage(imagePath: string, options: {
  prompt?: string;
  resemblance?: number;
  detail?: number;
} = {}) {
  const form = new FormData();
  form.append("image_file", new Blob([readFileSync(imagePath)]), "image.png");
  form.append("image_request", JSON.stringify({
    prompt: options.prompt,
    resemblance: options.resemblance ?? 50,   // 0-100: fidelity to original
    detail: options.detail ?? 50,              // 0-100: level of detail enhancement
    magic_prompt_option: "AUTO",
  }));

  const response = await fetch("https://api.ideogram.ai/upscale", {
    method: "POST",
    headers: { "Api-Key": process.env.IDEOGRAM_API_KEY! },
    body: form,
  });

  if (!response.ok) throw new Error(`Upscale failed: ${response.status}`);
  const result = await response.json();
  console.log(`Upscaled: ${result.data[0].resolution} -> ${result.data[0].upscaled_resolution}`);
  return result;
}

Step 4: Describe (Image to Text)

async function describeImage(imagePath: string, modelVersion: "V_2" | "V_3" = "V_3") {
  const form = new FormData();
  form.append("image_file", new Blob([readFileSync(imagePath)]), "image.png");
  form.append("describe_model_version", modelVersion);

  const response = await fetch("https://api.ideogram.ai/describe", {
    method: "POST",
    headers: { "Api-Key": process.env.IDEOGRAM_API_KEY! },
    body: form,
  });

  if (!response.ok) throw new Error(`Describe failed: ${response.status}`);
  const result = await response.json();
  return result.descriptions.map((d: any) => d.text);
}

// Use describe to reverse-engineer prompts for existing images
const descriptions = await describeImage("reference-image.jpg");
console.log("Suggested prompts:", descriptions);

Step 5: Reframe (Extend Canvas)

Expand an image to a new resolution while maintaining style consistency.

async function reframeImage(imagePath: string, resolution: string, options: {
  rendering_speed?: string;
  style_preset?: string;
} = {}) {
  const form = new FormData();
  form.append("image", new Blob([readFileSync(imagePath)]), "image.png");
  form.append("resolution", resolution);  // e.g., "1024x576" for 16:9
  form.append("rendering_speed", options.rendering_speed ?? "DEFAULT");
  if (options.style_preset) form.append("style_preset", options.style_preset);

  const response = await fetch("https://api.ideogram.ai/v1/ideogram-v3/reframe", {
    method: "POST",
    headers: { "Api-Key": process.env.IDEOGRAM_API_KEY! },
    body: form,
  });

  if (!response.ok) throw new Error(`Reframe failed: ${response.status}`);
  return response.json();
}

// Reframe a square image to widescreen
await reframeImage("square-photo.png", "1344x768");

Endpoint Quick Reference

Error Handling

Output

• Edited, remixed, upscaled, or reframed images downloaded locally
• Descriptions array for image-to-text analysis
• Metadata including seed, resolution, and safety status

Resources

• Edit V3 API
• Remix V3 API
• Upscale API
• Describe API
• Reframe V3 API

Next Steps

For common errors, see ideogram-common-errors.