Recall Parameters API

Overview

A new REST API endpoint has been added to the InvokeAI backend that allows programmatic updates to recallable parameters from another process. This enables external applications or scripts to modify frontend parameters like prompts, models, and step counts via HTTP requests.

When parameters are updated via the API, the backend automatically broadcasts a WebSocket event to all connected frontend clients subscribed to that queue, causing them to update immediately.

How It Works

1. API Request: External application sends a POST request with parameters to update
2. Storage: Parameters are stored in client state persistence, associated with a queue ID
3. Broadcast: A WebSocket event (recall_parameters_updated) is emitted to all frontend clients listening to that queue
4. Frontend Update: Connected frontend clients receive the event and can process the updated parameters
5. Immediate Display: The frontend UI updates automatically with the new values

This means if you have the InvokeAI frontend open in a browser, updating parameters via the API will instantly reflect on the screen without any manual action needed.

Endpoint

Base URL: http://localhost:9090/api/v1/recall/{queue_id}

POST - Update Recall Parameters

Updates recallable parameters for a given queue ID.

Request

POST /api/v1/recall/{queue_id}
Content-Type: application/json

{
  "positive_prompt": "a beautiful landscape",
  "negative_prompt": "blurry, low quality",
  "model": "sd-1.5",
  "steps": 20,
  "cfg_scale": 7.5,
  "width": 512,
  "height": 512,
  "seed": 12345
}

The queue id is usually "default".

Parameters

All parameters are optional. Only provide the parameters you want to update:

Response

{
  "status": "success",
  "queue_id": "queue_123",
  "updated_count": 7,
  "parameters": {
    "positive_prompt": "a beautiful landscape",
    "negative_prompt": "blurry, low quality",
    "model": "sd-1.5",
    "steps": 20,
    "cfg_scale": 7.5,
    "width": 512,
    "height": 512,
    "seed": 12345
  }
}

GET - Retrieve Recall Parameters

Retrieves metadata about stored recall parameters.

Request

GET /api/v1/recall/{queue_id}

Response

{
  "status": "success",
  "queue_id": "queue_123",
  "note": "Use the frontend to access stored recall parameters, or set specific parameters using POST"
}

Usage Examples

Using cURL

# Update prompts and model
curl -X POST http://localhost:9090/api/v1/recall/default \
  -H "Content-Type: application/json" \
  -d '{
    "positive_prompt": "a cyberpunk city at night",
    "negative_prompt": "dark, unclear",
    "model": "sd-1.5",
    "steps": 30
  }'

# Update just the seed
curl -X POST http://localhost:9090/api/v1/recall/default \
  -H "Content-Type: application/json" \
  -d '{"seed": 99999}'

Using Python

import requests
import json

# Configuration
API_URL = "http://localhost:9090/api/v1/recall/default"

# Update multiple parameters
params = {
    "positive_prompt": "a serene forest",
    "negative_prompt": "people, buildings",
    "steps": 25,
    "cfg_scale": 7.0,
    "seed": 42
}

response = requests.post(API_URL, json=params)
result = response.json()

print(f"Status: {result['status']}")
print(f"Updated {result['updated_count']} parameters")
print(json.dumps(result['parameters'], indent=2))

Using Node.js/JavaScript

const API_URL = 'http://localhost:9090/api/v1/recall/default';

const params = {
  positive_prompt: 'a beautiful sunset',
  negative_prompt: 'blurry',
  steps: 20,
  width: 768,
  height: 768,
  seed: 12345
};

fetch(API_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(params)
})
  .then(res => res.json())
  .then(data => console.log(data));

Implementation Details

• Parameters are stored in the client state persistence service, using keys prefixed with recall_
• The parameters are associated with a queue_id, allowing multiple concurrent sessions to maintain separate parameter sets
• Only non-null parameters are processed and stored
• The endpoint provides validation for numeric ranges (e.g., steps ≥ 1, dimensions ≥ 64)
• All parameter values are JSON-serialized for storage
• When parameter values are changed, the backend generates a web sockets event that the frontend listens to.

Integration with Frontend

The stored parameters can be accessed by the frontend through the existing client state API or by implementing hooks that read from the recall parameter storage. This allows external applications to pre-populate generation parameters before the user initiates image generation.

Error Handling

• 400 Bad Request: Invalid parameters or parameter values
• 500 Internal Server Error: Server-side error storing or retrieving parameters

Errors include detailed messages explaining what went wrong.