Browse the Pixio model catalog (550+ models) with optional filters.

Step 1 of the three-call contract for running any generation:

1. list_models — find a model id (filter by type and/or query).

2. get_model_params(model_id) — fetch that model's exact input schema.

3. generate(model_id, params) — run the job.

Args: type: Exact model type to match, e.g. "text-to-image", "image-to-image", "image-to-video", "text-to-video", "video-to-video", "text-to-audio". query: Case-insensitive substring matched against each model's id, name, and description (e.g. "flux", "background removal"). limit: Maximum number of models to return; clamped to 1..200 (default 50). offset: Number of matching models to skip, for pagination (negative values are treated as 0).

Returns: {"models": [{"id", "name", "type", "credits", "company", "description"}, ...], "total_matching": , "returned": <len of "models">, "offset": }. "credits" is the catalog-listed cost per generation; descriptions are truncated to 200 characters. The catalog is cached for ~10 minutes.

Fetch the exact input schema for one Pixio model.

Step 2 of the three-call contract: list_models -> get_model_params -> generate. Build the params object for generate() strictly from this response — the server embeds no per-model knowledge.

Critical gotchas when building params for generate():

• For select-type params the allowed values are options[].value (there is no ".values" array). Send select values as STRINGS even when they look numeric — e.g. "5", not 5.

• Some params marked optional-with-default are still required by the gateway. On your first attempt send EVERY listed param, using each param's defaultValue where you have no better value.

Args: model_id: Catalog model id from list_models, e.g. "pixio/flux-1/schnell".

Returns: The gateway /params response verbatim: {"model": {...}, "params": [{"name", "type", "label", "required", "defaultValue", "placeholder"?, "options"?: [{"value", "label"}]}, ...]}. An unknown model id yields a NOT_FOUND error dict.

Estimate the credit cost of a generation BEFORE spending anything.

Call this after get_model_params and before generate (the three-call contract is list_models -> get_model_params -> generate; this tool is the recommended pre-flight between steps 2 and 3). Costs come from the gateway estimate endpoint when available ("source": "estimate"), else from the catalog-listed per-generation cost ("source": "catalog"), else the cost is reported as unknown.

Args: model_id: Catalog model id, e.g. "pixio/flux-1/schnell". params: The exact params object you intend to pass to generate(), built from the get_model_params response.

Returns: {"model_id": str, "estimated_credits": int | null, "source": "estimate" | "catalog" | "unknown"}, plus a "warning" string only when the cost could not be determined ("estimated_credits" is null and "source" is "unknown").

Upload a local file or mirror a remote URL to Pixio, returning a permanent public media URL.

Use this before generate whenever a model parameter needs media (image_url, video_url, audio_url, ...): generate accepts http(s) URLs only and rejects local filesystem paths. The returned url (hosted on pixiomedia.nyc3.digitaloceanspaces.com) is permanent and publicly readable, and is exactly what generate's media params (e.g. image_url) expect — pass it through verbatim.

Args: source: An http(s) URL (mirrored server-side into Pixio storage) or a local file path (~ is expanded; uploaded as multipart). Directories are rejected.

Returns: {"url": str, "source_kind": "local_file" | "remote_url", "file_name": str, "size_bytes": int | None} — size_bytes is None for remote URLs (the file never transits this machine).

Run a media generation job on Pixio, with spend guardrails.

This is the final step of the 3-call discovery contract: list_models -> get_model_params -> generate. Build params from the live get_model_params(model_id) response — this server embeds no model schemas. On a first attempt send EVERY param the schema lists, at its default value (some params marked optional are actually required by the gateway), and send select-option values as STRINGS (e.g. "5", not 5).

URLs-only contract: every media input inside params must be an http(s) or data: URL. Any value that looks like a local filesystem path (~, ./, ../, file://, X:\, UNC \\, or an existing file) is rejected with a VALIDATION error naming the offending field(s) — before any credits are spent. Call upload_media first and pass the permanent URL it returns.

Spend guardrails: the job cost is estimated up front and refused with BUDGET_EXCEEDED if it exceeds the per-job cap or would exceed the session budget — no credits are spent on a refusal. Pass confirm=true to explicitly override both caps for this one job.

Waiting: with wait=true (default) this call polls until the job is terminal or timeout_s elapses (default: PIXIO_DEFAULT_TIMEOUT_S, 180s). On timeout you get a TIMEOUT_PENDING error whose details carry the generation_id — the job KEEPS RUNNING server-side; resume with wait_for_generation(generation_id). With wait=false the call returns immediately (status "processing", plus estimated_credits); check later with get_generation or wait_for_generation.

Output URLs may be signed and expire after roughly an hour — call download_output(generation_id) promptly.

Args: model_id: Pixio model id, e.g. "pixio/flux-1/schnell". params: Generation inputs built from get_model_params (URLs only for media fields). wait: Poll to completion (True, default) or return immediately. timeout_s: Max seconds to wait when wait=true; None uses the server default. confirm: Set True to override the per-job and session credit caps.

Returns: On success: {"generation_id", "status", "output_urls", "outputs", "model_id", "credits_spent", "remaining_balance", "elapsed_s", "error"}. With wait=false: the same shape with status "processing", credits_spent None, and estimated_credits added. On failure: {"error": {"code", "message", "details"}} with code VALIDATION, BUDGET_EXCEEDED, INSUFFICIENT_CREDITS, CONCURRENCY, GENERATION_FAILED, TIMEOUT_PENDING, NOT_FOUND, AUTH, or UPSTREAM_ERROR. NOTE: success results also contain an "error" key (the provider reason, null on success) — a call failed only when result["error"] is a dict carrying a "code".

Fetch the current status and outputs of one generation (no polling).

A single GET /generations/{id} snapshot. Use this to check on a job started with generate(wait=false) or after a TIMEOUT_PENDING; use wait_for_generation instead if you want to block until it finishes.

Statuses: "processing" -> "succeeded" | "failed". remaining_balance is only fetched (best-effort) once the job is terminal; while processing it is None, as is credits_spent.

Args: generation_id: Id returned by generate.

Returns: {"generation_id", "status", "output_urls", "outputs", "model_id", "credits_spent", "remaining_balance", "elapsed_s", "error"} — error carries the provider reason when status is "failed". On failure: {"error": {"code", "message", "details"}} (e.g. NOT_FOUND for an unknown id).

Block until a generation reaches a terminal status, or time out.

Resumes waiting on any in-flight job — most usefully after generate returned TIMEOUT_PENDING, or for a job started with wait=false. Polls with backoff (2s growing to a 10s cap, jittered) until the job is "succeeded" or "failed", or until timeout_s elapses (default: PIXIO_DEFAULT_TIMEOUT_S, 180s). Budget actuals are reconciled from the job's real creditsCost when it completes.

On timeout the TIMEOUT_PENDING error again carries the generation_id — the job keeps running server-side and this tool can be called as many times as needed.

Args: generation_id: Id returned by generate. timeout_s: Max seconds to wait; None uses the server default.

Returns: On success the job-result shape: {"generation_id", "status", "output_urls", "outputs", "model_id", "credits_spent", "remaining_balance", "elapsed_s", "error"}. On failure: {"error": {"code", "message", "details"}} with code GENERATION_FAILED (details include the provider reason), TIMEOUT_PENDING (details include generation_id and a resume hint), NOT_FOUND, AUTH, or UPSTREAM_ERROR.

Download every output file of a succeeded generation to a local directory.

Call this after generate(wait=true) or wait_for_generation reports status succeeded. Output URLs may be signed and expire (~1 hour), so download promptly. If the generation is still processing this returns a VALIDATION error — call wait_for_generation(generation_id) first and retry once it succeeds. Any non-succeeded status (including failed) returns a VALIDATION error stating the current status; for a failed generation the provider's reason is included in the details.

Args: generation_id: The id returned by generate. dest_dir: Target directory, created if missing (~ is expanded). Defaults to the server's configured download directory (PIXIO_DOWNLOAD_DIR, default ~/pixio-outputs).

Returns: {"generation_id": str, "files": [absolute file paths], "dest_dir": str} — files are named {generation_id[:8]}-{index}{ext} (id prefix sanitized to filesystem-safe characters) with the extension inferred from each URL or the downloaded content.

Report the Pixio account's current credit balance.

Use to check affordability before a job or to audit spend after one. Every terminal generate / wait_for_generation result already includes "remaining_balance", so this tool is mainly for standalone balance checks and recent-spend review.

Args: include_ledger_tail: When true, also return the most recent credit ledger entries (spend and top-up history). ledger_limit: Maximum ledger entries to include (default 10; only used when include_ledger_tail is true; negative values are treated as 0).

Returns: {"total": , "recurring": {"current", "quota", "lastTopOffAt"}, "permanent": }, plus "ledger_tail": [{"id", "reason", "deltaRecurring", "deltaPermanent", "sourceId", "createdAt"}, ...] when include_ledger_tail is true.