Generations

Poll asynchronous work (video and future verticals) by gen_ id until its state is terminal.

GET /api/v2/generations/:id

READ

MCP 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).

Query parameters

{
  "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"
  }
}

GET /api/v2/generations

READ

MCP 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.

Query parameters

{
  "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 /api/v2/generations/:id

GET /api/v2/generations

On this page