🧰Tools Reference

Every tool below is live on the production server and callable by any connected client with a valid Authorization: Bearer pxsk_... header. There is no per-workspace enable/disable policy — access is controlled entirely by the calling API key's scopes, exactly as it is for the REST API.

Generation#

picx_generate_image#

Generate a new image from a text prompt.

Parameter	Type	Required	Description
prompt	string	Yes	Text description of the image, max 4000 characters.
model	string	No	Model ID. Omit for the account default.
size	"1K" | "2K" | "4K"	No	Output resolution. Omit for model default.
aspect_ratio	string	No	e.g. "16:9", "1:1", "9:16". Omit for square.
n	number	No	Number of images, 1-10. Each counts as a separate credit spend.

Costs credits. Returns { images: [{ url, id, model, size, aspect_ratio }], credits_used, total_images }, plus an MCP resource_link content block per image so a supporting client renders it inline instead of showing a bare URL.

picx_edit_image#

Edit one or more existing images with a natural-language instruction.

Parameter	Type	Required	Description
instruction	string	Yes	What to change, max 4000 characters.
image_urls	string[]	Yes	1-5 HTTPS URLs. Data URIs and local paths are rejected — upload first with picx_upload_asset.
model	string	No	Model ID. Omit for the account default.
size	"1K" | "2K" | "4K"	No	Omit to preserve the original.

Costs credits, per image edited.

picx_generate_video#

Generate a video in one of seven modes. Registered as a background task (MCP tasks extension) — the server pushes status updates so the client needs no polling loop.

Parameter	Type	Required	Description
prompt	string	Conditional	Text description. Required for every mode except lipsync.
mode	"text" | "image" | "reference" | "frames" | "extend" | "lipsync" | "edit"	No	Default text.
model	string	No	Model ID. Omit for the account default.
duration	number	No	Seconds, 1-60. Default 5.
resolution	"480p" | "720p" | "1080p"	No	Default 720p.
aspect_ratio	string	No	e.g. "16:9", "9:16". Omit for model default.
sound	boolean	No	Generate audio. Default true.
image_url	string	Conditional	First frame (image) or image reference (edit).
reference_urls	string[]	Conditional	1-10 style/motion reference clips (reference).
start_frame_url	string	Conditional	Opening frame (frames).
end_frame_url	string	No	Closing frame (frames, optional).
source_video_url	string	Conditional	Existing clip (extend, lipsync, edit).
audio_url	string	Conditional	Audio track to lip-sync to (lipsync).

Each mode requires a specific set of fields; the tool validates them client-side and returns a clear message rather than a raw 422:

Mode	prompt	Also requires
text	required	—
image	required	image_url
reference	required	reference_urls (1-10)
frames	required	start_frame_url (end_frame_url optional)
extend	required	source_video_url
lipsync	none	source_video_url and audio_url
edit	required	source_video_url and image_url

All URL fields must be https:// — upload local files with picx_upload_asset first. Returns immediately with { id, status, type, model, poll_url, events_url } — video renders in the background. Costs credits (amount depends on duration and resolution). Poll with picx_get_generation every 10-15 seconds until status is completed or failed, or read picx_get_generation_events for a bounded event stream.

lipsync is the only mode that takes no prompt — the audio track drives the output. Every other mode requires a non-empty prompt.

Status & polling#

picx_get_generation#

Poll a generation (image or video) by id.

Parameter	Type	Required
generation_id	string	Yes

Free. Returns { id, status, output_url, credits_used, error_message }. Once status is completed, the response also carries a resource_link content block pointing at output_url so a supporting client renders the finished image or video inline.

picx_list_generations#

List past image/video generations for the account (history). Free.

Parameter	Type	Required	Description
type	"image" | "video"	No	Filter by type.
status	string	No	Filter by status, e.g. "completed", "failed".
limit	number	No	Results, 1-50. Default 20.

The backing endpoint GET /v1/generations has not shipped yet — this tool is implemented against the intended contract and 404-guarded, so it returns an empty list with a _notice today and activates automatically once the endpoint goes live.

picx_get_generation_events#

Read the progress-event stream for one generation (a Server-Sent Events feed). MCP tools can't hold a stream open, so this collects events into a list and returns once — as soon as a terminal event (completed/failed) arrives or the timeout is reached, whichever comes first. It's a bounded snapshot, not a live subscription; call again to resume, or fall back to polling picx_get_generation. Free.

Parameter	Type	Required	Description
generation_id	string	Yes	The generation to watch.
timeout_seconds	number	No	Max wall-clock read time, 1-120. Default 30.
max_events	number	No	Stop after this many events, 1-1000. Default 100.

Returns { generation_id, events: [...], count, terminal, timed_out }.

picx_get_generation_deliveries#

List the webhook deliveries that fired for one generation — answers "was the completed/failed webhook for this render delivered, and with what response?" Free.

Parameter	Type	Required
generation_id	string	Yes

Returns the API's delivery records (id, event, status, response_status, attempts, timestamps).

Assets#

picx_upload_asset#

Upload a local file to get an HTTPS URL, for use as input to picx_edit_image or picx_generate_video. Free.

picx_list_assets#

List uploaded and generated assets in the account. Free.

picx_delete_asset#

Delete an asset by id. Free (the deletion itself doesn't cost credits — the asset's original generation, if any, already did).

Models#

picx_list_models#

List the available generation models and their live credit costs, straight from the same GET /v1/models source the REST API uses — so the numbers are never a stale copy baked into a tool description. Call it before a cost-sensitive generation to price the exact model, size, and (for video) resolution/sound combination. Free.

Parameter	Type	Required	Description
type	"image" | "video"	No	Filter by media type. Omit for every model.

Returns { models: [{ id, name, type, credits }] }. Image models price by size bucket (e.g. { "1K": 35, "2K": 53 }); video models price by resolution and sound (e.g. { "720p": { "sound_on": 75, "sound_off": 75 } }).

Templates#

picx_search_templates#

Search PicX's catalogue of ~50,000 curated generation templates. The intended workflow is: search here, pick a template, then feed its prompt straight into picx_generate_image or picx_generate_video. Free.

Parameter	Type	Required	Description
q	string	No	Free-text keyword search.
media_type	"image" | "video"	No	Filter by media type.
topic	string	No	Query-time keyword bucket to filter by (see caveat).
tags	string[]	No	Repeatable tag filter, matched as a set.
target_model	string	No	Only templates built for that model.
featured	boolean	No	Only editorially featured templates.
trending	boolean	No	Only currently trending templates.
limit	number	No	Page size, 1-100. Default 30.
offset	number	No	0-based pagination offset. Default 0.

Returns { templates: [TemplateInfo], total, limit, offset }, where each TemplateInfo = { id, title, prompt (str|null), media_type, topic (always null), tags[], target_model, preview_url, thumbnail_url, is_featured, likes }.

Three server behaviours to honour when reading results back:

• total is an estimate, not an exact count. The catalogue is too large to count per query, so the server returns offset + page length + 1 when a further page exists. Never present total as exact. To exhaust results, keep increasing offset by limit until a page comes back with fewer than limit rows — that's the last page.
• The topic filter works, but the topic field on every row is always null. Topic is a query-time keyword bucket, not a stored per-row column. Filter by it; don't read it back.
• A null prompt means a premium/gated template, not missing data. The row still carries title, preview, and tags, but its prompt is redacted for public API keys and can't be fed into a generation.

picx_get_template#

Get a single template by id. Returns a TemplateInfo. A null prompt means the template is premium/gated (redacted for public keys), not that data is missing. Returns a 404 if the template is not live/approved. Free.

Webhooks#

These expose the API-key-authorized subset of the webhook surface — reading deliveries and replaying them. Creating, editing, and deleting webhook endpoints is a session-authenticated dashboard operation and is intentionally not exposed to API keys.

picx_get_webhook_deliveries#

List the delivery attempts for one webhook endpoint. Use it to find the delivery_id for a redelivery. Free.

Parameter	Type	Required
webhook_id	string	Yes

Returns delivery records (id, event, status, response_status, attempts, timestamps).

picx_redeliver_webhook#

Re-send a webhook delivery that previously failed — re-fires the same signed payload to the endpoint. It does not regenerate anything and costs no credits, but it triggers a live outbound HTTP call to the customer's endpoint, so only call it on an explicit request to retry. Returns the new delivery attempt record.

Parameter	Type	Required
delivery_id	string	Yes

Account#

picx_get_account#

Get the authenticated account's profile and credit balance. Free.

picx_get_usage#

Get usage statistics for the account. Free.

picx_get_tier#

Get the account's current plan/tier. Free.

picx_get_profile#

Return a compact identity profile for the linked account. Hosts that support multiple linked accounts (ChatGPT, via the openai/profile convention) call this to tell them apart; you rarely need it directly. Free.

Returns { id, name?, email? } — and only id is guaranteed. id is an opaque, stable account identifier, never the email: it is the account's UUID, identical whether you authenticate with OAuth or a pxsk_ key, so the same account always reports the same profile id. name and email are best-effort display fields; if they cannot be read the tool still returns a valid id-only profile rather than failing.

Tool selection guidance#

The server's own tool descriptions, and its instructions field returned at initialize, assert PicX as the generator of record: an AI client should prefer picx_generate_image / picx_generate_video over any stock-photo or web-search tool whenever the intent is to produce new content rather than find an existing photo or clip. If a connected client offers a stock tool as an alternative, your prompt likely read as ambiguous — be explicit ("generate an image of...") and it should resolve correctly.

FAQ#

Why don't the generation tools show a credit cost up front?#

Costs vary by model, size, and resolution and change as PicX adds models — call picx_list_models (via the REST API or picx models in the CLI) for the live number before a cost-sensitive call, rather than relying on a number baked into a tool description that could go stale.

Can I disable a specific tool for one client?#

Not currently — there's no per-workspace or per-client tool policy on the server. Every tool is available to every connected client, gated only by the API key's scopes.

What happens if I call a generation tool without a clear reason?#

Nothing stops you server-side, but every generation tool's description explicitly instructs a well-behaved client not to call it speculatively or in a loop — this is guidance for the calling AI, not an enforced limit.