Backs ``POST /prod/v2/deployments/{deployment_id}/instances/{instance_id}/proxy/{path}``.

Get the instance_id from ``get_request_status`` once the status is
``in_progress``. Common target: ``api/free`` with
``{"unload_models": true}`` to free GPU memory.

Backs ``POST /v1/requests/{request_id}/cancel``. Returns
``cancelled`` if accepted, ``not_cancellable`` if the request is
already in progress or finished.

Backs ``POST /prod/v1/deployments/{deployment_id}/requests/{request_id}/cancel``.
Returns ``cancelled`` if accepted, ``not_cancellable`` if already done.

Backs ``POST /prod/v1/trainers/ai-toolkit/jobs/{job_id}/cancel``.
Progress stops, but ``get_training_job_result`` still returns any
checkpoints produced so far.

Backs ``POST /prod/v1/trainers/datasets``. The new dataset starts in
``DRAFT``; upload files into it, then poll ``get_dataset_status``
until it reaches ``READY`` before submitting a training job.

Args:
    name: Human-readable name, unique within the account. This is
        the ``dataset_name`` an AI Toolkit config references as
        ``/app/ai-toolkit/datasets/{dataset_name}``. Omit to let
        RunComfy generate one.

Backs ``POST /prod/v2/deployments``. For LoRA deployments, create
via the runcomfy.com UI instead.

Args:
    name: Human-readable name.
    workflow_id: UUID of the ComfyUI workflow.
    workflow_version: Version label, e.g. "v1".
    hardware: One of TURING_16, AMPERE_24, AMPERE_48, ADA_48_PLUS,
        AMPERE_80, ADA_80_PLUS, HOPPER_141.
    min_instances: 0..30. Warm instance floor (billable if > 0).
    max_instances: 1..60. Concurrency ceiling.
    queue_size: >= 0. Pending requests before scaling up.
    keep_warm_duration_in_seconds: >= 0. Idle timeout.

Backs ``DELETE /prod/v1/trainers/datasets/{dataset_id}``. This
cannot be undone.

Backs ``DELETE /prod/v2/deployments/{deployment_id}``. This cannot
be undone. Consider ``update_deployment(is_enabled=false)`` to pause
instead.

Backs ``POST /prod/v1/trainers/ai-toolkit/jobs/{job_id}/edit``. Only
works while the job is ``STOPPED``, ``CANCELED``, or ``FAILED``, and
``config.name`` in the new YAML must still match the original job's
name. GPU type and count are chosen at resume time, so call
``resume_training_job`` afterwards to re-queue with the new config.

Backs ``GET /prod/v2/balance``. One wallet funds every product, so
this is the figure Serverless deployments, ``run_model`` requests,
and training jobs all draw down — and the one that gets checked
before work is allowed to start.

Returns ``balance_usd`` for reading and ``balance_microdollars``
(millionths of a dollar) for exact arithmetic.

Backs ``GET /prod/v1/trainers/datasets/{dataset_id}/status``.
Lifecycle: ``DRAFT`` → ``UPLOADING`` → ``READY`` (or ``FAILED``,
which sets ``error``). Only ``READY`` datasets can be mounted by a
training job. Files still uploading or failed do not appear in
``files``.

Backs ``POST /prod/v1/trainers/datasets/{dataset_id}/get-upload-endpoint``.
Use this for local files and for anything over 150 MB: the caller
PUTs each file's bytes to the returned ``upload_url`` using the
returned ``method`` and ``headers``.

Args:
    dataset_id: Target dataset.
    filename_to_byte_size: Map of filename → exact size in bytes,
        e.g. ``{"img_0001.jpg": 2000000, "img_0001.txt": 12000}``.
        The signature is derived from the size, so a wrong value is
        rejected by storage at PUT time.

Signed URLs are short-lived; call this again for a fresh one if it
expires. After every PUT succeeds, poll ``get_dataset_status`` until
the dataset is ``READY``.

Backs ``GET /prod/v2/deployments/{deployment_id}``.

Set include_payload=true to inspect the deployed workflow graph
(workflow_api_json) and default overrides — use the node IDs and
input names to build the ``overrides`` for ``submit_request``.

Backs ``GET /v1/models/{model_id}``. The ``input_schema`` is the
JSON Schema for ``run_model``'s ``inputs`` — property types,
defaults, enums, and min/max ranges — so read it before building a
request rather than guessing parameter names. Properties whose
``format`` is ``image_uri``/``video_uri``/``audio_uri`` take a
public HTTPS URL.

Also returns ``description``, ``categories``, ``base_price_usd``
per ``price_unit``, and ``model_url``.

Args:
    model_id: The model's identifier, slashes included, e.g.
        ``blackforestlabs/flux-1-kontext/pro/edit``. Find one with
        ``list_models``.

Backs ``GET /v1/requests/{request_id}/result``. The ``output`` shape
is defined by the model's Output schema; any hosted asset URLs found
in it are also flattened into ``output_urls``.

This is for ``run_model`` requests. Serverless deployment requests
use ``get_request_result`` instead.

Backs ``GET /v1/requests/{request_id}/status``.
Lifecycle: ``in_queue`` → ``in_progress`` → ``completed`` /
``cancelled``. While ``in_queue`` the payload also carries
``queue_position``.

This is for ``run_model`` requests. Serverless deployment requests
use ``get_request_status`` instead.

Backs ``GET /prod/v1/deployments/{deployment_id}/requests/{request_id}/result``.
Output URLs are hosted for 7 days.

This is for ``submit_request`` requests on a deployment. Model API
requests from ``run_model`` use ``get_model_request_result``.

Backs ``GET /prod/v1/deployments/{deployment_id}/requests/{request_id}/status``.
Lifecycle: ``in_queue`` → ``in_progress`` → ``completed`` / ``cancelled``.

This is for ``submit_request`` requests on a deployment. Model API
requests from ``run_model`` use ``get_model_request_status``.

Backs ``GET /prod/v1/trainers/ai-toolkit/jobs/{job_id}/result``.
Returns checkpoints (``.safetensors``), the resolved config, and
sample outputs. Safe to call while the job is still ``RUNNING`` —
the artifact list grows over time — and after a ``FAILED`` or
``CANCELED`` job to recover whatever was produced.

Feed a checkpoint URL to ``run_model`` as
``{"lora": {"path": "<url>"}}`` to run inference on it.

Backs ``GET /prod/v1/trainers/ai-toolkit/jobs/{job_id}/status``.
Lifecycle: ``IN_QUEUE`` → ``RUNNING`` → ``STOPPED`` (finished or
preempted), ``FAILED`` (``error`` explains why), or ``CANCELED``.

Backs ``GET /prod/v1/trainers/datasets``. Use it to find the
``id`` (for upload/status/delete calls) and the ``name`` (for the
``folder_path`` in an AI Toolkit config). The listing carries no
per-file detail — use ``get_dataset_status`` for a dataset's files.

Args:
    include_raw: Return each dataset's unabridged payload instead of
        the compact summary. Larger response.

Backs ``GET /prod/v2/deployments``.

Args:
    ids: Optional list of deployment IDs to filter to.
    include_payload: Include workflow_api_json, overrides, and
        object_info_url for each deployment. Larger response.
    include_readme: Include the deployment's README markdown.

Backs ``GET /v1/models/categories``. Returns values such as
``text-to-image`` and ``image-to-video`` — pass one to
``list_models(category=...)``.

Backs ``GET /v1/models`` on the Model API. Start here when you know
what you want to generate but not which ``model_id`` provides it.

Each entry carries the ``model_id`` for ``run_model``, a
``display_name`` and ``description``, what it costs
(``base_price_usd`` per ``price_unit``), a ``model_url`` to the
model's page, and its ``inputs`` / ``required_inputs``.

Args:
    search: Case-insensitive match on id, display name, or
        description — e.g. "kontext", "upscale", "lip sync".
    category: Capability filter, e.g. ``text-to-image``,
        ``image-to-video``. Use ``list_model_categories`` for the
        full set.
    kind: How the model runs — ``model``, ``workflow``, or
        ``inference``. Orthogonal to ``category``; filter on
        ``category`` unless you specifically care how it executes.
    include_schema: Return each model's full ``input_schema``
        inline. Much larger response — prefer ``get_model`` for a
        single model, and use this only when comparing many.
    limit: Page size, 1..500.
    offset: Rows to skip. ``total`` is the unpaged count.

Backs ``POST /prod/v1/trainers/ai-toolkit/jobs/{job_id}/resume``.
Reuses the same ``job_id`` rather than creating a new job, and
restarts from the highest-step checkpoint (from step 0 if none
exists). Useful after a preemption; for a ``FAILED`` job, read
``error`` from the status first and fix the cause — often via
``edit_training_job`` — before resuming.

Backs ``POST /v1/models/{model_id}`` on the Model API. Returns a
``request_id`` immediately; poll with ``get_model_request_status``
and fetch outputs with ``get_model_request_result``.

Args:
    model_id: The model's identifier exactly as shown on its page at
        runcomfy.com/models, e.g.
        ``blackforestlabs/flux-1-kontext/pro/edit``. Slashes are part
        of the ID.
    inputs: Request body matching the model's Input schema (model
        page → API → Input schema), e.g.
        ``{"prompt": "a cat", "aspect_ratio": "16:9", "seed": 42}``.
    wait_for_completion: If true, poll until done and return the
        result inline.
    timeout_seconds: Max wait when wait_for_completion=true.

File inputs must be publicly accessible HTTPS URLs that a plain
unauthenticated GET can fetch, e.g.
``{"image_url": "https://example.com/photo.webp"}``.

To run a Trainer LoRA without deploying it, call the LoRA's *base
model* ID here and pass the LoRA in the body, e.g.
``{"lora": {"path": "my_first_lora_3000.safetensors"}}`` — either a
LoRA name from your RunComfy LoRA Assets or a public URL.

Backs ``POST /prod/v1/deployments/{deployment_id}/inference``.

Args:
    deployment_id: Target deployment.
    overrides: Partial graph keyed by node_id, e.g.
        ``{"6": {"inputs": {"text": "a cat"}}}``.
        Use ``get_deployment(include_payload=true)`` to discover
        node IDs and input names.
    workflow_api_json: Advanced — run a different workflow without
        updating the deployment. Omit ``overrides`` in this mode.
    extra_data: E.g. ``{"api_key_comfy_org": "comfyui-..."}`` for
        ComfyUI Core API nodes.
    webhook_url: Push-based updates instead of polling.
    webhook_intermediate_status: Fire webhooks on every status
        change, not just terminal.
    wait_for_completion: If true, poll until done and return the
        result inline.
    timeout_seconds: Max wait when wait_for_completion=true.

File inputs: pass a public HTTPS URL or Base64 data URI directly
in the overrides value, e.g.
``{"189": {"inputs": {"image": "https://example.com/photo.jpg"}}}``
or ``{"189": {"inputs": {"image": "data:image/jpeg;base64,/9j..."}}}``.

Backs ``POST /prod/v1/trainers/ai-toolkit/jobs``. The job mounts a
``READY`` dataset and runs the config you supply. Training runs for
hours — this returns as soon as the job is queued; track it with
``get_training_job_status`` and pull artifacts with
``get_training_job_result``.

Args:
    config_file: The complete AI Toolkit YAML config as a string.
        Two paths in it are fixed by the platform:
        ``training_folder`` must be ``/app/ai-toolkit/output``, and
        the dataset's ``folder_path`` must be
        ``/app/ai-toolkit/datasets/{dataset_name}`` where
        ``dataset_name`` is the dataset's ``name`` (not its id).
    gpu_type: ``ADA_80_PLUS`` (H100) or ``HOPPER_141`` (H200).
    gpu_count: 1 for single-GPU (default), or 8 for multi-GPU.
        Multi-GPU is only supported on ``ADA_80_PLUS``.
    gpu_id: Optional specific GPU selector, e.g. ``"#1"``.

Backs ``PATCH /prod/v2/deployments/{deployment_id}``. Only pass the
fields you want to change. Set is_enabled=false to pause;
true to re-enable.

Downloads ``source_url`` and forwards the bytes to
``POST /prod/v1/trainers/datasets/{dataset_id}/upload``.

Args:
    dataset_id: Target dataset.
    source_url: Publicly reachable HTTPS URL for an image, video, or
        caption ``.txt`` file. Must be under 150 MB.
    filename: Name to store it under. Defaults to the URL's
        basename. For LoRA training each image/video needs a caption
        ``.txt`` with the *same base name* — ``img_0001.jpg`` pairs
        with ``img_0001.txt``.

Re-uploading the same filename overwrites the previous copy. For
files the caller holds locally, or anything over 150 MB, use
``get_dataset_upload_urls`` and PUT the bytes directly instead.

Backs ``POST /prod/v1/trainers/datasets/{dataset_id}/upload`` with
inline text, so captions can be written without hosting a file.

Args:
    dataset_id: Target dataset.
    filename: Must share the base name of the media it captions:
        ``img_0001.jpg`` → ``img_0001.txt``.
    text: Caption body.