Ideogram core workflow b

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

Endpoint	URL	Input	Key Parameters
Edit V3	/v1/ideogram-v3/edit	image + mask + prompt	style_type, rendering_speed
Remix V3	/v1/ideogram-v3/remix	image + prompt	image_weight (1-100)
Upscale	/upscale	image + image_request JSON	resemblance, detail (0-100)
Describe	/describe	image	describe_model_version (V_2/V_3)
Reframe V3	/v1/ideogram-v3/reframe	image + resolution	rendering_speed, style_preset

Error Handling

Error	HTTP Status	Cause	Solution
Mask size mismatch	400	Mask dimensions differ from image	Ensure mask matches source image size exactly
File too large	400	Image exceeds 10MB	Compress or resize before uploading
Safety rejected	422	Image or prompt flagged	Modify content, avoid restricted subjects
Format unsupported	400	Not JPEG/PNG/WebP	Convert image to a supported format
Rate limited	429	Too many requests	Queue with delays between calls

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.