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 generations in the active workspace, newest first (slideshow creations appear here). Avatar creation is synchronous and never appears. Optionally filter by kind or state.

Query parameters

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "avatar_image",
        "slideshow_variant",
        "reaction_import",
        "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