开始使用 Rose API

一个 API 地址、一个访问令牌，按实际需要选择 Chat、Responses 或 Claude Messages 协议。

接入前准备

1. 进入 Rose API 登录账户。
2. 在控制台生成 API Key，并确认令牌分组与可用模型。
3. 打开 模型与价格，复制真实可用的模型 ID，替换文档中的 YOUR_MODEL_ID。
4. 根据软件需要选择协议，先用下面的模型列表测试鉴权，再进行正式调用。

基础地址与接口约定

第一步：测试密钥与模型列表

curl -sS https://api.365rose.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

成功时通常会得到包含 data 的模型列表。展示内容与可用权限可能受令牌分组限制。请以站点模型与价格页面和你的令牌可用性为准。

选择哪个协议？

常见状态与排查

OpenAI Chat Completions

面向常规对话、问答、文本任务与兼容 OpenAI Chat API 的应用。

接口规范

请求参数

cURL 示例

curl https://api.365rose.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "user", "content": "用一句话介绍 Rose API"}
    ],
    "stream": false
  }' 

Python · OpenAI SDK

# pip install --upgrade openai
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.365rose.com/v1"
)

result = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[{"role": "user", "content": "你好"}]
)
print(result.choices[0].message.content)

返回结构与读取

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "choices": [
    {"index": 0, "message": {"role": "assistant", "content": "你好！"}, "finish_reason": "stop"}
  ],
  "usage": {"prompt_tokens": 8, "completion_tokens": 5, "total_tokens": 13}
}

以上仅为结构示意。不同模型、渠道或流式模式下，返回字段可能不同；其中 choices 为常用的回复数组。

适用客户端与注意事项

• 多数写着“OpenAI Compatible / Chat Completions”的软件都可以用。
• 若客户端要求“API Host”，注意它可能期望带 /v1 的地址，也可能自己追加版本路径。
• 涉及函数调用、视觉输入、结构化输出时先确认模型支持，再添加对应参数。

Responses API · 编程接口

适用于使用 OpenAI Responses 协议的编程客户端、Agent 工作流和部分 Codex 接入场景。

接口规范

请求参数

cURL · 最简调用

curl https://api.365rose.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_RESPONSES_MODEL_ID",
    "instructions": "你是一位编程助手。",
    "input": "请写一个读取 JSON 文件的 Python 函数。",
    "stream": false
  }' 

Python · OpenAI SDK

# pip install --upgrade openai
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.365rose.com/v1"
)
response = client.responses.create(
    model="YOUR_RESPONSES_MODEL_ID",
    input="编写一个健壮的重试装饰器"
)
print(response.output_text)

Codex 配置参考

支持 Responses 的 Codex 客户端通常需要 base_url 包含 /v1，并将协议指定为 responses。以下为配置结构示例，具体写入方式与当前 Codex / CC Switch 版本有关。

# ~/.codex/config.toml（配置结构示例）
model_provider = "rose-api"
model = "YOUR_RESPONSES_MODEL_ID"

[model_providers.rose-api]
name = "Rose API"
base_url = "https://api.365rose.com/v1"
wire_api = "responses"
experimental_bearer_token = "YOUR_API_KEY"

如何判断接口已经通了？

• 请求成功时可拿到包含 id、output 等信息的响应。
• 若报 404，先检查是否错误拼接了 /v1/v1/responses。
• 若报不支持的字段或模型错误，确认所选模型、渠道和 Responses 协议是否匹配。

Claude Code · Messages API

兼容 Anthropic Messages 的模型可通过原生协议调用；Claude Code 使用的也是这类接口。

接口规范

请求参数

cURL 示例

curl https://api.365rose.com/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MESSAGES_MODEL_ID",
    "max_tokens": 512,
    "messages": [
      {"role": "user", "content": "用两句话说明 REST API"}
    ]
  }' 

Python · Anthropic SDK

# pip install --upgrade anthropic
from anthropic import Anthropic

client = Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.365rose.com"
)
message = client.messages.create(
    model="YOUR_MESSAGES_MODEL_ID",
    max_tokens=512,
    messages=[{"role": "user", "content": "你好"}]
)
for block in message.content:
    if block.type == "text":
        print(block.text)

Claude Code · 环境配置

如果使用 Claude Code，可以将其 API 地址指向 Rose API。这里不要在 ANTHROPIC_BASE_URL 末尾添加 /v1。

// ~/.claude/settings.json · 示例
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.365rose.com",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_MODEL": "YOUR_MESSAGES_MODEL_ID"
  }
}

也可以让 CC Switch 代为管理供应商配置与切换，不需要同时手工修改多个客户端配置。查看 CC Switch 教程 →

CC Switch 与第三方工具

通过 CC Switch 管理多个模型服务配置；使用其他 AI 客户端时，只需提供对应的接口地址、协议与密钥。

CC Switch 是什么？

CC Switch 是一个开源的 AI 编程工具供应商管理器，可以帮助你在 Claude Code、Codex 等客户端之间添加或切换 API 服务。这里以 Rose API 作为自定义供应商举例。

配置 Claude Code

1. 安装并打开 CC Switch，切换到 Claude Code 页面。
2. 点击新增供应商，选择自定义供应商，名称填写 Rose API。
3. API 格式选择 Anthropic Messages；接口地址填写 https://api.365rose.com。
4. 填入你的 Rose API Key，并将默认模型设为实际可用的 Messages 兼容模型。
5. 保存并启用供应商，再打开 Claude Code 测试简单消息。

配置 Codex / Responses

1. 在 CC Switch 的 Codex 页面添加自定义供应商 Rose API。
2. Base URL 填写 https://api.365rose.com/v1，协议使用 responses。
3. 填写 API Key，选择站内实际支持 Responses 的模型。
4. 启用供应商；如使用本地路由模式，先确保 CC Switch 已启动路由服务，再重启 Codex 终端。

常见配置对照

其他第三方工具怎么配置？

如 Cherry Studio、Chatbox、OpenCode、Cline 或其他兼容客户端，界面和字段名常随版本变化。你可以直接让 AI 助手根据软件版本一步步指导，不必照搬不适用的设置。

请教我把 [工具名称和版本] 接入 Rose API。
API 网站：https://api.365rose.com
OpenAI Chat/Responses 的 Base URL：https://api.365rose.com/v1
Claude Messages 的 Base URL：https://api.365rose.com
我的目标协议：[Chat Completions / Responses / Messages]
请按当前工具界面一步步告诉我在哪填地址、模型 ID、API Key，
并说明如何测试连通性和排查 401/404/模型不支持的错误。
我会自己在软件中输入真实密钥。

安全与兼容提醒

• 不要在浏览器前端代码、公开仓库或截图中泄露真实 API Key。
• 工具切换后若仍使用旧配置，请完全关闭并重新启动客户端。
• 某些编程工具依赖额外工具调用或流式事件，接口能正常返回文字不代表所有高级功能都受支持。
• 详细模型和定价以 Rose API 模型与价格 为准。

Flow · Omni 1.1 Flash Video

模型与价格

按次计费：文生视频、多图参考图生视频均为 $5.8 / 次。约 8 秒出片、无需传时长，720p，失败不计费。

两种模式（按素材自动切换）

选档规则：带参考图（images）→ 图生视频；不带 → 文生视频。两种模式同一模型名 flow-omni-1.1-flash，均为 $5.8 / 次。

接口信息

核心参数

⚠️ 约 8 秒出片，无需传 seconds / duration。朝向用 aspect_ratio（或 size），清晰度恒 720p。

画幅与朝向（横屏 / 竖屏怎么定）

比例不是必填：不传默认出横屏 16:9（1280×720）；要竖屏传 aspect_ratio:"9:16"，或用 size 传竖版 WxH（如 720x1280、1080x1920——超过 720p 会自动缩放到 720p）。同时传 size 和 aspect_ratio 时以 size 为准。清晰度恒 720p；图生视频同样用 aspect_ratio / size 指定朝向。

示例请求（curl）

BASE_URL="https://api.365rose.com"

TOKEN="sk-你的令牌"



# 1) 文生视频（720p 横屏，默认）

curl -sS -X POST "$BASE_URL/v1/videos" \

  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \

  -d '{"model":"flow-omni-1.1-flash","prompt":"日出时分平静的湖面雾气升腾，电影感镜头"}'



# 2) 文生视频（竖屏 9:16）

curl -sS -X POST "$BASE_URL/v1/videos" \

  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \

  -d '{"model":"flow-omni-1.1-flash","prompt":"竖屏短视频：城市夜景延时，霓虹流光","aspect_ratio":"9:16"}'



# 3) 图生视频（参考图，URL 或 base64）

curl -sS -X POST "$BASE_URL/v1/videos" \

  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \

  -d '{"model":"flow-omni-1.1-flash","prompt":"参考这些图片生成连贯运镜","images":["https://img1.jpg","https://img2.jpg"]}'

# => {"task_id":"task_xxx","status":"queued",...}

Python 完整示例（提交 → 轮询 → 下载）

import time, requests



BASE = "https://api.365rose.com"

TOKEN = "sk-你的令牌"

H = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}



# 提交：文生 720p 横屏。

#   竖屏 -> 加 "aspect_ratio": "9:16"

#   图生 -> 加 "images": ["https://.../a.jpg", "https://.../b.jpg"]（也支持 base64）

payload = {

    "model": "flow-omni-1.1-flash",

    "prompt": "日出时分平静的湖面雾气升腾，电影感镜头",

    "aspect_ratio": "16:9",     # 16:9 横屏 / 9:16 竖屏

}

r = requests.post(f"{BASE}/v1/videos", headers=H, json=payload, timeout=60)

r.raise_for_status()

task = r.json()

task_id = task.get("task_id") or task.get("id")

print("task_id:", task_id)



# 轮询直到完成（约 8 秒成片，通常 1-2 分钟）

while True:

    time.sleep(5)

    d = requests.get(f"{BASE}/v1/videos/{task_id}", headers=H, timeout=30).json()

    status = str(d.get("status", "")).lower()

    print("status:", status)

    if status == "completed":

        video_url = d.get("video_url") or (d.get("data") or [{}])[0].get("url")

        break

    if status == "failed":

        raise RuntimeError(d.get("error") or d)



open("out.mp4", "wb").write(requests.get(video_url, timeout=180).content)

print("成片:", video_url)

轮询取片

# 轮询直到 status=completed

curl -sS "$BASE_URL/v1/videos/task_xxx" -H "Authorization: Bearer $TOKEN"

# => {"status":"completed","video_url":"https://api.365rose.com/d/dl/xxx.mp4",...}



# 下载成片：用上面返回的 video_url（mp4，地址已脱敏、我方域名）

curl -sSL "<上面返回的 video_url>" -o out.mp4

轮询间隔建议 3–5 秒、客户端超时 ≥ 300 秒；勿重复提交同一任务。

注意事项

• 一个模型名 flow-omni-1.1-flash、自动切换：带参考图（images）= 图生视频；不带 = 文生视频。均为 $5.8 / 次。
• 朝向用 aspect_ratio（16:9 横屏默认 / 9:16 竖屏），也可用 size 的 WxH；清晰度恒 720p。
• 比例非必填：不传默认横屏 16:9；要竖屏传 aspect_ratio:"9:16"。
• 无水印、约 8 秒；按次计费、失败不计费。
• 多图参考 images：参考图须公网可直接下载或用 base64（需登录 / 内网 / 拦爬虫的链接会失败）。
• 生成约 1–2 分钟；轮询取片、勿重复提交同一任务。
• 提示词与参考图避免暴露 / 未成年 / 血腥暴力等敏感内容，否则被内容安全拦截（不计费）。

Omni 视频生成

基于 Gemini Veo 的视频生成服务，支持文生视频、图生视频（最多 5 张参考图）。

模型与价格

无水印模型输出经过自动清洗处理，完成前可能多一个 processing 阶段，稍慢。失败不计费。

接口信息

核心参数

Multipart 提交（支持文件上传）

示例：文生视频

curl -X POST https://api.365rose.com/v1/videos \

  -H "Authorization: Bearer sk-xxx" \

  -H "Content-Type: application/json" \

  -d '{

    "model": "omni-fast",

    "prompt": "雨夜霓虹街道，镜头缓慢推进，电影感光影",

    "aspect_ratio": "16:9"

  }'

示例：图生视频

# JSON：参考图 URL

curl -X POST https://api.365rose.com/v1/videos \

  -H "Authorization: Bearer sk-xxx" \

  -H "Content-Type: application/json" \

  -d '{

    "model": "omni-fast",

    "prompt": "保持人物一致，缓慢走动",

    "image_url": "https://your-cdn.com/photo.jpg",

    "aspect_ratio": "16:9"

  }'



# multipart：直接上传图片文件

curl -X POST https://api.365rose.com/v1/videos \

  -H "Authorization: Bearer sk-xxx" \

  -F "model=omni-fast" \

  -F "prompt=保持人物一致，缓慢走动" \

  -F "[email protected]"

参考图 URL 要求

参考图直接给公网 URL 即可，服务端会替你下载（经代理，不暴露你我的 IP），你只要保证链接能被匿名 GET 到；也可以传 data:image/...;base64,。URL 必须满足：

让它照着念台词

omni-fast 文生 / 图生视频会把你写的英文台词一字不差地念出来——把台词用引号写进提示词即可。8 个不同场景实测逐字 8/8，按序命中率 1.00。

curl -X POST https://api.365rose.com/v1/videos \

  -H "Authorization: Bearer sk-xxx" \

  -H "Content-Type: application/json" \

  -d '{

    "model": "omni-fast",

    "prompt": "A woman in a bright studio holds up a wireless earbud case to the camera. She speaks clearly to camera and says, \"This one lasts nine hours on a single charge.\" Bright commercial product-ad look.",

    "aspect_ratio": "16:9"

  }'

实测 8 个不同场景、同一句台词，逐字 8/8。所以：要精确台词 → 把台词用引号写进提示词。

轮询取片

curl https://api.365rose.com/v1/videos/{task_id} \

  -H "Authorization: Bearer sk-xxx"



# 完成后（优先读顶层 video_url，兼容 data[0].url；均为完整下载直链）:

# {"status":"completed",

#  "video_url":"https://api.365rose.com/v1/videos/vid-xxxx/content",

#  "data":[{"url":"https://api.365rose.com/v1/videos/vid-xxxx/content"}]}

Grok Imagine xAI

Grok 视频 · 模型与价格

按秒计费：费用 = 分辨率单价 × seconds。失败不计费。1.0 支持 480p / 720p；1.5-preview 额外支持 1080p。

视频接口信息

视频核心参数

⚠️ 1080p 限制：grok-imagine-video-1.5-preview 的 1080p 仅支持单张首帧 image，不支持多图 reference_images。需要多图参考请使用 480p / 720p。

视频示例请求

# 文生视频 · Grok Imagine 1.0
curl -X POST https://api.365rose.com/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "灯塔在日落时分，海浪拍打礁石，电影感镜头",
    "seconds": "8",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

# 图生视频 · Grok Imagine 1.5
curl -X POST https://api.365rose.com/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5-preview",
    "resolution": "720p",
    "prompt": "轻微镜头推移，画面自然生动",
    "image": "https://your-public-image.jpg",
    "seconds": "8",
    "aspect_ratio": "16:9"
  }'

# 多图参考 · 1.5-preview 720p
curl -X POST https://api.365rose.com/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5-preview",
    "resolution": "720p",
    "prompt": "融合多张参考图的场景，电影感转场",
    "reference_images": ["https://img-a.jpg", "https://img-b.jpg"],
    "seconds": "8"
  }'

轮询取片

curl https://api.365rose.com/v1/videos/task_xxx \
  -H "Authorization: Bearer sk-xxx"

# status=completed 后读取 video_url 并下载
curl -L "<video_url>" -o grok.mp4

建议每 3–5 秒轮询一次；客户端超时建议 ≥ 300 秒。任务已经受理后只轮询同一个 task_id，不要重复 POST。

Python 完整示例

import time
import requests

BASE = "https://api.365rose.com/v1"
TOKEN = "sk-你的令牌"
H = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
}

# 1.5 图生视频 · 720p
task = requests.post(f"{BASE}/videos", headers=H, json={
    "model": "grok-imagine-video-1.5-preview",
    "resolution": "720p",
    "prompt": "轻微镜头推移，画面自然生动",
    "image": "https://your-public-image.jpg",
    "seconds": "8",
    "aspect_ratio": "16:9",
}, timeout=60).json()

task_id = task.get("task_id") or task.get("id")
print("task_id:", task_id)

while True:
    time.sleep(4)
    s = requests.get(f"{BASE}/videos/{task_id}", headers=H, timeout=30).json()
    status = s.get("status")
    print("status:", status)

    if status == "completed":
        video_url = s.get("video_url") or (s.get("data") or [{}])[0].get("url")
        print("下载:", video_url)
        break

    if status == "failed":
        raise RuntimeError(s.get("error") or s)

视频注意事项

• grok-imagine-video 不带图可直接文生视频；grok-imagine-video-1.5-preview 建议带清晰参考图。
• seconds 支持 1–15 秒；价格按所选分辨率的单价 × 秒数结算。
• 多图参考仅建议用于 1.5-preview 480p / 720p，最多 7 张。
• 1080p 只支持单张首帧 image。
• 参考图 URL 必须公网可直接访问；否则请改用完整 base64 Data URI。
• 视频画幅只支持 16:9、9:16、1:1。
• 失败不计费。

Grok 图像 · 用法总览

grok-imagine-image 与 grok-imagine-image-2.0 同一个模型名可用于两种接口：/generations 做文生图，/edits 做图生图 / 编辑。-lite 仅支持文生图。

Grok 图像 · 模型与价格

图片接口为同步接口，请求成功后直接返回图片，无需轮询 task_id。失败不计费。

图像尺寸与画幅

size 与 aspect_ratio 二选一；其它取值可能报错。

图像核心参数

图像示例请求

# 文生图
curl -X POST https://api.365rose.com/v1/images/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "一座漂浮在云海上的未来城市，清晨柔光，电影感",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

# 图生图 / 图片编辑 · JSON 单图
curl -X POST https://api.365rose.com/v1/images/edits \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "保留主体构图，将背景改为雨后的霓虹街道",
    "image": "https://your-public-image.jpg",
    "response_format": "url"
  }'

# 图生图 / 图片编辑 · multipart 多图
curl -X POST https://api.365rose.com/v1/images/edits \
  -H "Authorization: Bearer sk-xxx" \
  -F "model=grok-imagine-image-2.0" \
  -F "prompt=融合两张参考图的风格，生成商品展示图" \
  -F "image[][email protected]" \
  -F "image[][email protected]" \
  -F "response_format=url"

图像返回

{
  "created": 1786675686,
  "data": [
    {
      "url": "https://api.365rose.com/v1/images/proxy/<encrypted-token>"
    }
  ]
}

response_format=url 时直接读取 data[].url；需要本地持久化或继续作为参考图使用时可选择 b64_json。

图像注意事项

• 图像接口为同步请求，请等待 data 返回后再继续处理。
• 参考图公网 URL 必须能被服务端直接下载；访问受限时请使用完整 data:image/...;base64,...。
• JSON 多图使用 images 数组；multipart 多图重复传 image[]。
• url 适合直接展示 / 下载；b64_json 适合本地持久化或二次处理。
• n 建议传 1，需要多张时分多次请求更稳。