调用模型

在终端查找 ModelSell 模型、查看参数，生成文本、图片、视频、音频和 3D 内容，恢复异步任务并下载结果。

调用模型前先登录一次。输入时不显示密钥，Key 保存在 ~/.config/modelsell/credentials.json：

modelsell login
modelsell status

脚本或 CI 中可以改用环境变量 MODELSELL_API_KEY，或 modelsell login --key-stdin 从标准输入读取。

找到模型并查看参数

modelsell models                      # 当前 Key 可用的模型
modelsell models seedance --type video
modelsell models --type image --compact --json
modelsell schema gpt-image-2          # 协议、路径、参数和文档链接
modelsell run gpt-image-2 --help

--type 可按 text、image、video、audio、3d、vector 等筛选。登录后只列出当前 Key 有权限的模型；未登录或加 --all 时显示公开目录，公开可见不代表当前 Key 能调用。--compact 只保留 ID、类型、协议和文档链接，适合给 Agent 阅读。

schema 显示的参数可能只是协议默认值。返回中带有 docs_url 时，以该文档列出的原生参数为准。

文本与图片

# 流式输出文本
modelsell run gpt-6-sol -p '用中文解释一下什么是向量数据库' --stream

# 生成图片并保存到本地
modelsell run gpt-image-2 -p '清晨海边的小屋，水彩风格' --download ./images

# 图片编辑：上传本地图片
modelsell run gpt-image-2 --endpoint openai-image-edit \
  --file image=./photo.png -p '替换为蓝色背景' --download ./edited

视频、音乐与 3D

视频等生成时间较长的任务会自动轮询直到完成：

modelsell run grok-imagine-video -p '镜头缓慢越过海面' --download ./videos

# Seedance：使用火山引擎原生格式和原生参数
modelsell run doubao-seedance-2-0-260128 \
  --endpoint seedance2-native-video -p '镜头缓慢越过海面' \
  -i duration=4 -i watermark=false --json

modelsell run suno_music -p '轻快的夏日纯音乐' -i make_instrumental=true --json
modelsell run Tripo/Tripo-H3.1 -p 'a small red robot' --json

不想等待时加 --no-wait，命令会返回任务 ID，之后用 wait 继续等待，见任务与下载。

语音、向量与重排

# 语音合成：音频是二进制结果，需要指定 --output
modelsell run AUDIO_MODEL --endpoint speech -p '你好，世界' \
  -i voice=alloy --output ./speech.mp3

# 语音识别：上传音频文件
modelsell run AUDIO_MODEL --endpoint transcription --file file=./speech.wav --json

# 向量
modelsell run text-embedding-v4 --endpoint embeddings \
  -i 'input=["第一段文字","第二段文字"]' --json

把 AUDIO_MODEL 换成支持对应协议的模型 ID。实时语音模型使用 modelsell realtime 模型，通过 JSONL 收发原生事件，音频需由调用方编码，CLI 不会采集麦克风。

传入参数

方式	用途
`-p '提示词'`	自动放进该协议的输入字段，如 `messages`、`prompt` 或 `content`
`-i key=value`	传入单个原生参数，可重复；支持数字、布尔、数组、对象和 `a.b` 嵌套字段
`--input-file request.json`	传入完整的 JSON 请求，适合多轮消息、工具调用和多模态内容；`-` 表示从标准输入读取
`--file 字段=./路径`	以 multipart 上传本地文件，单个文件最大 100 MiB
`--endpoint 协议`	模型支持多种协议时指定其一，可用值见 `modelsell endpoints`
`--dry-run`	只预览请求方法、路径和内容，不提交、不计费

参数优先级从低到高为：别名默认值、JSON 文件、-i、-p。已经用 JSON 传入 messages 时不要再加 -p。JSON 中以 @ 开头的字符串（如 "@./photo.png"）会读取本地文件并转为 data URI，需要模型支持这种格式。

任务与下载

modelsell run grok-imagine-video -p '镜头缓慢越过海面' --no-wait --json
modelsell wait TASK_ID --download ./videos   # 继续等待并下载
modelsell show TASK_ID --json                # 只查询一次
modelsell history --limit 20                 # 本机提交过的任务

默认每 2 秒查询一次，最长等待 600 秒，可用 --poll-interval 和 --timeout 调整。
等待超时或网络中断不代表生成失败。 用 wait 继续等待，不要重复提交，以免重复计费。
查询其他机器提交的任务时，用 --fetch-path 指定查询路径，例如 --fetch-path '/v1/videos/{task_id}'。
--download 目录 保存生成的媒体文件；modelsell download URL --output 文件 下载指定结果。默认不覆盖已有文件，需要覆盖时加 --force。

项目别名

在项目中运行 modelsell init 生成 modelsell.json，团队可以共享常用模型和参数（不包含 Key）：

{
  "defaultModel": "hero",
  "aliases": {
    "hero": {
      "model": "gpt-image-2",
      "endpoint": "image-generation",
      "input": { "size": "1024x1024" }
    }
  }
}

modelsell run hero -p '适合官网的水彩插画' --download ./images
modelsell run -p '同样风格的另一张'    # 省略模型时使用 defaultModel
modelsell aliases

用量与价格

modelsell usage    # 当前 Key 的额度（服务器 quota 单位，不是账户余额）
modelsell price gpt-image-2   # 公开价格信息，不是你所在分组的实际报价

在脚本中使用

加 --json 时结果写到标准输出，进度写到标准错误；原生响应保留在 response 字段，生成的链接在 outputs 字段。
--stream --json 逐行输出 JSONL 事件。
失败时返回非零退出码，并输出 {"error": {...}}。
需要调用 CLI 未封装的接口时，用 modelsell request /路径 --method POST --input-file body.json，请求只会发往配置的 API 地址。