Relay

Lists Relay models by tag and/or text. Common tags: text-to-image, image-to-image, text-to-video, image-to-video, video-to-video, text-to-speech, speech-to-text, text-to-text, text-to-embedding. Returns name, tag and route per model (at most 50). Then call get_model with a name for its input schema.

{
  "type": "object",
  "properties": {
    "tag": {
      "type": "string",
      "description": "Model type tag, e.g. text-to-image or image-to-video. Omit for every tag."
    },
    "query": {
      "type": "string",
      "description": "Words to match, case-insensitive; every word must appear in the name, display name or tag (e.g. 'kling v3')."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns one model's route, request_schema (what run_model's input must follow), request_example, pricing and availability. Then call run_model with an input shaped like request_example.

{
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "description": "Exact model name from search_models, e.g. Qwen/qwen-image."
    }
  },
  "required": [
    "model"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns Relay's public list prices (USD), optionally for one model, plus media_storage: the per-file fees of the store_output / upload retention SKUs (relay1d, relay7d, …). Then estimate_cost for a number.

{
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "description": "Model name (e.g. Qwen/qwen-image) to keep only its rows. Omit for every model."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Estimates the USD cost of a call from the public price list: an estimate, not an invoice (the bill uses provider-reported usage and any custom pricing on your account). Pass only the usage fields the model's billing_type (see get_model or get_pricing) reads: per_token: input_tokens, output_tokens, cached_input_tokens; per_image: image_count, resolution_tier; per_second_video: duration_seconds, quality_mode, sound; per_second_audio: duration_seconds; per_character: character_count; per_media_token: media_input_tokens, media_output_tokens. Add store_output / retention / file_count for storage fees.

{
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "description": "Exact model name, e.g. KlingTeam/v3-T2V."
    },
    "usage": {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "direct",
            "opengpu"
          ],
          "description": "Pricing mode; default direct."
        },
        "input_tokens": {
          "type": "number",
          "description": "per_token: prompt tokens."
        },
        "output_tokens": {
          "type": "number",
          "description": "per_token: completion tokens."
        },
        "cached_input_tokens": {
          "type": "number",
          "description": "per_token: cached-read tokens (a subset of input_tokens)."
        },
        "cache_write_5m_input_tokens": {
          "type": "number",
          "description": "per_token: 5-minute prompt-cache writes (a subset of input_tokens)."
        },
        "cache_write_1h_input_tokens": {
          "type": "number",
          "description": "per_token: 1-hour prompt-cache writes (a subset of input_tokens)."
        },
        "image_count": {
          "type": "number",
          "description": "per_image: images generated (default 1)."
        },
        "resolution_tier": {
          "type": "string",
          "description": "per_image / per_second_video: resolution key of the row, e.g. 1K, 2K, 720p."
        },
        "duration_seconds": {
          "type": "number",
          "description": "per_second_video / per_second_audio: seconds of output (or input audio)."
        },
        "quality_mode": {
          "type": "string",
          "description": "per_second_video: std or pro (Kling)."
        },
        "sound": {
          "type": "boolean",
          "description": "per_second_video: sound on or off."
        },
        "has_ref": {
          "type": "boolean",
          "description": "per_second_video: a reference input is present (Kling O1)."
        },
        "character_count": {
          "type": "number",
          "description": "per_character: characters of text to speak."
        },
        "media_input_tokens": {
          "type": "number",
          "description": "per_media_token: media input tokens."
        },
        "media_output_tokens": {
          "type": "number",
          "description": "per_media_token: media output tokens."
        },
        "request_count": {
          "type": "number",
          "description": "per_request: requests (default 1)."
        },
        "store_output": {
          "type": "string",
          "description": "Output storage SKU from get_pricing media_storage (adds its per-file fee); provider is free."
        },
        "retention": {
          "type": "string",
          "description": "Upload retention SKU from get_pricing media_storage; relay1h is free."
        },
        "file_count": {
          "type": "number",
          "description": "Files the storage fee applies to (default image_count, else 1)."
        }
      },
      "additionalProperties": true,
      "description": "What the call uses; only the fields of the model's billing type matter."
    }
  },
  "required": [
    "model",
    "usage"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Runs any Relay model by name (billed to your key). input follows get_model's request_schema (request_example runs as is). Waits up to 45 s; past that it returns a task_id — do not resubmit, call check_task. Result links expire 1 h after completion unless store_output names a media_storage SKU from get_pricing. Pass an idempotency_key if you may retry the same submit. Needs a Relay credential.

{
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "description": "Exact model name from search_models / get_model, e.g. Qwen/qwen-image."
    },
    "input": {
      "type": "object",
      "additionalProperties": {},
      "description": "Request body per get_model's request_schema, without model (added for you). Pass media as *_url links (upload_file makes one)."
    },
    "store_output": {
      "type": "string",
      "description": "Keep result media longer: a media_storage SKU from get_pricing (e.g. relay7d, adds its per-file fee), or provider (default, 1 h)."
    },
    "wait_seconds": {
      "type": "integer",
      "minimum": 0,
      "maximum": 45,
      "default": 45,
      "description": "Seconds to wait for it to finish (0–45, default 45); 0 returns the task_id at once."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Your key for this submit: a retry with the same key replays the first task instead of starting (and billing) a new one."
    },
    "inline_images": {
      "type": "boolean",
      "description": "Also return images ≤ 1 MB as image content blocks (default false: links only)."
    }
  },
  "required": [
    "model",
    "input"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Checks a task run_model returned (no key needed: the task_id is the capability). Waits up to 30 s for it to finish; returns the result when completed, else its status: then call check_task again, never resubmit. Task results are kept 1 h after they finish.

{
  "type": "object",
  "properties": {
    "task_id": {
      "type": "string",
      "description": "The task_id from run_model, e.g. direct:2f9c…"
    },
    "wait_seconds": {
      "type": "integer",
      "minimum": 0,
      "maximum": 30,
      "default": 30,
      "description": "Seconds to wait for it to finish (0–30, default 30); 0 just reads the status."
    },
    "inline_images": {
      "type": "boolean",
      "description": "Also return images ≤ 1 MB as image content blocks (default false: links only)."
    }
  },
  "required": [
    "task_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Hosts an image, video or audio file on Relay and returns its url: pass that url to any *_url input of run_model. Give exactly one of path (local server only, ≤ 100 MB), base64 (≤ 4 MB) or url (a public link Relay copies). retention: relay1h (default, free within a daily quota) or a media_storage SKU from get_pricing. Needs a Relay credential.

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Local file path (stdio server only; the hosted server cannot read your disk). Max 100 MB."
    },
    "base64": {
      "type": "string",
      "description": "File content as base64 or a data: URI, at most 4 MB decoded. Larger files: pass url."
    },
    "url": {
      "type": "string",
      "description": "Public http(s) link to copy onto Relay."
    },
    "retention": {
      "type": "string",
      "description": "How long the link lives: relay1h (default, free within a daily quota) or a media_storage SKU from get_pricing (relay1d, relay7d, …)."
    },
    "filename": {
      "type": "string",
      "description": "File name to record (defaults to the path's base name)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List Relay's workflow templates: multi-step pipelines (e.g. script → voiceover) run as one call. Each entry has workflow_id, input_schema and its steps (step_id + model). Run one with run_workflow; inputs follow input_schema.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Start a workflow run (one submit) and wait up to wait_seconds (≤ 45) for it to finish. Completed → the final output; still running → run_id: call check_workflow_run with it, never resubmit (a new run bills again). Each step is billed as an ordinary request. webhook_url gets ONE signed workflow.completed / workflow.failed delivery when the run ends. Get workflow_id and the inputs shape from list_workflows. Needs a Relay credential.

{
  "type": "object",
  "properties": {
    "workflow_id": {
      "type": "string",
      "minLength": 1,
      "description": "Workflow template id from list_workflows, e.g. `script-voiceover`."
    },
    "inputs": {
      "type": "object",
      "additionalProperties": {},
      "description": "Template inputs, an object matching the workflow's input_schema."
    },
    "store_output": {
      "type": "string",
      "description": "Run-level storage for every media step: `provider` (default, 1 h link) or `relay1d` / `relay7d` / `relay30d` (billed per file, see get_pricing)."
    },
    "webhook_url": {
      "type": "string",
      "description": "HTTPS URL for one signed workflow.completed / workflow.failed delivery when the run ends."
    },
    "wait_seconds": {
      "type": "integer",
      "minimum": 0,
      "maximum": 45,
      "default": 45,
      "description": "Seconds to wait for it to finish (0–45, default 45); 0 returns the run_id at once."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Idempotency-Key for the submit: the same key and inputs within 24 h return the same run_id instead of a new run. Generated when omitted."
    }
  },
  "required": [
    "workflow_id",
    "inputs"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Poll a workflow run by run_id, waiting up to wait_seconds (≤ 30) for it to end. Completed → the final output; failed / cancelled → the error; still running → its steps so far: call check_workflow_run again. No key needed: the run_id is the access token.

{
  "type": "object",
  "properties": {
    "run_id": {
      "type": "string",
      "minLength": 1,
      "description": "The run id returned by run_workflow (`wf:…`)."
    },
    "wait_seconds": {
      "type": "integer",
      "minimum": 0,
      "maximum": 30,
      "default": 30,
      "description": "Seconds to wait for it to finish (0–30, default 30); 0 answers the current state at once."
    }
  },
  "required": [
    "run_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Cancel a workflow run. Cancels between steps only: a step already running completes and bills. A run that has already ended answers WORKFLOW_RUN_NOT_CANCELLABLE. Needs a Relay credential.

{
  "type": "object",
  "properties": {
    "run_id": {
      "type": "string",
      "minLength": 1,
      "description": "The run id returned by run_workflow (`wf:…`)."
    }
  },
  "required": [
    "run_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read the account's credit balance, active promo credits and consumption. Needs a dashboard JWT or a custom-tier superkey; a plain inference key gets PERMISSION_DENIED (403). Needs a Relay credential.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read the account's usage and spend per API key. Pass period (e.g. 7d) for a by-date breakdown, or from + to. Needs a dashboard JWT or a custom-tier superkey; a plain inference key gets PERMISSION_DENIED (403). Needs a Relay credential.

{
  "type": "object",
  "properties": {
    "period": {
      "type": "string",
      "description": "Time period shorthand, e.g. `7d` or `30d` (max 30 days); adds a by-date breakdown."
    },
    "from": {
      "type": "string",
      "description": "Start date `YYYY-MM-DD`; use together with `to`."
    },
    "to": {
      "type": "string",
      "description": "End date `YYYY-MM-DD`; use together with `from`."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Search Relay's public docs (bundled, offline) for how-to, auth, errors, limits, retries, webhooks, files and pricing rules. Returns the best-matching sections: page, heading, docs path with anchor and an excerpt. For a model's input fields use get_model instead; to find a model use search_models.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "What to look for, in plain words, e.g. `idempotency key` or `file retention`."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 5,
      "description": "How many sections to return (1–10, default 5)."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}