Ghostfeed MCPGenerations
Track image and video work by its returned generation ID, inspect exact saved prompts and references, and retrieve prior settings for reuse.
GET /api/v2/generations/:id
READMCP twin: get_generation
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.
Path parameters: id (from the URL).
{
"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#"
}{
"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"
}
}GET /api/v2/generations
READMCP twin: list_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.
{
"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#"
}{
"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 /api/v2/prompt-templates/:templateId
READMCP twin: get_prompt_template
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.
Path parameters: templateId (from the URL).
{
"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#"
}{
"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 /api/v2/generations/:id/prompt
READMCP twin: get_generation_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.
Path parameters: id (from the URL).
{
"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#"
}{
"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 /api/v2/generations/:id/setup
READMCP twin: get_generation_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.
Path parameters: id (from the URL).
{
"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#"
}{
"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 /api/v2/images/:imageId
READMCP twin: get_image
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.
Path parameters: imageId (from the URL).
{
"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#"
}{
"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": []
}
}
}