# RY.LIVE API 接入摘要 更新时间：2026-10-15。完整文档：https://ry.live/docs ## RY.LIVE 是什么？ RY.LIVE 是面向开发者与团队的 AI 模型 API 服务，提供模型接入、API 密钥管理、用量查询和计费信息。模型目录包括对话与多媒体等能力；是否可用、具体端点和参数以实时模型广场及账户权限为准。 - 主站：https://ry.live/ - 模型广场：https://ry.live/pricing - 关于与联系：https://ry.live/about - 运营主体：中山市如云软件开发中心 - 客服邮箱：1932013@qq.com - 网站备案：粤ICP备2024238539号-1 ## 如何接入？ 1. 查看模型广场，确认准确模型名称、支持端点和价格。 2. 登录控制台，在自己获授权的账户中创建或使用 API 密钥。 3. OpenAI 兼容客户端的 Base URL 填 `https://ry.live/v1`，密钥填自己的密钥，模型填实时目录中的准确名称。 使用环境变量保存密钥和所选模型，不要把真实密钥写入代码或发送给他人： ```bash curl https://ry.live/v1/chat/completions \ -H "Authorization: Bearer $RY_LIVE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"你好"}],"max_tokens":64}' ``` `YOUR_MODEL_ID` 是占位符，调用前必须替换。并非每个模型都支持 Chat Completions；请按模型广场和完整文档选择协议。 ## 支持哪些端点？ - `GET /v1/models`：查看当前密钥可用模型，需要鉴权。 - `POST /v1/chat/completions`：适用于支持 Chat Completions 的对话模型。 - `POST /v1/responses`：适用于支持 Responses 的模型。 - `POST /v1/messages`：Anthropic Messages 兼容接口。客户端要求根地址时填写 `https://ry.live`。 - 图像、视频与其他模型接口：请阅读 https://ry.live/docs ，不要把任务型模型当作普通对话模型调用。 接口存在不代表所有模型完整支持该协议。部分模型的 Anthropic 工具结束标记存在已知兼容限制；接入依赖工具调用的 Agent 前，应按完整文档检查并做短请求验收。 ## Grok 生图、生视频与 ry.live 制品 完整示例：[Grok 生图](https://ry.live/docs#grok-images)、[Grok 生视频](https://ry.live/docs#grok-video)、[查询进度与制品下载](https://ry.live/docs#grok-artifacts)。所有创建、状态、制品列表与下载链接接口均使用本站普通 API Key 的 Bearer 鉴权，且只允许访问任务所属账户的结果。 - 图片模型：`grok-imagine-image`、`grok-imagine-image-2.0`、`grok-imagine-image-quality`；以账户 `/v1/models` 可见目录为准。`POST /v1/images/generations` 同步返回 `created` 与 `data[].url` / `data[].b64_json`，不添加 task_id；Base64 转换失败可能仅返回 URL。成功的新请求仍保留制品，可登录 [任务日志](https://ry.live/usage-logs/task) 预览、下载并取得任务 ID。图片编辑尚未启用。 - 需要程序获取图片任务 ID：改用 `POST /v1/tasks/xai-imagine`，相同顶层模型参数，省略 `response_format`；不要与普通生图重复提交。返回 `task_id`（与 `id` 相同），但创建仍可能等待同步生成，收据 `status=queued` 不是最终状态。 - 视频模型：`grok-imagine-video`、`grok-imagine-video-1.5`；`POST /v1/videos` 提交 JSON 文生视频，或 multipart 单参考图 `input_reference` 图生视频。保存响应 `id`，每隔 5 秒查 `GET /v1/videos/{id}`，直到 `completed` 或 `failed`。处理中 50% 是阶段提示，不是精确百分比；轮询应设等待上限，超时保留原 ID，不自动重新生成。 - 通用状态：`GET /v1/tasks/{task_id}`，顶层 `status` 为大写（成功 `SUCCESS`、失败 `FAILURE`），`progress` 为百分号字符串，错误见 `fail_reason`。勿与 Videos 的小写状态、数字进度混用。 - 完成后列制品：`GET /v1/tasks/{task_id}/artifacts` → `artifacts[]`，读取实际 `key`。Grok 图片通常 `image-1` 等，视频为 `video`。 - 申请本站下载地址：`POST /v1/tasks/{task_id}/artifacts/{key}/download-url?disposition=attachment`，JSON `{}`。200 且 `artifact_status=ready` 时读取 `url`、`expires_at`、`mime_type`、`size_bytes`；链接当前有效 15 分钟，下载时不再携带 API Key。202 `publishing` 表示制品保存中，按 `Retry-After`（当前 3 秒）有限重试下载链接接口，不重发生成。 - `content_url` 也是私密访问凭证，但不采用上述 15 分钟期限；不要公开或记录完整签名链接。也可带 Bearer 使用 `GET /v1/videos/{id}/content` 下载完成的视频。下载失败只重试下载或重新申请链接，不会再次收取模型生成费；请及时保存文件，不承诺永久存储。 图片数量 `n=1–10`，默认 1；分辨率与 quality 因模型而异。视频时长 `seconds=1–15`，默认 5，默认 480p；基础模型支持 480p/720p，1.5 另支持 1080p。详细参数和限制见 HTML 专节，不要把其他模型的参数直接照搬。 ## 火山方舟：Seedream 图片与 Seedance 视频 完整示例：[火山方舟图片与视频](https://ry.live/docs#volcengine)。使用本站普通 API Key，价格与可用性以模型广场和账户权限为准。 - 图片：`doubao-seedream-5-0-flash` 适合快速试稿，`doubao-seedream-5-0-pro` 适合画质优先的需求；均支持 1K / 1.5K / 2K，每次生成 1 张，最多 10 张参考图。 - 视频：`doubao-seedance-2-0` 支持 4–15 秒、最高 4k；`doubao-seedance-2-0-fast` / `doubao-seedance-2-0-mini` 支持 4–15 秒、最高 720p；`doubao-seedance-2-5` 支持 4–30 秒、最高 1080p。四款均支持声音。 - 生图用 `POST /v1/images/generations`，最小 JSON 为 `{"model":"doubao-seedream-5-0-flash","prompt":"蓝色陶瓷杯，白色背景","size":"2K","n":1,"response_format":"url"}`。参考图放顶层 `image`（图片 URL 或 URL 数组，也支持 data URI）。不添加 `stream`、`mask` 或组图参数 `sequential_image_generation`。 - 图片同步返回 `created` 与 `data[].url`，不返回任务 ID；成功制品可在 [任务日志](https://ry.live/usage-logs/task) 预览和下载。程序需要 ID 时改用 `POST /v1/tasks/doubao`，参数仍在顶层并省略 `n`、`response_format`，保存 `task_id` 后查询最终状态；仍需等待图片生成，收据 `queued` 不代表尚未生成。两种入口不要重复提交。 - 生视频用 `POST /v1/videos`，例如 `{"model":"doubao-seedance-2-0","prompt":"海边日出，镜头缓慢向前","seconds":5,"metadata":{"resolution":"720p","ratio":"16:9","generate_audio":true}}`。分辨率、比例和声音设置必须在 `metadata`；顶层同名字段不会生效。 - 视频参考图使用 `metadata.content`，单首帧项为 `{"type":"image_url","image_url":{"url":"https://example.com/replace-with-your-first-frame.png"},"role":"first_frame"}`；替换占位 URL 后使用。不要照搬 Grok 的顶层 `input_reference` / `image`，当前不支持 multipart 文件上传。高级素材组合请查完整文档链接的官方限制。 - 视频保存响应 `id` 后，每隔 5 秒查询 `GET /v1/videos/{id}`；只在 `completed` 后下载，`failed` 停止，失败原因见 `GET /v1/tasks/{id}` 的 `fail_reason`。10% / 50% / 100% 仅表示阶段，不是精确百分比或预计剩余时间。 - 图片与视频共用 [ry.live 制品下载流程](https://ry.live/docs#grok-artifacts)：完成后列出制品，再申请短期下载链接；202 `publishing` 时只等待保存并重试下载，不重新生成。不要向上游图片 URL 发送本站 API Key。 2026-10-15 已验证 Seedream Flash 生图与 ry.live 制品下载；其他模型及视频参数为接入契约核对，不是所有组合的生成实测。 ## Agent 本地参考图与图片、视频下载 有本地参考图、首尾帧、多参考图或下载/续传任务时，先读 [媒体调用与工具说明](https://ry.live/docs/media.md)。Agent 自动将本地图片上传至 SvrZs MinIO，用户无需手动中继外部 OSS；Python 示例默认授权直传 MinIO，multipart 入口也存入同一 MinIO。 - [操作指南](https://ry.live/docs/media) - [函数工具定义](https://ry.live/docs/media-tools.json)：需宿主绑定执行器，已有固定工具列表需更新，不是 MCP 服务地址。 - [Python 示例](https://ry.live/docs/examples/llmer_media.py)：upload / prepare / submit / status / download；prepare 只上传和构造请求。 H3 资产字段支持首尾帧和 1–4 张有序参考图，默认 8 步 768P；1080P 为超分输出。下载中断只重试下载或续签，不重新生成。只配置聊天 Base URL 的 Agent 仍需文件读取和工具执行能力。 ## 价格、缓存和账单怎么看？ 实时模型价格见模型广场。实际收费受模型计费规则、账户分组及请求用量影响；币种和计价单位以界面显示为准。缓存命中需要上游实际命中并上报用量，有缓存价格不代表每次请求都能享受缓存价。切换到不共享缓存的上游也可能影响命中率。 本文不维护独立价格表，避免与实时配置不一致。核对账单时，应同时查看模型、输入、输出、缓存用量、分组和用量记录。 ## 调用失败怎么办？ 先核对 Base URL、准确模型名、密钥权限和对应协议。向客服提供请求时间、模型、Request ID 和脱敏错误；不要提供完整 API 密钥、密码或敏感业务内容。AI 输出可能有误，重要结果需自行核实。 ## ComfyUI 本地参考图与下载 使用 ComfyUI 时，读取 [节点安装与工作流](https://ry.live/docs/comfyui)。提供 MinIO 直传、首尾帧/多参考请求准备、已有结果下载和自动重试。前三个示例不含生成提交节点，新增完整流程的提交默认关闭；安装后重启 ComfyUI 并使用自己的 API 密钥。