Image Gen

Image Generation & Manipulation API

Generate images from text prompts or modify existing images using various AI techniques.

Base URL

https://api.realm.ai/v1/images

Job Status

Image generation and manipulation tasks are asynchronous. You will typically receive a jobId upon initiating a task. Use the GET /jobs/{jobId} endpoint (described below) to poll for completion status and retrieve results.

Possible statuses: queued, processing, completed, failed.

---

Generate Image (Text-to-Image)

Creates an image based on a textual description (prompt) using a specified model.

• Method: POST

• Endpoint: /generate

• Authentication: API Key

Request Body

{
  "modelId": "mod_zyx987", // Required: ID of the model to use
  "prompt": "A photorealistic portrait of a woman with cyberpunk neon background, high detail", // Required
  "negativePrompt": "low quality, blurry, text, watermark, ugly", // Optional
  "width": 1024, // Optional, defaults to model's preferred size
  "height": 1024, // Optional, defaults to model's preferred size
  "guidanceScale": 7.5, // Optional, controls how strongly the prompt influences the image
  "numOutputs": 1 // Optional, number of images to generate (max 4)
}

Response 202 Accepted

{
  "jobId": "job_img_gen_123",
  "status": "queued",
  "estimatedCompletion": "2024-03-10T15:05:00Z"
}

---

Modify Image (Image-to-Image)

Modifies an existing image based on a prompt and optional mask. Useful for tasks like changing clothing, altering styles, or inpainting.

• Method: POST

• Endpoint: /modify

• Authentication: API Key

• Content-Type: multipart/form-data

Request Body Parameters

• modelId (string): ID of the model to use.

• prompt (string): Description of the desired changes.

• image (file): The input image file (JPEG, PNG).

• mask (file, optional): A black and white image where white areas indicate regions to modify.

• strength (float, optional, 0.0-1.0): Controls the intensity of the modification (higher means more change).

• negativePrompt (string, optional).

• guidanceScale (float, optional).

• numOutputs (int, optional).

Response 202 Accepted

{
  "jobId": "job_img_mod_456",
  "status": "queued"
}

---

Get Job Status & Results

Retrieves the status and, upon completion, the results of an image generation or manipulation job.

• Method: GET

• Endpoint: /jobs/{jobId}

• Authentication: API Key

Response 200 OK (Processing)

{
  "jobId": "job_img_gen_123",
  "status": "processing",
  "progressPercent": 65
}

Response 200 OK (Completed)

{
  "jobId": "job_img_gen_123",
  "status": "completed",
  "results": [
    {
      "imageId": "img_abc",
      "url": "https://cdn.realm.ai/images/img_abc.png",
      "seed": 123456789
    }
    // ... potentially more results if numOutputs > 1
  ],
  "completedAt": "2024-03-10T15:06:10Z"
}

Response 200 OK (Failed)

{
  "jobId": "job_img_mod_456",
  "status": "failed",
  "errorCode": "INAPPROPRIATE_CONTENT",
  "errorMessage": "Generation failed due to content policy violation.",
  "failedAt": "2024-03-10T15:10:00Z"
}