GhostfeedGhostfeed MCPv8.2.0
MCP docs

Generations

Track image and video work by its returned generation ID, inspect exact saved prompts and references, and retrieve prior settings for reuse.

get_generation

READ

REST: GET /api/v2/generations/:id

Check on an ASYNCHRONOUS generation you started, by its gen_ id: its normalized state and the finished asset urls once it succeeds. Poll until state is terminal (succeeded/failed/canceled); slideshow generations typically take 1-3 minutes. Avatars are created synchronously by create_avatar and are NOT polled here.

Input schema
{
  "type": "object",
  "properties": {
    "generationId": {
      "type": "string",
      "description": "The gen_ id returned when the generation was started."
    },
    "workspace": {
      "description": "Target workspace: a slug, id, or exact name from list_workspaces. Omit to use this connection's default workspace. Must be inside the credential's grant and your current access; overrides the connection-level X-Workspace-Id header.",
      "type": "string"
    }
  },
  "required": [
    "generationId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
Example response
{
  "success": true,
  "data": {
    "id": "gen_a1b2c3d4e5f64789a1b2c3d4e5f6",
    "kind": "slideshow_variant",
    "state": "succeeded",
    "phase": "compositing",
    "title": "5 Morning Habits That Changed My Skin",
    "input": {
      "mode": "prompt",
      "prompt": "5 morning habits for glowing skin, aimed at women 20-30",
      "slideCount": 6,
      "projectId": "64f1c2a1b2c3d4e5f6072000",
      "workspaceSlug": "client-a"
    },
    "outputs": [
      {
        "type": "slideshow",
        "url": "https://ghostfeed.ai/w/client-a/slideshows/64f1c2a1b2c3d4e5f6072000?ref=agent"
      }
    ],
    "dashboardUrl": "https://ghostfeed.ai/w/client-a/slideshows/64f1c2a1b2c3d4e5f6072000?ref=agent",
    "creditsSpent": 1,
    "createdAt": "2026-07-18T11:40:00.000Z",
    "updatedAt": "2026-07-18T11:42:30.000Z"
  }
}

list_generations

READ

REST: GET /api/v2/generations

List recent ASYNC agent jobs in the active workspace for polling and operational status, newest first. This ledger is not the product media library and must never be used to decide which content exists. Avatar creation is synchronous and never appears. Optionally filter by kind or state. Use show_generations when the user wants the real visual product library. To SHOW these results in an MCP Apps host, ALWAYS call render_generation_gallery; never hand-build the presentation in chat (no markdown galleries, embedded thumbnails, numbered image lists, or artifacts), even after a widget error. Outside an Apps host, describe items in text and share the dashboard link.

Input schema
{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "avatar_image",
        "slideshow_variant",
        "reaction_import",
        "reaction_crop",
        "reaction_smart_crop",
        "reaction_frame",
        "reaction_video"
      ]
    },
    "state": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "succeeded",
        "failed",
        "needs_action",
        "canceled"
      ]
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Per page (max 40; lower than other tools because these rows carry their full input and outputs).",
      "type": "integer",
      "minimum": 1,
      "maximum": 40
    },
    "workspace": {
      "description": "Target workspace: a slug, id, or exact name from list_workspaces. Omit to use this connection's default workspace. Must be inside the credential's grant and your current access; overrides the connection-level X-Workspace-Id header.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}
Example response
{
  "success": true,
  "data": {
    "workspace": {
      "id": "6a18c36ee586c7e44e4ece67",
      "name": "Client A",
      "slug": "client-a"
    },
    "generations": [
      {
        "id": "gen_a1b2c3d4e5f64789a1b2c3d4e5f6",
        "kind": "slideshow_variant",
        "state": "running",
        "phase": "casting_images",
        "title": "5 Morning Habits That Changed My Skin",
        "input": {
          "mode": "prompt",
          "prompt": "5 morning habits for glowing skin",
          "projectId": "64f1c2a1b2c3d4e5f6072000"
        },
        "outputs": [],
        "dashboardUrl": "https://ghostfeed.ai/w/client-a/slideshows/64f1c2a1b2c3d4e5f6072000?ref=agent",
        "createdAt": "2026-07-18T11:40:00.000Z",
        "updatedAt": "2026-07-18T11:41:00.000Z"
      },
      {
        "id": "gen_b2c3d4e5f60789a1b2c3d4e5f601",
        "kind": "avatar_image",
        "state": "succeeded",
        "input": {
          "traits": {
            "gender": "Female",
            "ageBand": "20s"
          },
          "count": 2
        },
        "outputs": [
          {
            "type": "image",
            "url": "https://cdn.ghostfeed.ai/avatars/64f1/v1.png"
          }
        ],
        "creditsSpent": 2,
        "createdAt": "2026-07-18T09:12:00.000Z",
        "updatedAt": "2026-07-18T09:12:45.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "pages": 1
  }
}

get_prompt_template

READ

REST: GET /api/v2/prompt-templates/:templateId

Read one versioned image default or guided-video system template. Image defaults and Wan 3 Video Guided select their matching templates automatically; other guided templates require an explicit systemPrompt. Inspect a submitted generation with get_generation_prompt.

Input schema
{
  "type": "object",
  "properties": {
    "templateId": {
      "type": "string",
      "enum": [
        "avatar-clone",
        "avatar-product-clone",
        "image-edit",
        "h3-audio-guided",
        "h3-video-guided",
        "wan3-audio-guided",
        "wan3-video-guided"
      ],
      "description": "Named image default or guided-video system template. Wan 3 Video Guided selects wan3-video-guided automatically; other guided templates are available for explicit use."
    }
  },
  "required": [
    "templateId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
Example response
{
  "success": true,
  "data": {
    "templateId": "image-edit",
    "version": "sha256-content-version",
    "systemPrompt": "Edit the provided image while preserving unrequested details.",
    "nextSteps": "Pass systemPrompt to replace the default for one generation."
  }
}

get_generation_prompt

READ

REST: GET /api/v2/generations/:id/prompt

Inspect the actual saved system, user, and compiled provider prompts of a public generation. Returns unavailable fields honestly for older records; never substitutes today’s defaults. Use get_prompt_template only when you want the current default.

Input schema
{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Target workspace: a slug, id, or exact name from list_workspaces. Omit to use this connection's default workspace. Must be inside the credential's grant and your current access; overrides the connection-level X-Workspace-Id header.",
      "type": "string"
    },
    "generationId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "The public gen_ ID returned by generation, not a video or image ID."
    }
  },
  "required": [
    "generationId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
Example response
{
  "success": true,
  "data": {
    "generationId": "gen_example",
    "kind": "image",
    "fidelity": "exact",
    "unavailableFields": [],
    "prompt": {
      "systemPrompt": null,
      "userPrompt": "A red ceramic cup on a white table.",
      "compiledProviderPrompt": "A red ceramic cup on a white table.",
      "promptProvenance": {
        "operation": "generate_image",
        "source": "user"
      }
    }
  }
}

get_generation_setup

READ

REST: GET /api/v2/generations/:id/setup

Read saved nonbilling generation settings, ordered references and prompts for reuse or debugging. Exact saved snapshots are distinguished from incomplete legacy history. Reuse reauthorizes assets and requires a new idempotency key for new work; this read does not generate anything.

Input schema
{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Target workspace: a slug, id, or exact name from list_workspaces. Omit to use this connection's default workspace. Must be inside the credential's grant and your current access; overrides the connection-level X-Workspace-Id header.",
      "type": "string"
    },
    "generationId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "The public gen_ ID returned by generation, not a video or image ID."
    }
  },
  "required": [
    "generationId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
Example response
{
  "success": true,
  "data": {
    "generationId": "gen_example",
    "kind": "video",
    "fidelity": "partial",
    "prompt": null,
    "setup": null,
    "unavailableFields": [
      "systemPrompt",
      "userPrompt",
      "compiledProviderPrompt",
      "setup"
    ],
    "reason": "This legacy generation did not save an immutable prompt/setup snapshot."
  }
}

get_image

READ

REST: GET /api/v2/images/:imageId

Read one accessible generated/source frame or completed image upload, including saved prompt provenance and lineage when available. Choose source upload for a mediaId. Use get_generation_prompt for an in-flight generation’s prompt.

Input schema
{
  "type": "object",
  "properties": {
    "workspace": {
      "description": "Target workspace: a slug, id, or exact name from list_workspaces. Omit to use this connection's default workspace. Must be inside the credential's grant and your current access; overrides the connection-level X-Workspace-Id header.",
      "type": "string"
    },
    "imageId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "A frameId, or a completed image mediaId when source is upload."
    },
    "source": {
      "default": "frame",
      "type": "string",
      "enum": [
        "frame",
        "upload"
      ]
    }
  },
  "required": [
    "imageId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}
Example response
{
  "success": true,
  "data": {
    "image": {
      "imageId": "frame_example",
      "source": "frame",
      "imageUrl": "https://media.ghostfeed.ai/example.png",
      "model": "gemini_flash",
      "origin": "generated",
      "prompt": {
        "systemPrompt": null,
        "userPrompt": "A red ceramic cup.",
        "compiledProviderPrompt": "A red ceramic cup."
      },
      "lineage": {},
      "unavailableFields": []
    }
  }
}
UGC ReactionsPreviousInstallNext

On this page

get_generationlist_generationsget_prompt_templateget_generation_promptget_generation_setupget_image