Moondream Cloud 免费额度：每工作区每月 5 美元视觉模型用量

Moondream Cloud 的调用方式是标准 HTTP 请求加 Bearer 鉴权，重点是图片如何随请求体传进去，以及不同视觉任务靠提示词区分。

base_url 与模型名

base_url 的形态为 https://api.moondream.ai/v1，最终请以控制台 API 文档页给出的地址为准；模型标识在控制台的模型列表或文档中获取，填写视觉模型对应的名称，不要沿用纯文本模型的名字。建议先把密钥和 base_url 写成环境变量：

export MOONDREAM_API_KEY="控制台生成的密钥"
export MOONDREAM_BASE_URL="https://api.moondream.ai/v1"

把这两行写进 ~/.zshrc 或 ~/.bashrc，重开终端生效，避免把密钥硬编码进代码后提交到仓库。

一次图片描述调用

下面是最小可运行的 curl 示例，把图片地址换成你自己可公网访问的图片 URL，把文字换成你要问的问题：

curl "$MOONDREAM_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $MOONDREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moondream-vision",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "用一句中文描述这张图片的主要内容"},
          {"type": "image_url", "image_url": {"url": "https://example.com/demo.jpg"}}
        ]
      }
    ],
    "max_tokens": 200,
    "temperature": 0.2
  }'

关键参数说明：model 必须是控制台提供的视觉模型标识；messages 里的 content 是数组，文本与图片交替排列，图片用 image_url 类型的条目传入；max_tokens 控制输出长度，做批量打标时压到很短即可，能明显降低单张成本；temperature 取低值让描述和坐标更稳定。若图片不方便公网访问，可改为传 base64 内联数据，具体字段以控制台文档为准。

用提示词切换任务类型

• 图片描述：直接问「描述这张图的内容」，适合批量生成图片标签。
• 视觉问答：提出具体问题，例如「图中这个人手里拿的是什么」，输出更短更省额度。
• 目标检测：要求「列出图中所有物体及其边界框」，返回结构化坐标，适合批量标注。
• 点定位：要求「指出图中某个元素的位置」，适合截图理解和界面元素定位。

额度耗尽与限流的典型表现

• 返回 401：密钥错误、被删除，或环境变量没有在当前终端生效，重新生成并检查变量。
• 返回 400 且提示图片相关错误：图片 URL 不可公网访问、格式不支持或尺寸过大，先转成 JPG 或 PNG 并压缩。
• 返回 429：请求频率或并发过高，降低并发数并加入指数退避重试，不要立即密集重试。
• 返回 402 或 403，或提示额度不足：当前 workspace 本月 $5 额度已经用尽，等下一周期重置，或切换到其他 workspace，或考虑升级套餐。

排查顺序建议固定为：401 先查密钥与终端环境变量，400 再查请求体和图片本身，429 看并发与重试间隔，最后去控制台 Usage 面板核对剩余额度与重置日期，确认是否只是额度用完而不是接口变更。