yangdev API 文档

一个端点，所有大模型。统一 OpenAI 兼容接口（Chat Completions + Responses）；按量付费与包月订阅双通道； Claude Code / Cursor / Cline / Codex / opencode / ChatBox 等任意 OpenAI 协议工具均可直接接入。

接入地址

基础 URL

https://yangdev.studio

OpenAI SDK 中使用的 base_url 为：

https://yangdev.studio/v1

认证方式

所有 API 请求必须在 HTTP Header 中携带你的 API Key：

Authorization: Bearer sk-xxxxxxxxxxxx

认证流程

yangdev 采用「API Key 预生成 → 手机号激活」的两步认证流程：

快速开始

1. 安装 SDK

# Python
pip install openai

# Node.js
npm install openai

2. 配置并发送请求

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的已激活API-Key",
    base_url="https://yangdev.studio/v1",
)

response = client.chat.completions.create(
    model="qwen3.6-plus",
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手。"},
        {"role": "user", "content": "你好，介绍一下你自己"},
    ],
)

print(response.choices[0].message.content)

Node.js

import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: 'sk-你的已激活API-Key',
    baseURL: 'https://yangdev.studio/v1',
});

const response = await client.chat.completions.create({
    model: 'qwen3.6-plus',
    messages: [{ role: 'user', content: '你好！' }],
});

console.log(response.choices[0].message.content);

cURL

curl https://yangdev.studio/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的已激活API-Key" \
  -d '{
    "model": "qwen3.6-plus",
    "messages": [{"role": "user", "content": "你好"}]
  }'

激活 API Key

将一个待激活的 API Key 绑定到手机号，激活后自动获得初始额度。每个手机号只能绑定一个 Key，每个 Key 只能绑定一个手机号。

请求体参数

请求示例

curl -X POST https://yangdev.studio/auth/activate \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sk-abcdef1234567890abcdef1234567890abcdef1234567890",
    "phone": "13800138000",
    "referrer_phone": "13900139000"
  }'

成功响应 (200)

{
  "success": true,
  "balance": 60.0,
  "currency": "CNY",
  "phone_masked": "138****8000",
  "referrer_bonus_applied": true,
  "activated_at": "2026-04-14T12:00:00Z"
}

上例中，初始额度 ¥50 + 推荐奖励 ¥10 = ¥60。

错误响应示例

账户信息查询

查询当前 API Key 关联的账户信息，包括余额、用量统计等。使用 Bearer Token 认证。

请求示例

curl https://yangdev.studio/v1/key/info \
  -H "Authorization: Bearer sk-你的API-Key"

成功响应 (200)

{
  "success": true,
  "api_key_masked": "sk-abc...7890",
  "status": "active",
  "key_type": "payg",
  "plan": "payg",
  "phone_masked": "138****8000",
  "balance": 42.35,
  "currency": "CNY",
  "total_topup": 60.0,
  "total_used": 17.65,
  "activated_at": "2026-04-14T12:00:00Z",
  "calls_today": 23,
  "calls_total": 156,
  "estimated_remaining_messages": 1411
}

订阅 Key 响应（200）

订阅 Key（包月/包年）不走余额计费，key_type 为 subscription 时额外返回 subscription 订阅块（套餐与到期信息），estimated_remaining_messages 改为反映窗口剩余次数而非余额；balance 对订阅 Key 无意义，请勿据此判断「余额不足」。

{
  "success": true,
  "key_type": "subscription",
  "plan": "subscription",
  "balance": 0.0,
  "estimated_remaining_messages": 480,
  "subscription": {
    "active": true,
    "plan_name": "专业版 月付",
    "plan_code": "pro_monthly",
    "status": "active",
    "started_at": "2026-06-01T00:00:00",
    "expires_at": "2026-07-01T00:00:00",
    "days_remaining": 20
  }
}

响应字段说明

推荐码机制

激活时填写 referrer_phone（已注册用户的手机号），双方各得 ¥10 额度奖励。

• 推荐人必须是已激活的用户
• 不能填写自己的手机号作为推荐人
• 每个新用户只能被推荐一次
• 奖励额度即时到账，可在 /v1/key/info 查看更新后的余额

余额与计费

文本 / 对话 API 按实际 token 消耗扣费，计费公式：

费用 = (输入 tokens × 输入单价 + 输出 tokens × 输出单价) ÷ 1,000,000

单价参见下方定价表，单位为「元 / 百万 tokens」。图片/视频生成模型价格单位因上游而异（美元或人民币），见图片生成与视频生成章节。费用精确到 ¥0.0001。

对话补全

创建对话补全请求。完全兼容 OpenAI Chat Completions API 格式，支持流式与非流式响应。

请求参数

Messages 格式

非流式响应 (200)

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1775542800,
  "model": "qwen3.6-plus",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！有什么可以帮助你的吗？"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 12,
    "total_tokens": 27
  }
}

流式响应

设置 "stream": true 后，响应使用 Server-Sent Events (SSE) 格式逐段返回：

curl https://yangdev.studio/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的API-Key" \
  -d '{
    "model": "qwen3.6-plus",
    "stream": true,
    "messages": [{"role": "user", "content": "写一首五言绝句"}]
  }'

SSE 数据流格式

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"role":"assistant"},"index":0}]}
data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"春"},"index":0}]}
data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"眠"},"index":0}]}
...
data: {"id":"chatcmpl-xxx","choices":[{"delta":{},"finish_reason":"stop","index":0}],"usage":{"prompt_tokens":10,"completion_tokens":20,"total_tokens":30}}
data: [DONE]

OCR 识别

口袋龙虾客户端用于图片文字识别的网关接口。请求 multipart/form-data，由 yangdev 网关校验鉴权与配额。

请求

请求示例

curl -X POST https://yangdev.studio/v1/ocr \
  -H "Authorization: Bearer sk-你的API-Key" \
  -F "file=@/path/to/image.png"

限制与计费

• 每分钟限流与对话补全共用同一速率限制。
• 单 Key 每日 100 次 OCR 配额（可由管理员调整）。
• 当前 OCR 调用不收取人民币费用，仅占用每日配额。
• OCR 服务暂停时返回 503；超出配额返回 429。

客户端更新检查

客户端版本 / MCP 包 / 技能包三通道更新检查接口，无需鉴权。

请求参数（Query）

响应示例

{
  "success": true,
  "latest_version": "2.8.2",
  "download_url": "https://yangdev.studio/downloads/yangdev-app-2.8.2.zip",
  "need_update": true,
  "mcp":    { "latest_version": "...", "download_url": "..." },
  "skills": { "latest_version": "...", "download_url": "..." }
}

顶层字段为主程序通道（all），mcp / skills 对象分别表示 MCP 包与技能包通道；旧客户端可继续读取顶层字段保持兼容。

按操作系统拆分的端点

主程序安装包按操作系统区分时，请调用对应 OS 端点；它们返回与上面完全一致的结构（顶层为该 OS 的主程序更新，外加 "os" 字段），mcp / skills / 公告 / 模型与通用端点共享。未发布对应 OS 版本时自动回退到通用包，不会缺更新。

查询参数与通用端点相同（version / mcp_version / skills_version）。macOS 客户端固定调 /macos，Windows 固定调 /windows；遗留端点 /v1/update/check 仍服务旧客户端（返回通用包）。

思考强度控制

部分模型支持在请求中控制「思考 / 推理强度」，让模型在速度与深度之间取得平衡。yangdev 网关兼容多种客户端参数格式，统一映射到上游模型所需的形式。

支持的模型

不在上表中的模型（如 qwen3.6-plus、sonnet、gemini-3.1-pro）不支持思考强度控制，传入相关参数会被静默忽略。

OpenAI 兼容格式（GPT 系列）

对 GPT 模型，使用顶层 reasoning_effort 字段：

curl https://yangdev.studio/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的API-Key" \
  -d '{
    "model": "gpt-5.4",
    "reasoning_effort": "high",
    "messages": [{"role": "user", "content": "证明根号2是无理数"}]
  }'

Anthropic 原生格式（Claude Opus 4.7）

Claude Opus 4.7 通过 /v1/messages 端点支持两种控制维度：

• thinking.type：控制思考模式，可选 "enabled"（固定预算）、"adaptive"（自适应）、"disabled"（关闭思考）。
• output_config.effort：控制整体输出努力程度，可选 low / medium / high / max。

curl https://yangdev.studio/v1/messages \
  -H "x-api-key: sk-你的API-Key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opus4.7",
    "max_tokens": 4096,
    "thinking": {"type": "enabled", "budget_tokens": 2048},
    "output_config": {"effort": "high"},
    "messages": [{"role": "user", "content": "分析这段代码的性能瓶颈"}]
  }'

参数自动迁移

不同客户端可能将 effort 参数放在不同位置。yangdev 网关会自动将以下位置的 effort 字段迁移到上游模型所需的正确位置：

• reasoning_effort（顶层，OpenAI 风格）
• output_config.effort（Anthropic 风格）
• thinking.effort（部分客户端扩展）
• thinking.adaptive.effort（部分客户端扩展）

订阅 / Premium 模式

除按量计费外，yangdev 支持订阅模式，用于覆盖需要按账号 / 订阅计费的高级模型通道。

• API Key 通过 key_type = "subscription" 标记，由管理员预生成并发放。
• 每位用户可绑定一个订阅计划（plan），plan 决定可用模型、5 小时 / 周 / 月三档窗口配额（用户侧展示统一为「次调用」，1 prompt ≈ 15 次调用），以及可选的单模型月上限。
• 调用按窗口扣减加权次数（GitHub Copilot premium-requests 风格），不扣人民币余额。计费单位为「次调用」，以 GPT-5.4 官方 API 列表价 = 1 次 为基准：Qwen = 1、GPT-5.4 / GPT-5.6 Terra = 1、GPT-5.5 / GPT-5.6 Sol = 2、GPT-5.6 Luna ≈ 0.4、GPT-5.4-mini ≈ 0.3、Grok 4.5 ≈ 0.5；Claude 系列不按「次调用」扣，按真实 token 用量计入专属高级模型额度（与「次调用」池相互独立）。Agent 模式下 1 prompt 平均 ≈ 15 次底层调用。Gemini 系列仅按量付费 key 支持，不在订阅内。
• 若窗口已满，调用直接返回 429 QUOTA_EXCEEDED；若仅单模型月上限打爆（如进阶档 Opus 750 次 prompt/月），返回 429 MODEL_MONTHLY_CAP_EXCEEDED，客户端可立即切换到其他模型继续。
• 订阅与按量计费完全分离：同一把 Key 不会同时走两套路径。

在售订阅计划

下表 5h / 周 / 月数字单位为「次调用」（GPT-5.4 = 1 基准；Qwen = 1、GPT-5.5 / 5.6-Sol = 2、5.6-Luna ≈ 0.4、mini ≈ 0.3、Grok ≈ 0.5；Claude 系列不占该池，另走专属高级模型额度；Agent 模式下 1 prompt ≈ 15 次底层调用）。

Gemini 系列模型不在订阅范围内，请使用按量付费 key 调用。

单模型月上限按原始调用次数计（不叠加 ×15，直接看用户实际发到该模型的请求数）。达上限后仅阻塞该模型，不影响同档位 plan 调用其他模型。

调用权重表

通用模型每次调用按成本加权扣「次调用」；Claude 系列不走该池，按真实 token 用量计入专属高级模型额度。下表给出每次模型调用消耗的"次调用"配额，以及 Agent 模式下 1 prompt 平均消耗的"次调用"数。

示例：进阶档月度 54,000 次调用 ≈ 54,000 次 GPT-5.4 / Qwen 或 27,000 次 GPT-5.5，混用按实际权重累加；Claude 用量另计专属额度、互不挤占。未来新增通用模型若未显式配置权重，默认按「1 次调用 = 1 次」计。

长上下文规则（与官方一致）：单次请求上下文（含缓存）超过 256k tokens 时按 2 倍次调用扣减（如 gpt-6-astra 由 4 次计为 8 次）。

用户侧操作

1. 从代理商 / 管理员获取一把订阅 Key（sk-...）。
2. 用 POST /auth/activate 绑定手机号（管理员侧已为该手机号开通对应订阅）。
3. 正常调用 /v1/chat/completions，模型名使用订阅允许的模型即可。
4. 通过 GET /v1/subscription/info 或 订阅自助页 查询当前窗口余量（API 返回字段单位即「次调用」，可直接展示）。

订阅状态查询

返回当前 API Key 的订阅信息、三档窗口的实时配额状态与近期调用记录。使用 Bearer Token 认证；按量计费 Key 调用时返回 key_type=payg 与空的窗口结构，便于客户端自适应。

请求示例

curl https://yangdev.studio/v1/subscription/info \
  -H "Authorization: Bearer sk-你的API-Key"

响应示例（订阅 Key）

{
  "success": true,
  "key_type": "subscription",
  "phone_masked": "138****8000",
  "subscription": {
    "plan_code": "mid_1499",
    "plan_name": "进阶订阅 (1499/月)",
    "status": "active",
    "started_at": "2026-04-10T00:00:00Z",
    "expires_at": "2026-05-10T00:00:00Z"
  },
  "windows": {
    "5h":    { "used": 540,    "limit": 2700,   "remaining": 2160   },
    "week":  { "used": 4050,   "limit": 13500,  "remaining": 9450   },
    "month": { "used": 16200,  "limit": 54000,  "remaining": 37800  }
  },
  // used/limit/remaining 单位均为「次调用」（GPT-5.4 = 1 基准；Claude 另计专属额度）
  "today_calls": 37,
  "recent_calls": [
    { "created_at": "2026-04-20T08:30:01Z", "model": "opus4.7" }
  ]
}

响应示例（按量计费 Key）

{
  "success": true,
  "key_type": "payg",
  "subscription": null,
  "windows": {}
}

订阅模式错误码

订阅模式 (key_type=subscription) 在 /v1/chat/completions 上有一组独立错误。所有失败都不会扣减人民币余额，也不会回退到按量计费。

Anthropic 原生协议

兼容 Anthropic 原生 Messages API 格式，Claude Code CLI / Claude Desktop / anthropic-sdk-python 等原生客户端无需任何格式转换即可接入。与 /v1/chat/completions 共用同一套鉴权、订阅配额、长任务心跳保活逻辑。

请求示例（非流式）

curl https://yangdev.studio/v1/messages \
  -H "x-api-key: sk-你的API-Key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opus4.7",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "用一句话介绍你自己"}
    ]
  }'

请求示例（流式）

curl -N https://yangdev.studio/v1/messages \
  -H "x-api-key: sk-你的API-Key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opus4.7",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "hello"}]
  }'

Python SDK（anthropic 官方）

import anthropic

client = anthropic.Anthropic(
    api_key="sk-你的API-Key",
    base_url="https://yangdev.studio",
)

msg = client.messages.create(
    model="opus4.7",
    max_tokens=1024,
    messages=[{"role": "user",
               "content": "hi"}],
)
print(msg.content[0].text)

Claude Code CLI（原生接入）

export ANTHROPIC_BASE_URL="https://yangdev.studio"
export ANTHROPIC_AUTH_TOKEN="sk-你的API-Key"
export ANTHROPIC_MODEL="opus4.7"
export ANTHROPIC_SMALL_FAST_MODEL="qwen3.6-plus"
claude

Claude Code 会走 POST /v1/messages 原生协议，按你的订阅或余额正常计费；响应首字节有心跳保活，长推理不再因 524 中断。

OpenAI Responses API

兼容 OpenAI Responses API（Codex Desktop / Codex CLI / 新版 OpenAI SDK 默认协议）。与 /v1/chat/completions 共用同一套鉴权、按量扣费、订阅窗口配额与长任务保活；支持流式与非流式。

请求示例（非流式）

curl https://yangdev.studio/v1/responses \
  -H "Authorization: Bearer sk-你的API-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": "用一句话介绍你自己",
    "max_output_tokens": 256
  }'

请求示例（流式）

curl -N https://yangdev.studio/v1/responses \
  -H "Authorization: Bearer sk-你的API-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": "hello",
    "stream": true,
    "max_output_tokens": 256
  }'

流式响应为 OpenAI Responses 的 typed SSE（如 response.created / response.output_text.delta / response.completed），与官方协议一致；最终 usage 在 response.completed 中返回并据此计费。

Python（openai 官方 SDK）

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的API-Key",
    base_url="https://yangdev.studio/v1",
)

resp = client.responses.create(
    model="gpt-5.6-terra",
    input="hello",
    max_output_tokens=256,
)
print(resp.output_text)

Codex / 第三方路由工具

若使用本机多模型路由（如 CC Switch MultiRouter），请将 上游 Provider 的地址配成公网 https://yangdev.studio（或带 /v1），不要把上游写成 http://127.0.0.1:…，否则会出现本地代理 502「上游连接失败」。

视频生成

视频生成是异步接口：提交任务后会立即返回任务 ID，随后通过状态接口轮询，完成后再下载视频内容。当前仅支持 payg 按量 key，订阅 key 调用会返回 VIDEO_PAYG_ONLY。支持多家上游（含 xAI Grok Imagine、百炼、火山方舟及聚合渠道模型）。

提交任务

curl -X POST https://yangdev.studio/v1/videos \
  -H "Authorization: Bearer sk-你的API-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1-lite",
    "prompt": "A golden retriever running on a sunny beach",
    "duration": 4,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

# xAI Grok Imagine 文生视频（官方同价，按秒计费）
curl -X POST https://yangdev.studio/v1/videos \
  -H "Authorization: Bearer sk-你的API-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A red balloon floating slowly against a blue sky",
    "duration": 5
  }'

查询状态 / 下载内容

状态为 completed 后，响应中的 unsigned_urls[0] 会指向本站代理下载地址，也可以直接请求 /v1/videos/{job_id}/content。轮询建议间隔 20–30 秒。

图生视频 / 参考图（首帧约束）

/v1/videos 对 OpenRouter 系列模型做字节级透传：仅校验 model 在白名单内，其余字段会原样转发到 OpenRouter /api/v1/videos。这意味着上游模型本身支持的图生视频 / 参考图入参（首帧、参考图 URL 等）可以直接附加在请求体里。

百炼系列(HappyHorse 1.0 + 通义万相 Wan)走独立异步通道,请求体是 OpenAI 风格的扁平字段(prompt / resolution / duration / seed);媒体输入字段按模式区分:

所有百炼系列共享同一计费规则:720P = ¥0.9 / 秒,1080P = ¥1.6 / 秒(at-cost,平价)。原生 1080p + 同步音轨。HappyHorse 支持 3–15 秒,Wan 支持 2–15 秒。

# 文生视频 (t2v)
curl -X POST https://yangdev.studio/v1/videos \
  -H "Authorization: Bearer sk-你的API-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-t2v",
    "prompt": "A cute cartoon horse runs forward joyfully on a sunny meadow",
    "resolution": "720P",
    "duration": 5
  }'

# 图生视频 (i2v) — 首帧约束
curl -X POST https://yangdev.studio/v1/videos \
  -H "Authorization: Bearer sk-你的API-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-i2v",
    "prompt": "Camera pans right, character walks forward",
    "image_url": "https://your-cdn.example.com/first-frame.jpg",
    "resolution": "720P",
    "duration": 5
  }'

# 参考图生视频 (r2v) — 多张参考(角色/风格)
curl -X POST https://yangdev.studio/v1/videos \
  -H "Authorization: Bearer sk-你的API-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-r2v",
    "prompt": "The character in the references dances in the street",
    "reference_images": [
      "https://your-cdn.example.com/ref1.jpg",
      "https://your-cdn.example.com/ref2.jpg"
    ],
    "resolution": "1080P",
    "duration": 5
  }'

# 视频编辑 (video-edit) — 在原视频上施加编辑指令
curl -X POST https://yangdev.studio/v1/videos \
  -H "Authorization: Bearer sk-你的API-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-video-edit",
    "prompt": "Change the background to a futuristic neon city at night",
    "video_url": "https://your-cdn.example.com/source.mp4",
    "resolution": "720P",
    "duration": 5
  }'

下列模型在上游 pricing_skus 中明确列出了独立的 image_to_video_* 计费档(即 yangdev 平台已知支持图生视频):

• kwaivgi/kling-v3.0-pro — 720p / 1080p
• kwaivgi/kling-v3.0-std — 720p / 1080p
• wan2.6-i2v — 720P / 1080P,通义万相原生图生视频
• happyhorse-1.0-i2v / happyhorse-1.0-r2v — 720P / 1080P,原生 1080p + 同步音轨

其余视频模型可能也支持图片输入（如 Veo、Sora、Seedance 系列），但当前未在 yangdev 平台做端到端验证。如需使用，请先用短任务确认上游接受请求体后再大规模调用。能否程序化判断某个模型是否带独立图生视频档：读取 GET /v1/videos/models 或 GET /pl/public/pricing 中该模型的 supports_image_input 字段（true 即上游显式列出 image_to_video_* 计费档）。

视频模型

"图生视频"列：✓ = 上游有独立 image_to_video_* 计费档；— = 上游目录未列出独立档（可能仍支持图片输入，需自行试跑确认）。

图片生成

另支持 POST /v1/images、POST /v1/images/edits。OpenAI 兼容 Images 接口：请求体用 prompt + 顶层 size / aspect_ratio，成功响应为 {created, data:[{b64_json|url}], usage?}。OpenClaw image_generate 等官方 Images 客户端应走这条，才能按指定宽高比出图。默认模型 openai/gpt-5.4-image-2，也认短名 gpt-image-2。

curl -X POST https://yangdev.studio/v1/images/generations \
  -H "Authorization: Bearer sk-你的API-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-image-2",
    "prompt": "电影感的雪山日落宽幅风景",
    "aspect_ratio": "16:9"
  }'

也可走 OpenAI 兼容对话接口出图。多数模型可设置 modalities 请求图片输出；xAI Grok Imagine 与 Seedream 等按张计费模型直接发对话请求即可。按量 key 直接出图；订阅 key 需挂图片资源包，否则返回 IMAGE_PAYG_ONLY。对话路径要控制尺寸，必须在请求体顶层（与 messages 平级）传 size / aspect_ratio，写在工具参数或提示词里不会生效。

curl -X POST https://yangdev.studio/v1/chat/completions \
  -H "Authorization: Bearer sk-你的API-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash-image",
    "modalities": ["image", "text"],
    "messages": [
      {"role": "user", "content": "生成一张赛博朋克风格的口袋龙虾海报"}
    ]
  }'

# xAI Grok Imagine 文生图（官方同价，按张计费，无需 modalities）
curl -X POST https://yangdev.studio/v1/chat/completions \
  -H "Authorization: Bearer sk-你的API-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image",
    "messages": [
      {"role": "user", "content": "A minimalist blue circle on white background"}
    ]
  }'

如果未显式传 modalities，平台会按模型能力自动补齐：纯图片模型使用 ["image"]，图片 + 文本模型使用 ["image","text"]。响应会保留 message.images 或流式图片增量。

图片模型

自定义宽高比 / 分辨率（16:9、4K 等）

在请求体顶层传以下任一参数即可控制出图尺寸（与 messages 平级），支持 16:9、9:16、4:3、21:9 等比例：

• aspect_ratio —— 宽高比，如 "16:9"、"9:16"、"4:3"、"1:1"（也兼容驼峰 aspectRatio）。
• resolution —— 分辨率档位 "1K" / "2K" / "4K"。
• size —— 显式像素，如 "2048x1152"、"3840x2160"。
• quality —— 画质档 "low" / "medium" / "high" / "auto"（默认 medium，按量计费随档位变化，追求更高清晰度可传 "high"）。gpt-image-2.5 另支持 xhigh / max。
• output_format —— png / jpeg / webp（视模型能力；不支持的型号可能仍回 PNG）。
• background —— auto / opaque / transparent。透明底请配 output_format=png 或 webp。gpt-image-2.5-* 支持真 alpha。
• output_compression —— JPEG/WebP 压缩 0–100。
• stream —— true 时 /v1/images* 返回 SSE（image_generation.partial_image / completed），不是整包 JSON。

图生图 / 参考图编辑：JSON 里传 image / images / input_references（http URL 或 data URL），或 multipart 文件字段 image / image[]。对话接口则在最后一条 user 消息里放 image_url / input_image 块。成功响应带 usage（prompt_tokens / completion_tokens / 明细 / cost）以及请求里的 quality。

curl -X POST https://yangdev.studio/v1/chat/completions \
  -H "Authorization: Bearer sk-你的API-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-image-2",
    "messages": [
      {"role": "user", "content": "电影感的雪山日落宽幅风景"}
    ],
    "aspect_ratio": "16:9",
    "resolution": "4K"
  }'

可用模型

获取当前可用模型列表，OpenAI 标准响应结构。

主力模型

以下模型为 yangdev 平台主力支持，覆盖率最高、延迟最低：

图片生成模型会出现在 payg key 的 GET /v1/models 响应中；视频生成模型可通过 GET /v1/videos/models 获取。两类媒体模型均仅 payg key 可调用。

模型定价

以下为按量计费的实际扣费价格，单位为 元（CNY）/ 百万 tokens：

主力模型定价

费用计算示例

费用 = (500 × 1.0 + 200 × 2.0) ÷ 1,000,000
     = 900 ÷ 1,000,000
     = ¥0.0009

费用 = (2000 × 17.25 + 800 × 103.5) ÷ 1,000,000
     = 117,300 ÷ 1,000,000
     ≈ ¥0.117

以初始额度 ¥50 为例，纯使用 qwen3.6-plus（按平均每次 500 输入 + 200 输出），约可调用 55,000+ 次；若纯使用 gpt-5.4 则约 400+ 次。混合使用以实际扣费为准。

错误处理

API 返回的错误信息包含 error_code 和 message 字段：

{
  "success": false,
  "error_code": "API_KEY_NOT_FOUND",
  "message": "API Key 不存在或已禁用"
}

Chat Completions 端点的错误遵循 OpenAI 兼容格式：

{
  "error": {
    "code": "TEMPORARY_UNAVAILABLE",
    "message": "请求被临时限流，请稍后重试 (temporary rate limit, please try again later)"
  }
}

完整错误码表

订阅模式相关错误（MODEL_NOT_PREMIUM / NO_ACTIVE_SUBSCRIPTION / PLAN_GROUP_DENIED 等）详见 订阅模式错误码。

速率限制

每个 API Key 的请求速率限制（按量计费 + OCR 共用）当前为 每分钟 120 次，可由管理员调整。

• 限制窗口：滑动窗口 60 秒
• 超限返回 HTTP 429，error_code: "RATE_LIMITED"
• 订阅模式额外受 5 小时 / 周 / 月窗口配额约束（详见 订阅模式）
• 建议在客户端实现指数退避重试策略；以 429 实际返回为准

Python SDK

基础用法

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的API-Key",
    base_url="https://yangdev.studio/v1",
)

# 非流式
response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "什么是量子计算？"}],
    temperature=0.7,
    max_tokens=1000,
)
print(response.choices[0].message.content)

# 流式
stream = client.chat.completions.create(
    model="qwen3.6-plus",
    messages=[{"role": "user", "content": "写一首诗"}],
    stream=True,
)
for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

查询账户余额

import requests

resp = requests.get(
    "https://yangdev.studio/v1/key/info",
    headers={"Authorization": "Bearer sk-你的API-Key"},
)
info = resp.json()
print(f"余额: ¥{info['balance']}")
print(f"今日调用: {info['calls_today']} 次")
print(f"预计剩余: {info['estimated_remaining_messages']} 次")

Node.js SDK

import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: 'sk-你的API-Key',
    baseURL: 'https://yangdev.studio/v1',
});

// 非流式
const response = await client.chat.completions.create({
    model: 'qwen3.6-plus',
    messages: [{ role: 'user', content: '你好' }],
});
console.log(response.choices[0].message.content);

// 流式
const stream = await client.chat.completions.create({
    model: 'qwen3.6-plus',
    messages: [{ role: 'user', content: '写一段代码' }],
    stream: true,
});
for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

cURL 示例

非流式请求

curl https://yangdev.studio/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的API-Key" \
  -d '{
    "model": "gpt-5.3-codex",
    "messages": [
      {"role": "system", "content": "你是一个编程助手"},
      {"role": "user", "content": "用 Python 写一个快排"}
    ],
    "temperature": 0.3
  }'

流式请求

curl -N https://yangdev.studio/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的API-Key" \
  -d '{
    "model": "qwen3.6-plus",
    "stream": true,
    "messages": [{"role": "user", "content": "讲个笑话"}]
  }'

查询余额

curl https://yangdev.studio/v1/key/info \
  -H "Authorization: Bearer sk-你的API-Key"

激活 Key

curl -X POST https://yangdev.studio/auth/activate \
  -H "Content-Type: application/json" \
  -d '{"api_key":"sk-你的Key","phone":"13800138000"}'

框架集成

LangChain

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-5.4",
    api_key="sk-你的API-Key",
    base_url="https://yangdev.studio/v1",
    temperature=0.7,
)

result = llm.invoke("用三句话解释相对论")
print(result.content)

LiteLLM

import litellm

response = litellm.completion(
    model="openai/qwen3.6-plus",
    messages=[{"role": "user", "content": "你好！"}],
    api_key="sk-你的API-Key",
    api_base="https://yangdev.studio/v1",
)

环境变量方式（推荐）

在终端设置环境变量后，支持 OpenAI SDK 的工具都能自动使用 yangdev：

export OPENAI_API_KEY="sk-你的API-Key"
export OPENAI_BASE_URL="https://yangdev.studio/v1"

第三方客户端接入

yangdev 的 /v1/chat/completions、/v1/responses 与 /v1/models 完全兼容 OpenAI 协议，任何支持自定义 OpenAI Base URL 的客户端均可直接接入，包括 Anthropic 模型 — 网关会自动完成 OpenAI ⇄ Anthropic 的格式转换（Claude 文本对话推荐 Chat Completions 或 /v1/messages）。以下提供常见工具的配置示例。

1. Claude Code CLI

Claude Code 是 Anthropic 官方推出的命令行 AI 编码 agent。通过设置 OpenAI 兼容端点，可直接以 yangdev 的 key 调用 opus4.7 / sonnet 等模型。

在 shell 中添加以下环境变量（推荐写入 ~/.zshrc 或 ~/.bashrc）：

export ANTHROPIC_BASE_URL="https://yangdev.studio"
export ANTHROPIC_AUTH_TOKEN="sk-你的API-Key"
export ANTHROPIC_MODEL="opus4.7"
export ANTHROPIC_SMALL_FAST_MODEL="qwen3.6-plus"

然后直接使用：

claude "帮我审查这个 PR 的安全性"

其中 ANTHROPIC_SMALL_FAST_MODEL 用于 Claude Code 内部的低成本子任务（如总结、索引），推荐设成 qwen3.6-plus 节省额度。

2. Cursor IDE

Cursor 支持自定义 OpenAI 兼容后端。打开 Settings → Models：

1. 在 OpenAI API Key 栏填入 sk-你的API-Key
2. 展开 Override OpenAI Base URL，填 https://yangdev.studio/v1，点击 Verify 验证
3. 在 Add model 中手动加入要用的模型 ID：qwen3.6-plus、gpt-5.4、opus4.7、gpt-5.3-codex 等
4. 关闭 Enable for ... (Anthropic / Google)，仅保留 OpenAI 作为后端，以避免 Cursor 调用原生 API

完成后在聊天框左下角选择对应模型即可使用。

3. Cline（VSCode / Roo Cline）

Cline（原 Claude Dev）是 VSCode 中最流行的 AI coding agent 插件之一。它原生支持 OpenAI-compatible 后端：

1. VSCode 左侧点击 Cline 图标 → 齿轮 Settings
2. API Provider 选 OpenAI Compatible
3. Base URL：https://yangdev.studio/v1
4. API Key：sk-你的API-Key
5. Model ID 填 gpt-5.3-codex（推荐用于 agent 任务）或 opus4.7
6. 勾选 Supports Images / Supports Computer Use 按需启用

Roo Cline（Cline 的 fork）配置方式完全相同。

4. opencode

opencode 是社区流行的终端 AI agent。编辑 ~/.config/opencode/config.json（或 macOS 的 ~/Library/Application Support/opencode/config.json）：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "yangdev": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://yangdev.studio/v1",
        "apiKey": "sk-你的API-Key"
      },
      "models": {
        "opus4.7":        { "name": "Opus 4.7" },
        "sonnet":         { "name": "Claude Sonnet" },
        "gpt-5.4":        { "name": "GPT-5.4" },
        "gpt-5.3-codex":  { "name": "GPT-5.3 Codex" },
        "qwen3.6-plus":   { "name": "Qwen 3.6 Plus" }
      }
    }
  },
  "model": "yangdev/opus4.7"
}

保存后在项目目录下执行 opencode 即可启动。可用 /model 命令在对话中切换。

5. ChatBox

ChatBox（桌面端 GUI 聊天客户端，支持 macOS / Windows / Linux / iOS / Android）：

1. 打开 Settings（设置）→ Model Provider（模型提供方）
2. Provider 选择：OpenAI API Compatible / 「自定义 OpenAI」
3. API Host：https://yangdev.studio/v1
4. API Key：sk-你的API-Key
5. 模型名称：手动添加并保存 qwen3.6-plus、gpt-5.6-terra、opus4.8、sonnet、haiku4.5、grok-4.6、grok-4.5、gemini-3.1-pro、gemini-3.7-flash 等（以文档白名单 / GET /v1/models 为准）
6. 保存 → 回到主界面，顶部选择模型即可对话

类似 GUI 客户端（Cherry Studio、LobeChat、NextChat、Jan 等）的配置流程基本一致：填 Base URL、填 Key、手动添加模型 ID。

6. Hermes / Nous Agent

Hermes 是 OpenAI-compatible 协议的轻量 agent CLI。在 ~/.hermes/config.yaml 中添加 provider：

providers:
  yangdev:
    type: openai
    base_url: "https://yangdev.studio/v1"
    api_key: "sk-你的API-Key"
    models: [opus4.8, sonnet, haiku4.5, gpt-5.6-terra, gpt-5.4, grok-4.6, grok-4.5, qwen3.6-plus, gemini-3.1-pro, gemini-3.7-flash]

default_model: "yangdev/opus4.7"

重新打开终端，hermes model 切换模型即可使用所有模型 — Claude 模型也走同一个 OpenAI 兼容 provider，无需另开 anthropic 通道。

其他支持 OpenAI 协议的工具

以下工具都可以用同样的方式接入（Base URL 一律填 https://yangdev.studio/v1，Key 填 sk-...）：

• Continue.dev（VSCode / JetBrains 代码助手）：config.json 里 "provider": "openai" + "apiBase": "https://yangdev.studio/v1"
• Aider：aider --openai-api-base https://yangdev.studio/v1 --openai-api-key sk-... --model openai/opus4.7
• Dify / FastGPT / Flowise：在 模型供应商 添加 OpenAI-Compatible，填 Base URL 和 Key
• LangChain / LlamaIndex / LiteLLM：参考上方 框架集成 章节
• OpenWebUI、AnythingLLM、Big-AGI 等开源 GUI 同理

口袋龙虾客户端

口袋龙虾是 yangdev 的配套移动 / 桌面客户端，集成了账户管理、AI 对话、OCR 等功能，开箱即用。

客户端配置

客户端首次使用流程

1. 在「设置」中填入 API 地址 https://yangdev.studio
2. 输入从代理商获得的 API Key
3. 输入手机号进行激活（可选填推荐人手机号）
4. 激活成功，获得 ¥50 初始额度，即可开始对话

更新日志

服务条款

使用 yangdev API 即视为同意以下条款：

• 合规使用：用户对自己使用 API 产生的内容负责，不得用于违法、骚扰、欺诈等用途。
• 账户安全：API Key 等同于账户密码，请勿在公开仓库 / 截图 / 论坛中暴露。Key 泄露导致的资金损失由用户自行承担。
• 计费规则：按量计费按 token 实际消耗扣费；订阅按窗口配额扣减；任何成功的 API 调用都会产生计费，包括因 client 中途断开但已生成 token 的调用。
• 退款政策：账户余额不退现；订阅未使用完毕的窗口配额不退款不顺延；如需服务变更或终止，请提前 3 个工作日通过 企业微信 联系。
• SLA：平台目标可用性 99.9%；遇模型提供方故障时网关会自动切换可用通道，但极端情况下仍可能短暂不可用 — 此类情况不视为违约。
• 条款变更：如有重大变更，会通过站内公告与企业微信群通知至少 7 天再生效。

yangdev API 文档 · v6 · 最后更新 2026-04-23 · 已适配 Claude Code / Cursor / Cline / opencode / ChatBox / Hermes 等 OpenAI 协议工具