PlotParty APIv1https://plotparty.ai/mcp/api/v1

REST API · V1

Generate images and video with one HTTP request

Every capability is a tool behind a single endpoint shape: POST /tools/{tool_name}. The request body is the tool's arguments; the response is a uniform JSON envelope. This page covers the 7 essential endpoints: health & balance checks, model parameter lookup, image / video job submission, result polling and history.

BASE URLhttps://plotparty.ai/mcp/api/v1

Quickstart

Check the service, discover a model and its parameters, submit a job, then poll for the result.

# 1. Health check
curl -X POST https://plotparty.ai/mcp/api/v1/tools/health \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" -d '{}'

# 2. See available models and their parameters
curl -X POST https://plotparty.ai/mcp/api/v1/tools/models_explore \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"action": "list", "category": "image"}'

# 3. Submit an image generation job
curl -X POST https://plotparty.ai/mcp/api/v1/tools/generate_image \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "model_id": "gemini-3.1-flash-image",
  "prompt": "A rainy neon street, cinematic wide shot"
}'
# → {"ok": true, "data": {"task_id": "…", "status": "processing", "credits_charged": 2}}

# 4. Poll the result
curl -X POST https://plotparty.ai/mcp/api/v1/tools/get_tool_result \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "<task_id>"}'

Authentication

Every /api/v1/* request requires an Authorization: Bearer <token> header. The same token works for the MCP server and this REST API.

To get a token: sign in at plotparty.ai, open the account menu (your avatar, top right), choose API & MCP Token, then Generate token. Copy it immediately — it is shown only once, and the dialog displays its expiry time. Generate a new one when it expires. Keep tokens private: they spend your PlotParty credits.

Conventions

Response envelope

Success responses are always {"ok": true, "data": …}; errors are {"ok": false, "error": "…", "message": "…"}.

Status	error	Meaning
400	invalid_json / invalid_arguments	Body is not a JSON object, or argument validation failed
401	invalid_token / unauthenticated	Missing or invalid Bearer token
404	unknown_tool	Unknown tool name — see GET /tools for the full list
500	tool_error / tool_execution_error	Tool execution failed; message has the cause
501	unsupported_result	The tool returned an interactive result that cannot map to a single REST call

Async task pattern

Generation endpoints (generate_*) submit an asynchronous job: credits are charged up front and a task_id is returned. By default the call waits briefly for the final result; pass wait_for_result: false to return immediately and poll with get_tool_result. For batches, submit everything with wait_for_result: false and poll — total wall time is roughly one generation. Failed generations are automatically refunded.

Model parameters are discoverable

The full list of supported models and their parameters is documented in Supported Models below. Because models change over time, the live source of truth is the API itself: use models_explore to list models (action="list") and to fetch one model's full parameter spec (action="get"): every parameter with its type, allowed options, default, and only_when conditions. Pass what you learn to generate_image / generate_video via their parameters object — values are validated against the model spec before submission.

Endpoint index

GET/api/v1/tools

Returns every tool with its input_schema / output_schema (JSON Schema). The parameter tables below are generated from it.

SYS

Basics

2 endpoints

POST/api/v1/tools/healthSYS · 01

Return a minimal health payload.

This endpoint takes no parameters — send {} as the request body.

curl -X POST https://plotparty.ai/mcp/api/v1/tools/health \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{ "ok": true, "data": { "status": "ok" } }

POST/api/v1/tools/get_account_balanceSYS · 02

Get the signed-in PlotParty account's available credit balance.

This endpoint takes no parameters — send {} as the request body.

curl -X POST https://plotparty.ai/mcp/api/v1/tools/get_account_balance \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "ok": true,
  "data": { "user_id": "…", "balance": 1280, "currency": "credits" }
}

MDL

Models & Parameters

1 endpoint

POST/api/v1/tools/models_exploreMDL · 01

Explore PlotParty generation models and their parameters.

Parameter	Type	Required	Default	Description
action	string	optional	"list"	`"list"` or `"get"`.
model_id	string	optional	null	Required when `action="get"`.
category	string	optional	null	Optional filter for `action="list"` — `image` \| `audio` \| `video`.
limit	integer	optional	50	Max models to return for `action="list"` (default 50).

curl -X POST https://plotparty.ai/mcp/api/v1/tools/models_explore \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "get",
  "model_id": "gemini-3.1-flash-image"
}'

Response · action="list"

{
  "ok": true,
  "data": {
    "action": "list",
    "total": 16,
    "returned": 16,
    "categories": {
      "image": [
        {
          "model_id": "gemini-3.1-flash-image",
          "display_name": "Nano Banana 2",
          "category": "image",
          "model_type": "text_to_image",
          "estimated_seconds": 18,
          "parameter_names": ["prompt", "aspect_ratio", "resolution", "image_urls"]
        }
      ],
      "video": [
        {
          "model_id": "seedance",
          "display_name": "Seedance 2.0 (omni)",
          "category": "video",
          "model_type": "image_to_video",
          "estimated_seconds": 330,
          "parameter_names": ["prompt", "mode", "duration", "aspect_ratio", "resolution", "…"]
        }
      ]
    }
  }
}

Response · action="get" — the full parameter spec

{
  "ok": true,
  "data": {
    "action": "get",
    "model": {
      "model_id": "gemini-3.1-flash-image",
      "display_name": "Nano Banana 2",
      "category": "image",
      "model_type": "text_to_image",
      "estimated_seconds": 18,
      "parameters": [
        { "name": "prompt", "type": "string", "required": true, "maxLength": 4000 },
        {
          "name": "aspect_ratio",
          "type": "enum",
          "options": ["1:1", "2:3", "3:2", "4:5", "9:16", "16:9", "21:9", "…"],
          "default": "16:9"
        },
        {
          "name": "resolution",
          "type": "enum",
          "options": ["512", "1K", "2K", "4K"],
          "default": "2K"
        },
        {
          "name": "image_urls",
          "type": "array",
          "items": "string",
          "description": "storage_path/URL(s) from upload_media",
          "max": 8
        }
      ]
    }
  }
}

CAT

Supported Models

14 models

The full catalog of models you can pass as model_id, with every model-specific parameter, its allowed values and defaults. Top-level arguments like prompt and aspect_ratio go directly in the request body; the remaining model-specific keys go in the parameters object of generate_image / generate_video. Parameters marked only when must be sent only if the referenced parameter has that value. The live source of truth is models_explore.

Image Models

5 models

Bytedance Seedream v5

text_to_image~15s

MODEL_ID bytedance/seedream/v5/pro/edit

Parameter	Type	Required	Allowed values	Default	Description
prompt	string	required	—	—	—
image_size	enum	optional	square_hd · square · portrait_4_3 · portrait_16_9 · landscape_4_3 · landscape_16_9 · auto_1K · auto_2K	"auto_2K"	—
image_urls	string[]	optional	≤ 8 items	—	storage_path/URL(s) from upload_media

Gemini 2.5 Flash Image

text_to_image~12s

MODEL_ID gemini-2.5-flash-image

Parameter	Type	Required	Allowed values	Default	Description
prompt	string	required	—	—	—
aspect_ratio	enum	optional	16:9 · 9:16 · 4:3 · 3:4 · 1:1 · 3:2 · 2:3 · 4:5 · 5:4 · 21:9	"16:9"	—
image_urls	string[]	optional	≤ 3 items	—	storage_path/URL(s) from upload_media

GPT Image 2

text_to_image~55s

MODEL_ID gpt-image-2

Parameter	Type	Required	Allowed values	Default	Description
prompt	string	required	—	—	—
size	enum	optional	1024x1024 · 1536x1024 · 1024x1536 · 2048x2048 · 2048x1152 · 3840x2160 · 2160x3840 · auto	"auto"	—
quality	enum	optional	high · medium · low · auto	"high"	—
image_urls	string[]	optional	≤ 4 items	—	storage_path/URL(s) from upload_media

Nano Banana 2

text_to_image~18s

MODEL_ID gemini-3.1-flash-image

Parameter	Type	Required	Allowed values	Default	Description
prompt	string	required	≤ 4000 chars	—	—
aspect_ratio	enum	optional	1:1 · 1:4 · 1:8 · 2:3 · 3:2 · 3:4 · 4:1 · 4:3 · 4:5 · 5:4 · 8:1 · 9:16 · 16:9 · 21:9	"16:9"	—
resolution	enum	optional	512 · 1K · 2K · 4K	"2K"	—
image_urls	string[]	optional	≤ 8 items	—	storage_path/URL(s) from upload_media

Gemini 3 Pro Image

text_to_image~25s

MODEL_ID gemini-3-pro-image

Parameter	Type	Required	Allowed values	Default	Description
prompt	string	required	≤ 4000 chars	—	—
aspect_ratio	enum	optional	16:9 · 9:16 · 4:3 · 3:4 · 1:1 · 3:2 · 2:3 · 4:5 · 5:4 · 21:9	"16:9"	—
image_urls	string[]	optional	≤ 8 items	—	storage_path/URL(s) from upload_media

Video Models

9 models

Gemini Omni Flash

image_to_video~300s

MODEL_ID gemini-omni-flash-preview

Parameter	Type	Required	Allowed values	Default	Description
prompt	string	required	—	—	—
aspect_ratio	enum	optional	16:9 · 9:16	"16:9"	—
image_urls	string[]	optional	≤ 6 items	—	storage_path/URL(s) from upload_media

Kling 2.5 pro

image_to_video~300s

MODEL_ID fal-ai/kling-video/v2.5-turbo/pro/image-to-video

Parameter	Type	Required	Allowed values	Default	Description
prompt	string	optional	≤ 2000 chars	—	—
negative_prompt	string	optional	—	"blur, distort, and low quality"	—
duration	enum	optional	5 · 10	5	—
cfg_scale	number	optional	min 0 · max 1 · step 0.1	0.5	—
image_url	string	required	—	—	Start frame — storage_path/URL from upload_media
tail_image_url	string	optional	—	—	Optional end frame — storage_path/URL from upload_media

Kling 3.0 pro

image_to_video~330s

MODEL_ID fal-ai/kling-video/v3/pro/image-to-video

Parameter	Type	Required	Allowed values	Default	Description
prompt	string	optional	≤ 2000 chars	—	—
negative_prompt	string	optional	—	"blur, distort, low quality, text, watermark, labels, words, letters"	—
duration	enum	optional	3 · 4 · 5 · 6 · 7 · 8 · 9 · 10 · 11 · 12 · 13 · 14 · 15	5	—
generate_audio	boolean	optional	—	false	—
aspect_ratio	enum	optional	16:9 · 9:16 · 1:1	"16:9"	—
cfg_scale	number	optional	min 0 · max 1 · step 0.1	0.5	—
start_image_url	string	required	—	—	Start frame — storage_path/URL from upload_media
end_image_url	string	optional	—	—	Optional end frame — storage_path/URL from upload_media
elements	object[]	optional	≤ 3 items	—	Optional character/reference consistency elements (max 3). Each item: frontal_image_url (string), reference_image_urls (array of strings), video_url (optional string, overrides image refs for motion)

Server-injected fixed values (not overridable): shot_type="customize" · multi_prompt=[]

Seedance 2.0 Fast(omni)

image_to_video~270s

MODEL_ID seedance-fast

Parameter	Type	Required	Allowed values	Default	Description
prompt	string	optional	≤ 5000 chars	—	—
mode	enum	required	first_frame · first_last_frame · omni	"omni"	Use omni by default. Choose omni for video continuation, multiple input images, storyboards, reference images, or when you are unsure. Use first_frame only for a single starting image. Use first_last_frame only when exactly one first frame and one last frame are provided.
duration	enum	optional	4 · 5 · 6 · 7 · 8 · 9 · 10 · 11 · 12 · 13 · 14 · 15	5	—
ratio	enum	optional	adaptive · 16:9 · 9:16 · 4:3 · 3:4	"adaptive"	—
resolution	enum	optional	480p · 720p	"720p"	—
first_frame	string[]	required	≤ 1 items	—	Single starting image from upload_media. Only use with mode=first_frame or mode=first_last_frame. For video continuation or multiple images, use mode=omni and put all images in reference_urls instead.only when mode = first_frame \| first_last_frame
last_frame	string[]	required	≤ 1 items	—	Single ending image from upload_media. Only use with mode=first_last_frame together with first_frame. Do not use for multiple references or continuation; use mode=omni reference_urls instead.only when mode = first_last_frame
reference_urls	string[]	required	≤ 12 items	—	Preferred input for Seedance. storage_path/URL(s) from upload_media. Use this with mode=omni for video continuation, multiple images, character/style references, storyboard/keyframes, or any case with more than one image.only when mode = omni

Happy horse

image_to_video~300s

MODEL_ID alibaba/happy-horse/text-to-video

Parameter	Type	Required	Allowed values	Default	Description
prompt	string	required	≤ 2500 chars	—	—
duration	enum	optional	3 · 4 · 5 · 6 · 7 · 8 · 9 · 10 · 11 · 12 · 13 · 14 · 15	5	—
aspect_ratio	enum	optional	16:9 · 9:16 · 1:1 · 4:3 · 3:4	"16:9"	—
resolution	enum	optional	720p · 1080p	"720p"	—
image_urls	string[]	optional	≤ 9 items	—	storage_path/URL(s) from upload_media

Kling 3.0 pro turbo

image_to_video~300s

MODEL_ID fal-ai/kling-video/v3/turbo/pro/image-to-video

Parameter	Type	Required	Allowed values	Default	Description
prompt	string	optional	≤ 2000 chars	—	—
duration	enum	optional	3 · 4 · 5 · 6 · 7 · 8 · 9 · 10 · 11 · 12 · 13 · 14 · 15	5	—
aspect_ratio	enum	optional	16:9 · 9:16 · 1:1	"16:9"	—
image_url	string	required	—	—	Start frame — storage_path/URL from upload_media

Server-injected fixed values (not overridable): multi_prompt=[]

Seedance 2.0 (omni)

image_to_video~330s

MODEL_ID seedance

Parameter	Type	Required	Allowed values	Default	Description
prompt	string	optional	≤ 5000 chars	—	—
mode	enum	required	first_frame · first_last_frame · omni	"omni"	Use omni by default. Choose omni for video continuation, multiple input images, storyboards, reference images, or when you are unsure. Use first_frame only for a single starting image. Use first_last_frame only when exactly one first frame and one last frame are provided.
duration	enum	optional	4 · 5 · 6 · 7 · 8 · 9 · 10 · 11 · 12 · 13 · 14 · 15	5	—
aspect_ratio	enum	optional	adaptive · 16:9 · 9:16 · 4:3 · 3:4	"adaptive"	—
resolution	enum	optional	480p · 720p · 1080p · 4K	"720p"	—
first_frame	string[]	required	≤ 1 items	—	Single starting image from upload_media. Only use with mode=first_frame or mode=first_last_frame. For video continuation or multiple images, use mode=omni and put all images in reference_urls instead.only when mode = first_frame \| first_last_frame
last_frame	string[]	required	≤ 1 items	—	Single ending image from upload_media. Only use with mode=first_last_frame together with first_frame. Do not use for multiple references or continuation; use mode=omni reference_urls instead.only when mode = first_last_frame
reference_urls	string[]	required	≤ 12 items	—	Preferred input for Seedance. storage_path/URL(s) from upload_media. Use this with mode=omni for video continuation, multiple images, character/style references, storyboard/keyframes, or any case with more than one image.only when mode = omni

Seedance 2.5 (omni)

image_to_video~330s

MODEL_ID seedance-2.5

Parameter	Type	Required	Allowed values	Default	Description
prompt	string	required	≤ 10000 chars	—	Mention any reference as @Reference1, @Reference2, ... in reference_urls order. Mentions of well-known IP will be blocked.
mode	enum	required	omni · first_last_frame · extend · edit	"omni"	Use omni by default: text-to-video plus optional image/video/audio references. Use first_last_frame only when exactly one first frame and one last frame are provided. Use extend to continue from a source video. Use edit to edit a source video; the output inherits the source video's duration.
duration	number	optional	min 4 · max 30 · step 1	5	Video length in seconds (4-30). Ignored for mode=edit, which inherits the source video's duration.only when mode = omni \| extend \| first_last_frame
ratio	enum	optional	adaptive · 16:9 · 9:16	"adaptive"	—only when mode = omni
resolution	enum	optional	480p · 720p · 1080p	"480p"	—
first_frame	string[]	required	≤ 1 items	—	Single starting image from upload_media. Only use with mode=first_last_frame together with last_frame. For references, use mode=omni and reference_urls instead.only when mode = first_last_frame
last_frame	string[]	required	≤ 1 items	—	Single ending image from upload_media. Only use with mode=first_last_frame together with first_frame.only when mode = first_last_frame
reference_urls	string[]	required	≤ 50 items	—	storage_path/URL(s) from upload_media. mode=omni: up to 30 images, 10 videos and 10 audio files (50 total; audio cannot be the only reference). mode=edit/extend: must include at least one source video (4s or longer, max 30s); images can be added as extra references. Mention each item in the prompt as @Reference1, @Reference2, ...only when mode = omni \| edit \| extend

Seedance 2.0 Mini

image_to_video~300s

MODEL_ID seedance-mini

Parameter	Type	Required	Allowed values	Default	Description
prompt	string	optional	≤ 5000 chars	—	—
mode	enum	required	first_frame · first_last_frame · omni	"omni"	Use omni by default. Choose omni for video continuation, multiple input images, storyboards, reference images, or when you are unsure. Use first_frame only for a single starting image. Use first_last_frame only when exactly one first frame and one last frame are provided.
duration	enum	optional	4 · 5 · 6 · 7 · 8 · 9 · 10 · 11 · 12 · 13 · 14 · 15	5	—
ratio	enum	optional	adaptive · 16:9 · 9:16 · 4:3 · 3:4	"adaptive"	—
resolution	enum	optional	480p · 720p	"720p"	—
first_frame	string[]	required	≤ 1 items	—	Single starting image from upload_media. Only use with mode=first_frame or mode=first_last_frame. For video continuation or multiple images, use mode=omni and put all images in reference_urls instead.only when mode = first_frame \| first_last_frame
last_frame	string[]	required	≤ 1 items	—	Single ending image from upload_media. Only use with mode=first_last_frame together with first_frame. Do not use for multiple references or continuation; use mode=omni reference_urls instead.only when mode = first_last_frame
reference_urls	string[]	required	≤ 12 items	—	Preferred input for Seedance. storage_path/URL(s) from upload_media. Use this with mode=omni for video continuation, multiple images, character/style references, storyboard/keyframes, or any case with more than one image.only when mode = omni

IMG

Image Generation

1 endpoint

POST/api/v1/tools/generate_imageIMG · 01

Submit an image generation job for the signed-in PlotParty user.

Parameter	Type	Required	Default	Description
model_id	string	required	—	The generation model to use. Must be an image model that PlotParty currently supports — call `models_explore` (action='list') to see valid options (e.g. `gemini-3.1-flash-image`, `gpt-image-2`, `bytedance/seedream/v5/pro/edit`).
prompt	string	required	—	Text description of the image to generate.
image_urls	string[]	optional	null	Optional reference/source images used for image editing or style reference, as a list of either public `http(s)` URLs or `storage_path` values returned by `upload_media`. For a local file or base64 image, call `upload_media` first and pass its `storage_path` here. Leave empty for pure text-to-image.
aspect_ratio	string	optional	null	Optional aspect ratio, e.g. `"16:9"`, `"1:1"`, `"9:16"`.
parameters	object	optional	null	Optional model-specific parameters (e.g. `image_size`, `size`, `quality`, `resolution`). Call `models_explore` (action='get', model_id=...) to see the exact keys and allowed enum values for this model. Values are validated against the model spec before submission.
wait_for_result	boolean	optional	true	Whether to wait briefly for the final result before returning. Defaults to true for a Claude-style generating card.
wait_seconds	number	optional	null	Optional per-call wait budget. Capped by the server.

curl -X POST https://plotparty.ai/mcp/api/v1/tools/generate_image \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "model_id": "gemini-3.1-flash-image",
  "prompt": "A rainy neon street, cinematic wide shot",
  "aspect_ratio": "16:9",
  "parameters": { "resolution": "2K" }
}'

Response — job accepted

{
  "ok": true,
  "data": {
    "task_id": "9f2c1e6a-…",
    "status": "processing",
    "model_id": "gemini-3.1-flash-image",
    "credits_charged": 2
  }
}

VID

Video Generation

1 endpoint

POST/api/v1/tools/generate_videoVID · 01

Submit a video generation job for the signed-in PlotParty user.

Parameter	Type	Required	Default	Description
model_id	string	required	—	The video model to use. Call `models_explore` (action="list", category="video") to see valid options (e.g. `seedance`, `fal-ai/kling-video/v3/pro/image-to-video`).
prompt	string	required	—	Text description of the video to generate.
aspect_ratio	string	optional	null	Optional aspect ratio, e.g. `"16:9"`, `"1:1"`, `"9:16"`.
duration	integer	optional	null	Optional clip length in seconds. Allowed values depend on the model — check `models_explore`.
image_url	string	optional	null	Optional single source image (public URL or `storage_path` from `upload_media`) for image-to-video.
image_urls	string[]	optional	null	Optional source images, as public URLs or `storage_path` values from `upload_media`.
mode	string	optional	null	Model-specific generation mode (e.g. `first_frame`, `first_last_frame`, `omni` for Seedance).
ratio	string	optional	null	Model-specific ratio field; prefer `aspect_ratio` unless the model spec says otherwise.
resolution	string	optional	null	Optional output resolution, e.g. `"720p"`, `"1080p"`. Allowed values depend on the model.
cfg_scale	number	optional	null	Model-specific guidance scale, when the model supports it.
generate_audio	boolean	optional	null	Whether the model should also generate audio, when supported.
first_frame	string[]	optional	null	Single starting image. Only for models/modes that take a first frame (see the model spec's `only_when`).
last_frame	string[]	optional	null	Single ending image. Only for first-and-last-frame modes (see the model spec's `only_when`).
reference_urls	string[]	optional	null	Reference images for reference-driven modes (e.g. Seedance `omni`).
references	string[]	optional	null	Alias for reference inputs on models that use this key.
parameters	object	optional	null	Optional model-specific parameters (e.g. `image_size`, `size`, `quality`, `resolution`). Call `models_explore` (action='get', model_id=...) to see the exact keys and allowed enum values for this model. Values are validated against the model spec before submission.
extra	object	optional	null	Additional provider-specific fields, passed through as-is.
wait_for_result	boolean	optional	false	Whether to wait briefly for the final result before returning. Defaults to true for a Claude-style generating card.
wait_seconds	number	optional	null	Optional per-call wait budget. Capped by the server.

curl -X POST https://plotparty.ai/mcp/api/v1/tools/generate_video \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "model_id": "seedance",
  "prompt": "Slow dolly-in on a lighthouse at dusk, waves crashing",
  "duration": 5,
  "resolution": "720p",
  "wait_for_result": false
}'

Response — job accepted

{
  "ok": true,
  "data": {
    "task_id": "b41d7c02-…",
    "status": "processing",
    "model_id": "seedance",
    "credits_charged": 20
  }
}

TSK

Results & History

2 endpoints

POST/api/v1/tools/get_tool_resultTSK · 01

Display one generation task by the MCP `task_id`.

Parameter	Type	Required	Default	Description
task_id	string	required	—	The `task_id` returned by `generate_image` / `generate_video`.

curl -X POST https://plotparty.ai/mcp/api/v1/tools/get_tool_result \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "task_id": "<task_id>"
}'

Response — still generating

{
  "ok": true,
  "data": {
    "task_id": "9f2c1e6a-…",
    "source_tool": "generate_image",
    "status": "processing",
    "result": {},
    "hint": "Still generating — call get_tool_result again with this task_id."
  }
}

Response — success (signed media URLs)

{
  "ok": true,
  "data": {
    "task_id": "9f2c1e6a-…",
    "source_tool": "generate_image",
    "status": "success",
    "images": [
      {
        "url": "https://storage.googleapis.com/…(signed, expiring)",
        "storage_path": "<user_id>/image/….png",
        "permalink": "https://…/mcp/media?path=…&token=…"
      }
    ]
  }
}

POST/api/v1/tools/fetch_historyTSK · 02

Fetch the signed-in user's successfully completed generation prompts.

Parameter	Type	Required	Default	Description
page	integer	optional	1	Page number, starting at 1. Results are newest first.
page_size	integer	optional	20	Items per page (max 100).
media_type	"image" \| "audio" \| "video"	optional	null	Optional filter: `image`, `audio`, or `video`.

curl -X POST https://plotparty.ai/mcp/api/v1/tools/fetch_history \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "page": 1,
  "page_size": 20,
  "media_type": "image"
}'

Response

{
  "ok": true,
  "data": {
    "history": [
      {
        "task_id": "9f2c1e6a-…",
        "prompt": "A rainy neon street, cinematic wide shot",
        "source_tool": "generate_image",
        "model_id": "gemini-3.1-flash-image",
        "media_type": "image",
        "status": "success",
        "created_at": "2026-08-30T09:12:44",
        "images": [{ "url": "https://…(signed)" }]
      }
    ],
    "page": 1,
    "page_size": 20,
    "total": 42,
    "has_more": true
  }
}