OpenAI 兼容 API，支持多种编程语言接入
本平台提供与 OpenAI 兼容的 API 接口，您可以使用任何支持 OpenAI SDK 的客户端或 HTTP 库进行接入。
| 项目 | 说明 |
|---|---|
| 协议 | HTTPS |
| 数据格式 | JSON |
| 编码 | UTF-8 |
| Content-Type | application/json |
为了整体资源分配的公平性，同时防止恶意攻击，我们目前将基于账户的累计充值金额进行速率限制，具体如下表，如有更高需求请联系管理员。
| 用户等级 | 累计充值金额 | 并发 | RPM | TPM | TPD |
|---|---|---|---|---|---|
| 加载中... | |||||
| 指标 | 全称 | 说明 |
|---|---|---|
| 并发 | Concurrency | 同一时间内我们最多处理的来自您的请求数 |
| RPM | Requests Per Minute | 指一分钟内您最多向我们发起的请求数 |
| TPM | Tokens Per Minute | 指一分钟内您最多和我们交互的 token 数 |
| TPD | Tokens Per Day | 指一天内您最多和我们交互的 token 数 |
速率限制是 API 接口的常见做法，主要有以下几个考量：
我们将全力保障用户的正常使用，但当集群负载达到容量上限时，我们可能会采取临时的限流措施，对各类限速进行调整。代金券不计入累计充值总额。
| 模型名称 | 说明 | 统一价格 | 输入价格 | 输出价格 | 计费模式 | 峰谷定价 |
|---|---|---|---|---|---|---|
deepseekv4pro-0813 | DeepSeek V4 Pro - 最强推理能力 | 加载中... | ||||
deepseek-v4.1-flash-1017 | DeepSeek V4.1 Flash (1017) - 快速响应 + 多模态图片理解 + 1M上下文 | 加载中... | ||||
claude-opus-4-8 | Claude Opus 4.8 - Anthropic 最强模型 | 加载中... | ||||
claude-opus-4-7 | Claude Opus 4.7 - Anthropic 高级软件工程模型 | 加载中... | ||||
claude-fable-5 | Claude Fable 5 - Anthropic 迄今最强公开大模型，顶级推理+原生视觉 | 加载中... | ||||
gpt-5.5 | GPT-5.5 - OpenAI 旗舰模型，自主规划多步骤复杂任务 | 加载中... | ||||
gpt-5.6-luna | GPT-5.6 Luna - 最快最实惠，适合高容量延迟敏感工作负载 | 加载中... | ||||
gpt-5.6-sol | GPT-5.6 Sol - 高性能推理模型，复杂逻辑分析与代码生成 | 加载中... | ||||
gpt-5.6-terra | GPT-5.6 Terra - 平衡日常工作模型，低成本高性能 | 加载中... | ||||
glm-5.2 | GLM-5.2 - 智谱旗舰模型，1M上下文长程任务 | 加载中... | ||||
kimi-k2.6 | Kimi K2.6 - Moonshot 高级推理模型 | 加载中... | ||||
kimi-k3 | Kimi K3 - Moonshot 最强旗舰，2.8万亿参数，100万上下文，原生视觉 | 加载中... | ||||
gpt-image-2 | GPT-image-2 - OpenAI 图像生成（按 Token 计费） | 加载中... | ||||
gemini-3-pro-image-preview | Gemini 3 Pro Image Preview - Google 多模态图像生成（支持1K/2K/4K） | 加载中... | ||||
gemini-3.5-flash | Gemini 3.5 Flash - Google 快速文本对话模型 | 加载中... | ||||
qwen3.7-max | Qwen 3.7 Max - 阿里通义千问纯文本旗舰模型 | 加载中... | ||||
ZenAiVes3.0-Omni | ZenAiVes3.0-Omni - 上海鲸泽智模科技有限公司自研 Omni 多模态大模型，原生思考模式，1M 上下文，支持图片/视频输入 | 加载中... | ||||
doubao-seedance-2-0-260128 | Seedance 2.0 - 视频生成 | 加载中... | ||||
doubao-seedance-2-0-fast-260128 | Seedance 2.0 Fast - 快速视频生成 | 加载中... | ||||
doubao-seedance-2.5 | Seedance 2.5 - 长视频生成(支持30秒) | 加载中... | ||||
doubao-seedance-2-0-Professional Edition | Seedance 2.0 Professional - 专业版视频生成(需授权) | 加载中... | ||||
doubao-seedance-2-0-fast-Professional Edition | Seedance 2.0 Fast Professional - 专业版快速视频(需授权) | 加载中... | ||||
doubao-seedance-2.5-Professional Edition | Seedance 2.5 Professional - 专业版旗舰视频(需授权) | 加载中... |
部分模型支持峰谷定价：一天划分为峰、平、谷三个时段，各时段适用各自的输入价/输出价（统一价模型为统一价）。上表「峰谷定价」列展示各模型当前的时段划分与价格，并标注当前所处时段。
所有 API 请求需要在 HTTP Header 中携带 API Key 进行认证。本平台支持以下两种认证方式：
部分第三方工具（如 Claude Code、某些 IDE 插件）只支持 x-api-key 头部，可直接使用此方式认证，无需 Bearer 前缀。
API Key 可在本平台"API Keys"页面生成和管理。每个用户可以创建多个 API Key。
发送对话消息，获取 AI 回复。支持流式和非流式两种模式。
{
"model": "deepseek-v4.1-flash-1017",
"messages": [
{ "role": "system", "content": "You are a helpful assistant." },
{ "role": "user", "content": "Hello!" }
],
"stream": false
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型名称，如 deepseek-v4.1-flash-1017 |
messages | array | 是 | 消息数组，包含 role 和 content |
stream | boolean | 否 | 是否流式输出，默认 false |
max_tokens | integer | 否 | 最大生成 token 数 |
temperature | float | 否 | 采样温度，0-2，默认 1 |
top_p | float | 否 | 核采样，0-1 |
reasoning_effort | string | 否 | 思考强度：high 或 max |
extra_body.thinking | object | 否 | 启用思考模式：{ "type": "enabled" } |
deepseek-v4.1-flash-1017
支持图片理解。在 messages 的
content 中使用数组格式传入图片：
{
"model": "deepseek-v4.1-flash-1017",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "这张图片里有什么？"},
{"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}
]
}
],
"max_tokens": 1000
}
支持格式：data:image/xxx;base64,...（Base64）或 https://...（公网URL）
⚠️ deepseek-v4-pro 不支持图片理解，传入图片会返回 400 错误
部分模型支持多模态输入，可在对话中传入图片或视频 URL，模型将理解内容并作出回应。
| 模型 | 图片理解 | 视频理解 | 说明 |
|---|---|---|---|
gemini-3.5-flash | 支持 | 部分支持 | 通过 Gemini 原生 API 使用（OpenAI 兼容接口图片理解可用，视频理解建议走原生 API） |
claude-opus-4-8 | 支持 | 不支持 | 通过 Claude 原生 API 使用 |
claude-fable-5 | 支持（原生视觉） | 不支持 | Anthropic 迄今最强公开大模型，原生视觉理解 |
kimi-k3 | 支持 | 支持 | 100万上下文窗口，原生多模态（不支持关闭思考模式） |
qwen3.7-max | 纯文本，不支持多模态 | 如需多模态请使用 qwen3.7-plus（暂未接入） | |
{
"model": "gemini-3.5-flash",
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "描述这张图片的内容" },
{ "type": "image_url", "image_url": { "url": "https://example.com/image.jpg" } }
]
}
]
}
{
"model": "gemini-3.5-flash",
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "总结这个视频的主要内容" },
{ "type": "video_url", "video_url": { "url": "https://example.com/video.mp4" } }
]
}
]
}
{
"id": "chatcmpl-xxx",
"object": "chat.completion",
"created": 1699000000,
"model": "deepseek-v4-flash",
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! How can I help you today?"
},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 20,
"completion_tokens": 10,
"total_tokens": 30
}
}
| 字段 | 说明 |
|---|---|
prompt_tokens | 输入 token 数量 |
completion_tokens | 输出 token 数量 |
total_tokens | 总 token 数量（输入+输出） |
// 非流式请求 - 等待完整响应后返回 const axios = require('axios'); async function chat() { const response = await axios.post( 'https://www.yhapiplatform.com/v1/chat/completions', { model: 'deepseek-v4.1-flash-1017', messages: [ { role: 'system', content: 'You are a helpful assistant.' }, { role: 'user', content: 'Hello!' } ], stream: false }, { headers: { 'Authorization': 'Bearer sk-yhapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', 'Content-Type': 'application/json' } } ); console.log(response.data.choices[0].message.content); console.log('Tokens used:', response.data.usage.total_tokens); } chat().catch(console.error);
// 流式请求 - 逐字实时返回（推荐用于打字机效果） const axios = require('axios'); async function chatStream() { const response = await axios.post( 'https://www.yhapiplatform.com/v1/chat/completions', { model: 'deepseek-v4.1-flash-1017', messages: [{ role: 'user', content: 'Hello!' }], stream: true }, { headers: { 'Authorization': 'Bearer sk-yhapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', 'Content-Type': 'application/json' }, responseType: 'stream' } ); response.data.on('data', (chunk) => { const lines = chunk.toString().split('\n'); for (const line of lines) { if (!line.startsWith('data: ')) continue; const data = line.slice(6); if (data === '[DONE]') { console.log('\n[完成]'); return; } try { const json = JSON.parse(data); const content = json.choices?.[0]?.delta?.content; if (content) process.stdout.write(content); } catch (e) {} } }); } chatStream().catch(console.error);
import requests API_KEY = 'sk-yhapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' BASE_URL = 'https://www.yhapiplatform.com/v1' def chat(message): response = requests.post( f'{BASE_URL}/chat/completions', headers={ 'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json' }, json={ 'model': 'deepseek-v4.1-flash-1017', 'messages': [ {'role': 'system', 'content': 'You are a helpful assistant.'}, {'role': 'user', 'content': message} ], 'stream': False } ) result = response.json() reply = result['choices'][0]['message']['content'] tokens = result['usage']['total_tokens'] return reply, tokens reply, tokens = chat('Hello!') print(f'回复: {reply}') print(f'消耗 tokens: {tokens}')
import requests import json API_KEY = 'sk-yhapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' BASE_URL = 'https://www.yhapiplatform.com/v1' def chat_stream(message): response = requests.post( f'{BASE_URL}/chat/completions', headers={'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'}, json={'model': 'deepseek-v4.1-flash-1017', 'messages': [{'role': 'user', 'content': message}], 'stream': True}, stream=True ) for line in response.iter_lines(decode_unicode=True): if not line or not line.startswith('data: '): continue data = line[6:] if data == '[DONE]': break try: chunk = json.loads(data) content = chunk.get('choices', [{}])[0].get('delta', {}).get('content') if content: print(content, end='', flush=True) except json.JSONDecodeError: pass print() # 最后换行 chat_stream('Hello!')
| HTTP 状态码 | 错误类型 | 说明 | 解决方法 |
|---|---|---|---|
200 | 成功 | 请求成功 | - |
201 | 创建成功 | 资源创建成功（如注册） | - |
400 | 参数错误 | 请求参数有误（缺少必填项、格式错误、超出范围） | 检查请求参数是否符合要求 |
401 | 未授权 | API Key 无效或已过期，用户名/密码错误 | 检查 API Key 或账号密码是否正确 |
402 | 余额不足 | 账户余额不足，无法完成本次请求 | 联系管理员充值 |
403 | 禁止访问 | 账号或 API Key 被禁用，无权执行该操作 | 联系管理员 |
404 | 资源不存在 | 请求的资源不存在（如用户、任务、记录） | 确认资源 ID 是否正确 |
409 | 资源冲突 | 用户名已被注册 | 更换用户名 |
416 | 限速触发 | 超出用户等级限速（并发/RPM/TPM/TPD），返回 416 | 查看限速说明，联系管理员提升等级 |
429 | 请求过多 | 超出上游 API 速率限制 | 降低请求频率，稍后重试 |
500 | 服务器错误 | 平台内部服务器错误 | 稍后重试 |
502 | 网关错误 | 无法连接到上游服务（DeepSeek/Claude/火山方舟） | 检查上游服务状态，稍后重试 |
504 | 超时 | 请求上游超时 | 稍后重试或减小 max_tokens |
本平台所有模型均支持通过 response_format 参数要求模型以 JSON 格式返回结果。
在请求体中添加 response_format 参数：
{
"model": "deepseek-v4.1-flash-1017",
"messages": [
{"role": "system", "content": "你是一个数据提取助手"},
{"role": "user", "content": "提取张三的信息：28岁，住在北京市海淀区，邮箱 zhangsan@example.com"}
],
"response_format": {"type": "json_object"},
"stream": false
}
{
"name": "张三",
"age": 28,
"email": "zhangsan@example.com",
"address": "北京市海淀区"
}
| 模型 | 实现方式 | 说明 |
|---|---|---|
deepseekv4pro-0813 | 原生支持 | DeepSeek 官方 API 原生支持 response_format |
deepseek-v4.1-flash-1017 | 原生支持 | DeepSeek 官方 API 原生支持 response_format |
claude-opus-4-8 | 自动注入 system 提示 | Claude 上游不支持该参数，平台自动在 system 提示中注入 JSON 格式要求 |
在使用 /v1/messages (Anthropic 原生格式) 时同样支持：
{
"model": "claude-opus-4-8",
"messages": [{"role": "user", "content": "以JSON格式返回用户信息"}],
"max_tokens": 4096,
"response_format": {"type": "json_object"}
}
response_format 参数，不会透传到上游启用思考模式后，模型会在回复前进行深度推理。适合复杂数学、编程、逻辑分析等场景。
在请求体中添加以下两个参数（所有模型通用）：
{
"model": "deepseek-v4.1-flash-1017",
"messages": [{"role": "user", "content": "Solve this math problem"}],
"stream": false,
"reasoning_effort": "high",
"extra_body": {
"thinking": {"type": "enabled"}
}
}
claude-opus-4-8、claude-fable-5、gpt-5.5、gpt-5.6-sol 支持上述思考模式参数，后端会自动适配。思考内容的显示取决于模型自身的支持情况。
kimi-k3 始终处于思考模式，无法关闭，无需传递 thinking 参数。 gpt-5.6-luna 和 gpt-5.6-terra 为平衡/快速模型，思考模式支持取决于上游配置。
启用思考模式后，响应的 message 对象（或流式响应的 delta）会额外包含 reasoning_content 字段：
"message": {
"role": "assistant",
"reasoning_content": "Let me think step by step...",
"content": "The answer is 42."
}
kimi-k2.6 和 kimi-k3 由 Moonshot AI 提供。平台对 Kimi 系列做了参数兼容处理，使用时请注意以下特殊限制：
| 参数 | 约束 | 说明 |
|---|---|---|
temperature | 部分线路固定为 1 | 该线路仅接受 1，其他值会报错；平台会按当前线路自动修正，用户无需处理 |
top_p | 部分线路固定为 0.95 | 平台自动修正 |
n | 固定为 1 | 不支持一次生成多条回复 |
presence_penalty | 固定为 0 | 不支持 |
frequency_penalty | 固定为 0 | 不支持 |
max_tokens | 默认 32768 | 未传时平台自动设置 |
kimi-k3 已接入平台线路调度（单资源/多资源/直供线路），管理员可在后台切换线路；各线路计费口径一致。参数约束仅在需要修正的线路上自动生效，其余线路按用户传入值原样执行。kimi-k3 是 Moonshot 迄今最强旗舰模型，具备以下特性：
/v1/chat/completions 时无需（也不应）传递 thinking 或 reasoning_effort 参数，模型会自动返回 reasoning_content。调用 /v1/responses 时可通过 reasoning.effort 控制思考强度（详见 Responses 接口章节）。kimi-k3 的 /v1/responses 通道正在对接中，当前请使用 /v1/chat/completions（文本/视觉/工具调用/思考全功能）。开放后将在 Responses 接口 章节同步更新。
Kimi K2.6 和 K3 均支持图片和视频理解。在 messages 中使用数组格式的 content 传入 image_url 或 video_url 类型即可。
按实际返回的 usage.total_tokens 计费。流式响应中 usage 位于最后一个 chunk 的 choices[0].usage 中，平台已自动适配解析。
本平台同时提供 Anthropic 原生格式的 API 端点，适用于 Claude Code、Claude Desktop 等仅支持 Anthropic SDK 的工具。
claude-opus-4-8 和 claude-fable-5 模型。其他模型请使用 OpenAI 兼容接口 /v1/chat/completions。与 OpenAI 兼容接口相同，使用 API Key 认证：
Authorization: Bearer <your_api_key>
Content-Type: application/json
anthropic-version: 2023-06-01 // 可选，兼容性头部
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型名称：claude-opus-4-8 |
messages | array | 是 | 对话消息列表，格式 [{"role": "user", "content": "Hello"}] |
max_tokens | integer | 是 | 生成最大 token 数 |
stream | boolean | 否 | 是否流式输出，默认 false |
system | string | 否 | 系统提示词 |
temperature | number | 否 | 采样温度 0-1，默认 1.0 |
top_p | number | 否 | 核采样参数 0-1 |
thinking | object | 否 | 思考模式：{"type": "enabled", "budget_tokens": 16000} |
curl -X POST "https://www.yhapiplatform.com/v1/messages" \
-H "Authorization: Bearer sk-yhapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-opus-4-8",
"messages": [{"role": "user", "content": "Hello"}],
"max_tokens": 4096,
"thinking": {"type": "enabled", "budget_tokens": 16000}
}'
{
"id": "msg_01AbC...",
"type": "message",
"role": "assistant",
"model": "claude-opus-4-8",
"content": [
{
"type": "thinking",
"thinking": "The user said hello, I should respond warmly."
},
{
"type": "text",
"text": "Hello! How can I help you today?"
}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 13,
"output_tokens": 25
}
}
Claude Code 和 OpenAI Codex 的详细配置请参考下方独立章节。
Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手。通过配置接入本平台，即可使用 Claude Opus 4.8 模型进行代码编写、调试和项目管理。
# 使用 npm 全局安装 npm install -g @anthropics/claude-code # 验证安装 claude --version
在本平台用户中心生成 API Key，然后设置以下环境变量：
# 填入你从本平台获取的 API Key
export ANTHROPIC_API_KEY="sk-yhapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export ANTHROPIC_BASE_URL="https://www.yhapiplatform.com"
~/.bashrc 或 ~/.zshrc，避免每次重启终端后重新设置。
# 在项目目录中启动 cd /path/to/your/project claude # 或使用 --dangerously-skip-permissions 跳过权限检查（首次使用） claude --dangerously-skip-permissions
启动后，输入以下指令验证是否正常工作：
检查你的模型版本和可用功能
如果 Claude 回复了内容且未报错，说明配置成功。如果提示权限问题，请检查 API Key 是否有效、余额是否充足。
| 问题 | 解决方案 |
|---|---|
| 提示 Invalid API Key | 确认 ANTHROPIC_API_KEY 是从本平台用户中心复制的完整 Key，且未过期 |
| 提示余额不足 | 联系管理员充值，或在用户中心查看余额 |
| 连接超时 | 检查网络是否能访问 www.yhapiplatform.com，必要时配置代理 |
| 回复缓慢或中断 | 这是流式传输正常现象，与网络环境有关 |
| 无法使用代码编辑功能 | 确认模型为 claude-opus-4-8，只有该模型支持完整的代码编辑能力 |
OpenAI Codex 是 OpenAI 推出的代码生成模型。由于 Codex 需要 OpenAI 官方的特殊权限和端点，本平台暂不支持 Codex 模型。但你可以通过以下替代方案实现类似功能：
/v1/codex 端点。本平台提供的是对话式模型，不具备 Codex 的实时代码执行环境。
Claude Opus 4.8 的编程能力不逊于 Codex，推荐在以下场景中使用：
Cursor 是支持自定义 API 的 AI 编程 IDE，可直接接入本平台：
1. 下载安装 Cursor: https://cursor.sh 2. 打开设置 (Ctrl+,) → Models 3. 添加自定义模型: - API Key: sk-yhapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - Base URL: https://www.yhapiplatform.com/v1 - Model: claude-opus-4-8 4. 保存后即可在编辑器中使用
Continue 是开源的 AI 编程助手插件，支持自定义 API：
{
"models": [
{
"title": "YHAPI Claude",
"provider": "openai",
"model": "claude-opus-4-8",
"apiKey": "sk-yhapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"apiBase": "https://www.yhapiplatform.com/v1"
}
]
}
如果你已有 GitHub Copilot，可通过以下方式增强：
1. 安装 "Copilot Chat" 扩展 2. 在聊天框中输入 /help 查看支持的指令 3. 对于复杂任务，切换到 Claude Opus 4.8 获得更好的代码理解能力
使用以下系统提示词可获得更好的编程体验：
你是一个专业的全栈开发工程师，擅长代码编写、调试和重构。要求： 1. 代码必须附带清晰的注释 2. 优先使用现代最佳实践 3. 考虑边界条件和错误处理 4. 如需修改多文件，列出每个文件的变更
本平台支持 OpenAI /v1/responses 接口，与 Chat Completions 接口并行提供。该接口支持流式 SSE 和非流式响应，特别适合 GPT-5.5 等需要 Responses 格式的模型。
| 接口 | 方法 | 说明 |
|---|---|---|
/v1/responses | POST | 创建对话任务（流式/非流式） |
/v1/responses/{response_id} | GET | 检索已存储的响应（需创建时 store=true） |
/v1/responses/{response_id} | DELETE | 删除已存储的响应 |
/v1/responses/{response_id}/input_items | GET | 查询生成该响应的输入项列表（支持 after/limit/order 分页参数） |
Authorization: Bearer <your_api_key> 头部中传入。支持 GPT-5.5/5.6 系列、Claude 系列、glm-5.2（DeepSeek 系列与 Kimi 系列暂不支持，kimi-k3 的 Responses 支持待服务端开放后自动生效）。已存储响应的检索/删除/输入项查询端点仅对 Responses 通道内创建的响应有效。| 模型 | 说明 |
|---|---|
gpt-5.5 | OpenAI 旗舰模型，自主规划多步骤复杂任务 |
gpt-5.6-luna | 最快最实惠，适合高容量延迟敏感工作负载 |
gpt-5.6-sol | 高性能推理模型，复杂逻辑分析与代码生成 |
gpt-5.6-terra | 平衡日常工作模型，低成本高性能 |
claude-opus-4-8 | Anthropic 最强模型 |
claude-opus-4-7 | Anthropic 高级软件工程模型 |
claude-fable-5 | Anthropic 迄今最强公开大模型，顶级推理+原生视觉 |
glm-5.2 | 智谱旗舰模型，1M上下文长程任务 |
/v1/chat/completions（文本/视觉/工具调用/思考全功能支持）。| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型名称，如 gpt-5.5、kimi-k3 |
input | string/array | 是 | 用户输入，字符串或消息数组 |
instructions | string | 否 | 系统指令，插入上下文起始位置 |
stream | boolean | 否 | 是否流式返回，默认 false |
temperature | number | 否 | 采样温度 0-2 |
max_tokens | number | 否 | 最大生成 token 数（也可用 max_output_tokens） |
reasoning | object | 否 | 思考强度：{ "effort": "low|medium|high|max" }（kimi-k3 支持） |
tools | array | 否 | 工具定义列表（自定义 function 工具） |
tool_choice | string/object | 否 | 工具选择策略 |
previous_response_id | string | 否 | 多轮对话上下文 ID（上一轮响应的 id，有效期 7 天） |
store | boolean | 否 | 是否存储本次响应供后续检索，默认 true |
metadata | object | 否 | 自定义元数据 |
{
"model": "gpt-5.5",
"input": [
{ "role": "user", "content": "请帮我写一个 Python 快速排序算法" }
],
"stream": true,
"max_tokens": 4096
}
当 stream: true 时，接口返回 SSE 流。每个事件以 data: 开头，事件类型包括：
| 事件类型 | 说明 |
|---|---|
response.created | 响应开始 |
response.output_text.delta | 文本增量 |
response.reasoning_text.delta | 思考过程增量 |
response.completed | 响应完成（含 usage） |
const axios = require('axios'); const API_KEY = 'sk-yhapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'; const BASE_URL = 'https://www.yhapiplatform.com'; async function responsesStream() { const response = await axios.post( `${BASE_URL}/v1/responses`, { model: 'gpt-5.5', input: [{ role: 'user', content: '你好，请介绍一下自己' }], stream: true }, { headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }, responseType: 'stream' } ); response.data.on('data', (chunk) => { const lines = chunk.toString().split('\n'); for (const line of lines) { if (line.startsWith('data:')) { const data = line.replace('data:', '').trim(); if (data === '[DONE]') { console.log('完成'); return; } try { const event = JSON.parse(data); if (event.choices?.[0]?.delta?.content) { process.stdout.write(event.choices[0].delta.content); } } catch (e) {} } } }); } responsesStream().catch(console.error);
input 替代 messages 传递对话内容previous_response_id 实现多轮对话上下文/v1/chat/completions/v1/chat/completions（文本/视觉/工具调用/思考全功能）。Responses 接口对该模型开放后本文档将同步更新。本平台集成了 OpenAI GPT-image-2 和 Google Gemini 3 Pro Image Preview 图像生成模型，可通过兼容 OpenAI 的 API 接口创建图片生成任务。
| 接口 | 方法 | 说明 |
|---|---|---|
/v1/images/generations | POST | 创建图片生成任务（需API Key） |
Authorization: Bearer <your_api_key> 头部中传入。| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
model | string | 是 | gpt-image-2 | 模型名称：gpt-image-2 或 gemini-3-pro-image-preview |
prompt | string | 是 | - | 期望生成图像的文本描述 |
n | number | 否 | 1 | 生成图像数量，范围 1~10 |
size | string | 否 | auto | 图片尺寸（像素格式或比例格式，见下方说明） |
quality | string | 否 | auto | 图片质量：high、medium、low、auto，Gemini 额外支持 1K、2K、4K |
| 格式 | 支持的值 | 适用模型 |
|---|---|---|
| 像素格式（标清） | 1024x1024、1536x1024、1024x1536 | GPT-image-2 |
| 像素格式（2K） | 2048x2048、2048x1152、1152x2048 | GPT-image-2 |
| 像素格式（4K） | 3840x2160、2160x3840（最大边长 3840px） | GPT-image-2 |
| 比例格式 | 1:1、16:9、9:16、4:3、3:4、3:2、2:3 | Gemini 3 Pro Image |
| 画质值 | 说明 | 适用模型 |
|---|---|---|
auto | 自动选择最佳画质 | 全部 |
high | 高画质 | 全部 |
medium | 中等画质 | 全部 |
low | 低画质 | 全部 |
1K | 1024px 短边 | Gemini 3 Pro Image |
2K | 2048px 短边 | Gemini 3 Pro Image |
4K | 4096px 短边 | Gemini 3 Pro Image |
| 字段 | 类型 | 说明 |
|---|---|---|
created | integer | 创建时间戳 |
data | array | 生成的图片列表 |
data[].b64_json | string | Base64 编码的图片数据（PNG格式） |
output_format | string | 输出格式：png |
quality | string | 实际使用的质量等级 |
size | string | 输出图片尺寸 |
usage.prompt_tokens | integer | 输入 token 数 |
usage.completion_tokens | integer | 输出 token 数 |
usage.total_tokens | integer | 总 token 数（用于计费） |
const axios = require('axios'); const fs = require('fs'); const API_KEY = 'sk-yhapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'; const BASE_URL = 'https://www.yhapiplatform.com'; async function generateImage() { const response = await axios.post( `${BASE_URL}/v1/images/generations`, { model: 'gpt-image-2', prompt: 'A photograph of a red fox in an autumn forest', n: 1, size: '1024x1024', quality: 'auto' }, { headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }, timeout: 300000 } ); const result = response.data; console.log('Usage:', result.usage); // 保存 Base64 图片 if (result.data && result.data[0] && result.data[0].b64_json) { const base64 = result.data[0].b64_json; fs.writeFileSync('output.png', Buffer.from(base64, 'base64')); console.log('图片已保存为 output.png'); } } generateImage().catch(console.error);
usage.total_tokens 计费本平台支持 GPT-image-2 图片编辑功能，可通过上传本地图片并配合提示词进行图像编辑、风格转换、内容修改等操作。支持单图和多图（最多16张）编辑。
| 接口 | 方法 | 说明 |
|---|---|---|
/v1/images/edits | POST | 创建图片编辑任务（需API Key，multipart/form-data） |
multipart/form-data 格式提交，不支持 JSON。图片通过 image 字段以文件方式上传，不支持 URL 或 Base64。| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
model | string | 是 | gpt-image-2 | 模型名称，固定为 gpt-image-2 |
prompt | string | 是 | - | 期望编辑图像的文本描述 |
image | file | 是 | - | 上传图片文件（支持 png/jpg/webp/gif） |
image[] | file | 否 | - | 上传多张图片（最多16张），用于多图编辑 |
n | number | 否 | 1 | 生成图像数量，范围 1~10 |
size | string | 否 | auto | 输出尺寸：1024x1024、1536x1024、1024x1536、auto |
quality | string | 否 | auto | 图片质量：high、medium、low、auto |
# 单图编辑 curl -X POST "BASE_URL/v1/images/edits" \ -H "Authorization: Bearer $API_KEY" \ -F "model=gpt-image-2" \ -F "prompt=Make this black and white" \ -F "image=@/path/to/image.png" # 多图编辑（最多16张） curl -X POST "BASE_URL/v1/images/edits" \ -H "Authorization: Bearer $API_KEY" \ -F "model=gpt-image-2" \ -F "prompt=Merge these two images into one, side by side" \ -F "image=@image1.png" \ -F "image=@image2.png"
async function editImage(file, prompt) { const formData = new FormData(); formData.append('model', 'gpt-image-2'); formData.append('prompt', prompt); formData.append('image', file); const res = await fetch(`BASE_URL/v1/images/edits`, { method: 'POST', headers: { 'Authorization': `Bearer API_KEY` }, body: formData }); const data = await res.json(); // 保存 Base64 图片 if (data.data && data.data[0]?.b64_json) { const buffer = Buffer.from(data.data[0].b64_json, 'base64'); require('fs').writeFileSync('edited.png', buffer); console.log('编辑完成，已保存为 edited.png'); } } // 使用：传入 File 对象 // editImage(fileInput.files[0], '将红色方块变成蓝色，背景改为白色');
{
"background": "opaque",
"created": 1780036809,
"data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." }],
"output_format": "png",
"quality": "medium",
"size": "1024x1024",
"usage": {
"prompt_tokens": 88,
"completion_tokens": 196,
"total_tokens": 284
}
}
multipart/form-data 格式，不支持 JSON bodyusage.total_tokens 计费除 OpenAI 兼容接口外，本平台还支持 Google Gemini 原生 API 格式，可直接使用 Gemini 官方 SDK 或工具对接。
| 接口 | 方法 | 说明 |
|---|---|---|
/v1beta/models/{model}:generateContent | POST | 非流式文本生成 |
/v1beta/models/{model}:streamGenerateContent | POST | 流式文本生成 |
Authorization: Bearer <your_api_key> 头部中传入。| 模型路径参数 | 说明 |
|---|---|
gemini-3.5-flash | 快速文本对话模型 |
gemini-3-pro-image-preview | 多模态图像生成模型 |
{
"contents": [
{
"role": "user",
"parts": [{ "text": "请用中文介绍一下机器学习的基本概念" }]
}
],
"generationConfig": {
"temperature": 0.7,
"maxOutputTokens": 2048
}
}
const axios = require('axios'); const API_KEY = 'sk-yhapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'; const BASE_URL = 'https://www.yhapiplatform.com'; async function geminiChat() { const response = await axios.post( `${BASE_URL}/v1beta/models/gemini-3.5-flash:generateContent`, { contents: [ { role: 'user', parts: [{ text: 'Hello, how are you?' }] } ] }, { headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' } } ); const candidate = response.data.candidates[0]; console.log('Reply:', candidate.content.parts[0].text); console.log('Usage:', response.data.usageMetadata); } geminiChat().catch(console.error);
ZenAiVes3.0-Omni 是上海鲸泽智模科技有限公司自主研发的 Omni 多模态大模型：最大上下文 1,048,576 tokens（1M），原生思考模式，支持图片输入与视频输入。调用方式与标准对话接口完全一致（POST /v1/chat/completions），模型名填 ZenAiVes3.0-Omni 即可。
ZenAiVes3.0-Omni 默认开启思考，思考与正文原生分离，客户端按标准 OpenAI 格式解析即可：
message.reasoning_content，正文在 message.contentdelta.reasoning_content、正文走 delta.content，finish_reason 语义不变"extra_body": {"chat_template_kwargs": {"enable_thinking": false}}，此时只有 content 有值completion_tokens 计费（usage.reasoning_tokens 返回思考部分数量）；多轮对话命中前缀缓存时 usage.prompt_tokens_details.cached_tokens 返回命中数（自动省钱省时）支持三档思考强度，通过 reasoning_effort 参数控制（平台自动转换，客户端直接用 OpenAI 风格取值即可）：
| reasoning_effort | 说明 | token 消耗 |
|---|---|---|
"xhigh" 或 "high" 或 "max"（默认） | 深度思考，最彻底的推理链 | 最高 |
"medium" | 中等思考，速度与质量平衡 | 中等 |
"low" | 轻量思考，快速出答案 | 最低 |
high / max → 上游的 xhigh；medium / low 原值透传。不传此参数时默认 xhigh。OpenAI 风格的 thinking 对象（extra_body 里的）会被平台自动清理，不会导致报错。请求不传 temperature / top_p / top_k 时，使用模型 generation_config.json 的官方思考模式默认值：temperature 1.0 / top_p 0.95 / top_k 20。请求显式传了则覆盖默认（一切以请求为准）：
| 场景 | 建议传值 | 说明 |
|---|---|---|
| 默认思考模式 | 不传（用官方默认 1.0 / 0.95 / 20） | 官方思考模式推荐采样参数，效果最佳 |
| 打榜评测 | temperature: 0.1 | 低温度确定性输出 |
| 关闭思考场景 | temperature: 0.7 | 非思考模式官方推荐值 |
top_k 为 ZenAiVes3.0-Omni 专属透传参数（OpenAI 标准参数之外），可直接顶层传或放 extra_body 中；其他模型不支持此参数。content 使用数组结构，image_url.url 支持公网 https 直链或 Base64（data:image/jpeg;base64,...，推荐前端 FileReader 读取本地文件转换）；多图就放多个 image_url 块。
{
"model": "ZenAiVes3.0-Omni",
"messages": [{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}},
{"type": "text", "text": "这张图里有什么？"}
]
}],
"temperature": 0.3,
"max_tokens": 1024
}
与图片同理，video_url.url 传 data:video/mp4;base64,... 或公网直链。视频 token 消耗较大（约每秒 2 帧 × 每帧数百 token），建议控制在 1~2 分钟内，长视频建议先抽帧再发。
{
"model": "ZenAiVes3.0-Omni",
"messages": [{
"role": "user",
"content": [
{"type": "video_url", "video_url": {"url": "data:video/mp4;base64,AAAA..."}},
{"type": "text", "text": "视频里发生了什么？"}
]
}],
"temperature": 0.3
}
| 场景 | temperature | max_tokens |
|---|---|---|
| 默认思考模式（日常/长文/代码） | 不传（官方默认 1.0，配 top_p 0.95 / top_k 20） | 2048 ~ 4096+ |
| 打榜评测 | 0.1（显式传） | 按榜要求 |
| 关闭思考场景 | 0.7（显式传） | 2048 |
from openai import OpenAI client = OpenAI( base_url='https://www.yhapiplatform.com/v1', api_key='sk-yhapi-xxx' ) # 普通对话（默认开思考：不传 temperature 用官方默认 1.0/0.95/20） resp = client.chat.completions.create( model='ZenAiVes3.0-Omni', messages=[{'role': 'user', 'content': '介绍下你自己'}], max_tokens=2048 ) msg = resp.choices[0].message print('思考:', getattr(msg, 'reasoning_content', None)) print('回答:', msg.content) # 关闭思考（直接出答案，更快更省；非思考场景官方推荐 temperature 0.7） resp = client.chat.completions.create( model='ZenAiVes3.0-Omni', messages=[{'role': 'user', 'content': '1+1等于几？'}], extra_body={'chat_template_kwargs': {'enable_thinking': False}}, temperature=0.7 ) print(resp.choices[0].message.content)
ZenAiVes3.0-Omni（Z、A、V、O 大写）。计费按实际 token 用量（思考计入输出），缓存命中按平台缓存价格体系折扣。ZenAiVes3.0-Omni 同时支持以下端点：POST /v1/chat/completions（标准 OpenAI 兼容）、POST /v1/responses（OpenAI Responses API，含流式 SSE 与工具调用）、POST /v1/messages（Anthropic 原生协议，Claude Code 等客户端可直接使用）。三个端点的思考模式行为一致：reasoning_effort 参数均自动映射（high/max → xhigh，medium/low 原值透传），thinking 对象自动清理。视频输入建议 ≤2 分钟（base64 直传或公网直链均可），更长视频建议先抽帧。本平台集成 Seedance 2.0 / 2.5 系列视频生成模型，接口与官方文档完全同构（model + prompt + metadata.content[]），支持文生视频、图生视频（首帧/首尾帧）、多模态参考生视频、音频驱动，以及 2.5 的视频延长/编辑。支持生成与画面同步的音频。
| 模型名称 | 说明 | 分辨率 | 时长 |
|---|---|---|---|
doubao-seedance-2-0-260128 | 标准版，画质更优（约5-8分钟） | 480p / 720p / 1080p / 4k | 4~15秒 |
doubao-seedance-2-0-fast-260128 | 快速版（约3-4分钟） | 480p / 720p | 4~15秒 |
doubao-seedance-2-0-mini-260615 | 精简版，成本更低、速度更快 | 480p / 720p | 4~15秒 |
doubao-seedance-2-5-260628 | 2.5：素材上限50个、原生多语言、视频延长/编辑、纯音频参考 | 480p / 720p | 4~30秒 |
doubao-seedance-2.5（等同 2-5-260628）。1080p 与 4k 仅标准版支持。| 接口 | 方法 | 说明 |
|---|---|---|
/v1/video/generations | POST | 提交视频生成任务（官方格式） |
/v1/video/generations/{task_id} | GET | 查询任务状态与结果 |
/v1/video/tasks | GET | 按令牌获取视频任务列表（支持状态/时间范围/分页过滤） |
/v1/videos/{task_id}/content | GET | 视频内容稳定地址（可直接下载/播放，支持断点续传） |
Authorization: Bearer <your_api_key>。旧端点 /api/video/create、/api/video/status/:taskId、/api/video/list 继续可用，存量集成无需改动。| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型名称（见上表） |
prompt | string | 是 | 提示词（平台校验要求非空；未传 metadata.content 时自动转换为 content 文本） |
metadata | object | 是 | 扩展参数对象，见下表 |
| metadata 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
content | object[] | 是 | - | 输入内容数组（文本/图片/音频/视频），见下 |
generate_audio | boolean | 否 | true | 是否生成同步音频 |
resolution | string | 否 | 720p | 480p / 720p / 1080p / 4k（高分辨率仅标准版） |
ratio | string | 否 | adaptive | 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive |
duration | integer | 否 | 5 | 时长（秒）；-1 为智能时长（实际时长以查询返回为准） |
tools | object[] | 否 | - | 如 [{"type":"web_search"}] 联网搜索（仅标准版/快速版，仅文生视频） |
output_format | string | 否 | mp4 | mp4 / mov（仅 2.5；延长/拼接/调色建议 mov） |
omni_reference_task_type | string | 否 | auto | auto / reference / edit / extend（仅 2.5；显式指定可提前校验参数限制） |
| 类型 | 结构 | 说明 |
|---|---|---|
| 文本 | {"type":"text","text":"..."} | 提示词（建议中文≤500字） |
| 图片 | {"type":"image_url","image_url":{"url":"..."},"role":"..."} | url 支持 公网URL / Base64(data:image/...) / asset://素材ID；role：first_frame（首帧1张）、last_frame（尾帧，与首帧成对）、reference_image（参考图：2.0系列1~9张，2.5最多30张） |
| 视频 | {"type":"video_url","video_url":{"url":"..."},"role":"reference_video"} | mp4/mov，480p/720p，单个2~15秒；2.0系列最多3个（总时长≤15s），2.5最多10个 |
| 音频 | {"type":"audio_url","audio_url":{"url":"..."},"role":"reference_audio"} | wav/mp3，单个2~15秒；2.0系列最多3段（不可单独输入），2.5最多10段且支持纯音频参考 |
{
"model": "doubao-seedance-2-0-260128",
"prompt": "果茶广告",
"metadata": {
"content": [{ "type": "text", "text": "全程第一人称视角果茶宣传广告" }],
"duration": 8,
"resolution": "480p",
"ratio": "9:16",
"generate_audio": true
}
}
图生视频（首帧，素材引用）：
{
"model": "doubao-seedance-2-0-fast-260128",
"prompt": "人物微笑挥手",
"metadata": {
"content": [
{ "type": "image_url", "image_url": { "url": "asset://asset-20260427120130-ngtck" }, "role": "first_frame" }
],
"duration": 5, "resolution": "720p", "ratio": "adaptive"
}
}
响应（HTTP 200）：
{ "task_id": "cgt-20260326182734-68xp4" }
content.video_url；余额不足返回 402，充值后重新查询即可拿到视频。失败任务不计费。生成成功响应：
{
"code": "success",
"data": {
"task_id": "cgt-20260326182734-68xp4",
"status": "SUCCESS",
"progress": "100%",
"data": {
"model": "doubao-seedance-2-0-260128",
"ratio": "9:16", "duration": 8, "resolution": "480p",
"generate_audio": true, "framespersecond": 24,
"content": { "video_url": "https://...mp4?..." },
"usage": { "total_tokens": 80770, "completion_tokens": 80770 }
}
}
}
任务状态：NOT_START（已提交未开始）/ IN_PROGRESS（生成中，带 progress 如 "30%"）/ SUCCESS / FAILURE（看 fail_reason）。查询不存在的任务返回 404。
按当前令牌拉取视频任务列表，全部参数走 URL Query：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
status | string | 否 | NOT_START / SUBMITTED / QUEUED / IN_PROGRESS / SUCCESS / FAILURE / UNKNOWN |
start_timestamp | int | 否 | 提交时间下界（Unix 秒） |
end_timestamp | int | 否 | 提交时间上界（Unix 秒） |
p | int | 否 | 页码，从 1 开始（默认 1） |
page_size | int | 否 | 每页条数，默认 10，最大 100 |
响应示例：
{
"success": true,
"message": "",
"data": {
"page": 1, "page_size": 10, "total": 4433,
"items": [{
"user_id": 1, "task_id": "cgt_b514b218_81515",
"submit_time": 1783500697, "start_time": 0, "finish_time": 1783500732,
"token_id": 8774, "status": "SUCCESS", "progress": "100%",
"fail_reason": "https://www.yhapiplatform.com/v1/videos/cgt_b514b218_81515/content",
"prompt_tokens": 0, "completion_tokens": 0
}]
}
}
任务列表与文档中的视频地址均指向本端点：任务已结算即可直接访问（浏览器/下载器可打开，支持 Range 断点续传）；未结算返回 403（先调查询接口完成结算）。请以本地址作为长期入口（签名地址有时效）。
素材库用于管理视频生成所需的图片、视频、音频素材。上传后的素材获得 asset:// 引用地址（真实素材ID直通，ID 全生命周期不变），可直接用于视频生成的 content 参数。素材按令牌隔离：用哪个令牌的 API Key 创建，素材就归属该令牌，只能操作自己的素材。
asset-yh-*）仍可正常查询/删除/用于视频生成（平台自动只读翻译为真实ID）；查询单个素材时若传入包装ID，响应会额外附 real_id 字段（上游真实 asset-ID，便于对账）。新上传的素材一律直接返回真实ID，无此字段。| 接口 | 方法 | 说明 |
|---|---|---|
/v1/assets | POST | 创建素材：单条（sync 同步 / async 异步）与批量（urls 数组） |
/v1/assets/async | POST | 异步上传（新·推荐）：立即返回真实素材ID，状态 Pending |
/v1/assets/get | POST | 查询单个素材（id 支持素材ID 或异步任务ID） |
/v1/assets/list | POST | 查询素材列表（分页/按名称/按分组） |
/v1/assets/batch/get | POST | 按批次查询素材（批量上传的整批进度） |
/v1/assets/update | POST | 更新素材名称 |
/v1/assets/delete | POST | 删除素材 |
/v1/assets/{id}/content | GET | 素材内容稳定地址（浏览器/下载器直接访问，支持断点续传） |
/v1/assets/groups | GET / POST | 获取 / 创建素材库分组 |
/v1/assets/groups/delete | POST | 删除分组（级联删除组内素材） |
/v1/assets/groups/transfer | POST | 转移分组到当前用户另一令牌 |
Authorization: Bearer <your_api_key>），操作要求账户余额 ≥ 1 元（操作本身不扣费）。上传前必须先创建分组拿 group_id。| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
url | string | 是 | 素材文件的公网可访问 URL（服务端会下载） |
group_id | int | 是 | 分组 ID（正整数，须为当前令牌的分组） |
asset_type | string | 否 | Image（默认）/ Video / Audio |
name | string | 否 | 素材名称（上限64字符） |
upload_mode | string | 否 | sync（默认，阻塞至审核完成后返回）/ async（立即返回任务ID） |
callback_url | string | 否 | 异步上传结果回调地址（见第4节） |
callback_secret | string | 否 | 回调签名密钥（可选） |
sync 响应（审核通过，返回真实素材ID）：
{ "code": "success", "data": { "id": "asset-20260427120130-ngtck", "asset_url": "asset://asset-20260427120130-ngtck" } }
async 响应（立即返回，id 即任务ID，可直接用于 /v1/assets/get 轮询）：
{ "code": "success", "data": { "id": "task-20260630120000-abcde", "status": "Processing" } }
直接分配真实素材ID（无需等任务回填），状态初始 Pending，通常 5~30 秒进入终态。请求体：{ "url", "group_id", "asset_type"?, "name"? }
{ "code": "success", "data": { "id": "asset-20260716171312-pvq2l", "group_id": 8, "status": "Pending" } }
用返回的 id 调 POST /v1/assets/get 轮询：Pending（处理中）→ Active（可用）/ Failed（失败，带 error）。建议轮询间隔 ≥ 500ms。
传 urls 数组（最多 50 条，非空时忽略单条 url）。批次内共用 asset_type 与 name：
{
"group_id": 8, "asset_type": "Image", "name": "batch-test",
"urls": ["https://example.com/1.jpg", "https://example.com/2.jpg"]
}
响应含 batch_id（用于 POST /v1/assets/batch/get 轮询整批进度）：
{
"code": "success",
"data": {
"batch_id": "task-20260713070255-c9a9f950", "task_id": "task-20260713070255-c9a9f950",
"total": 3, "status": "Processing",
"items": [{ "source_url": "https://example.com/1.jpg", "status": "Processing" }]
}
}
单条 async 与批量上传可携带 callback_url。平台以自有域名中继回调（你只会收到来自本平台的回调请求）：
Content-Type: application/json、X-Track-Id（任务ID，幂等键）；填了 callback_secret 时附 X-Webhook-Signature = HMAC-SHA256(secret, 原始请求体字节) 十六进制{ "code": 200, "task_id", "status": "completed|failed", "total_count", "done_count", "result": { "items": [...] } }，items[].asset_url 为 asset:// 引用地址| 接口 | 请求体 | 说明 |
|---|---|---|
POST /v1/assets/get | {"id": "asset-xxx 或 task-xxx"} | 查询单个素材；status：Active / Processing(≈Pending) / Failed（带 error）/ Deleted |
POST /v1/assets/list | {"page_number","page_size","name","group_id"} | 分页查询当前令牌素材；name 模糊搜索；group_id>0 指定分组 |
POST /v1/assets/batch/get | {"batch_id": "task-xxx"} | 整批进度；items[].status 均不为 Processing 即整批结束 |
POST /v1/assets/update | {"id", "name"} | 更新素材名称（上限64字符） |
POST /v1/assets/delete | {"id"} | 删除素材；删除后 asset:// 引用即刻失效 |
单个素材响应示例（url 为平台稳定访问地址，长期有效）：
{
"code": "success",
"data": {
"id": "asset-20260403150605-bfjwz",
"name": "sunflower",
"url": "https://www.yhapiplatform.com/v1/assets/asset-20260403150605-bfjwz/content",
"asset_url": "asset://asset-20260403150605-bfjwz",
"asset_type": "Image",
"status": "Active",
"create_time": "2026-04-03T07:06:05Z"
}
}
素材内容稳定地址：GET /v1/assets/{id}/content（浏览器/下载器可直接打开，支持 Range）。
| 接口 | 方法 | 请求体 / 说明 |
|---|---|---|
/v1/assets/groups | GET | 分组列表：data[] 含 id、name、asset_count |
/v1/assets/groups | POST | {"name"} 创建分组；创建后从列表取 id 作为 group_id |
/v1/assets/groups/delete | POST | {"id": 8} 删除分组（级联删除组内素材，不可恢复） |
/v1/assets/groups/transfer | POST | {"id": 3, "token_id": 5} 转移到当前用户另一令牌 |
/v1/assets/groups/update | POST | {"id", "name"} 修改分组名称（平台扩展接口） |
| 类型 | 格式 | 尺寸要求 | 大小限制 |
|---|---|---|---|
| 图片 | jpeg、png、webp、bmp、tiff、gif | 宽高 300~6000px，宽高比 0.4~2.5 | 单张 < 30MB |
| 视频 | mp4、mov | 分辨率 480p/720p，时长 2~15秒 | 单个 < 50MB |
| 音频 | wav、mp3 | 时长 2~15秒 | 单个 < 15MB |
真人素材用于生成"数字人 / 真人形象"类视频。与普通素材不同，真人素材上传前必须先完成 H5 人脸认证授权：授权方在 H5 页面刷脸成功后，系统创建一个真人素材组（艺人组），后续上传到该组的素材会做人脸一致性校验——只有与授权刷脸同一个人的素材才能通过审核（否则返回 FaceMismatch）。审核通过后获得 asset:// 引用地址，可直接用于视频生成。
POST /v1/assets/real-person/auth/link（提交艺人名称）GET /v1/assets/real-person/groups（拿到真人组 group_id，即返回项的 id）POST /v1/assets（或 /v1/assets/async），传真人组 id，触发人脸校验asset:// 引用地址传入 POST /v1/video/generations/v1/real-person/* 保留兼容，与新路径等价。| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
artist_name | string | 是 | 艺人（授权组）名称，最多32字符，不可重复 |
artist_desc | string | 否 | 艺人描述，最多300字符 |
{
"code": "success",
"data": {
"h5_url": "https://...",
"tip": "请让授权方在 120 秒内打开并完成认证，链接使用后失效"
}
}
请将 h5_url 转交授权方（真人本人）在手机上打开完成刷脸。认证成功后系统自动为当前令牌创建真人素材组。
{
"code": "success",
"data": {
"items": [{
"id": 128,
"group_id": "group-xxx",
"artist_name": "张三",
"artist_desc": "品牌代言人真人素材组",
"authorized_at": "2026-04-27T12:00:29+08:00",
"asset_count": 3
}]
}
}
id（平台组 ID，整数）。刚完成刷脸列表为空时，等 1~2 秒重试；始终为空说明刷脸未成功或链接超时，请重新获取认证链接。通过 POST /v1/assets（或 /v1/assets/async）上传，group_id 指定为真人组 id 即触发人脸一致性校验：
{
"url": "https://example.com/zhangsan-face.jpg",
"asset_type": "Image",
"name": "张三-正脸",
"group_id": 128
}
{"error":{"message":"FaceMismatch: 上传素材与授权认证人脸不一致"}}。同一真人组只应上传同一位真人的素材。素材要求与普通素材一致（图片高度300~6000px、URL公网可访问）。| 接口 | 请求体 | 说明 |
|---|---|---|
POST /v1/assets/real-person/assets/delete | {"id": "asset-xxx"} | 删单个真人素材（不含 asset:// 前缀），永久移除不可恢复 |
POST /v1/assets/real-person/groups/delete | {"id": 128} | 删整组（连同组内全部素材一并永久移除，不可恢复） |
{
"model": "doubao-seedance-2-0-fast-260128",
"prompt": "人物微笑挥手",
"metadata": {
"content": [
{ "type": "image_url", "image_url": { "url": "asset://asset-20260427120130-ngtck" }, "role": "reference_image" }
],
"duration": 5, "resolution": "720p", "ratio": "adaptive"
}
}
素材管理是一个独立的本地素材库模块：分组管理 + 素材上传（在线 URL 或 base64 图片）+ 分页查询。素材文件存储在本平台自有文件服务（返回的 url 为本平台长期有效地址，带随机访问令牌）。可选 auto_asset 同步注册到素材库，获得 asset:// 引用后即可直接用于视频生成。
| 接口 | 方法 | 说明 |
|---|---|---|
/v1/material/groups | POST | 新建分组（body: {"name"}） |
/v1/material/groups | GET | 获取分组列表（首次访问自动创建「我的素材」默认分组；含 item_count） |
/v1/material/items/upload | POST | 上传素材到分组（在线 URL / base64 data URI；auto_asset 可选） |
/v1/material/items/list | POST | 分页查询素材（按分组 / 名称模糊 / 分页） |
/v1/material/file/{id}?t=xxx | GET | 素材文件服务（url 字段指向这里；浏览器可直接访问，支持断点续传） |
Authorization: Bearer <your_api_key>（无需额外的 X-Token 头）。响应统一 {success, message?, data}，失败为 {"success": false, "message": "原因"}。上传操作要求账户余额 ≥ 1 元（操作本身不扣费）。请求体：{"name": "API测试分组"}（name 必填）。响应：
{
"success": true,
"data": {
"id": 12, "name": "API测试分组", "user_id": 326,
"is_default": false,
"created_at": "2026-09-09 10:30:00", "updated_at": "2026-09-09 10:30:00"
}
}
{
"success": true,
"data": [
{ "id": 1, "user_id": 1, "name": "我的素材", "is_default": true, "created_at": 1783475596, "item_count": 13 },
{ "id": 15, "user_id": 1, "name": "API测试分组", "is_default": false, "created_at": 1788947593, "item_count": 3 }
]
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
group_id | int | 是 | 目标分组 ID（须为本人的分组） |
url | string | 是 | 素材内容：在线 http(s) 直链，或 base64 的 data URI 形式（data:image/png;base64,xxxx）。纯 base64 字符串会被拒绝（无 MIME 无法识别类型），请务必带 data: 前缀 |
name | string | 否 | 素材名称；不传则从来源 URL 自动提取 |
auto_asset | boolean | 否 | 默认 false。为 true 时上传完成后自动注册到素材库，响应附 asset_id / asset_url / asset_status（asset:// 引用可直接用于视频生成） |
响应示例：
{
"success": true,
"data": {
"id": 88, "name": "示例图片", "group_id": 12,
"url": "https://www.yhapiplatform.com/v1/material/file/88?t=1a2b3c4d5e6f7a8b",
"file_type": "image",
"created_at": "2026-09-09 10:30:00", "updated_at": "2026-09-09 10:30:00",
"asset_id": "asset-20260928120000-abcde",
"asset_url": "asset://asset-20260928120000-abcde",
"asset_status": "Pending"
}
}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
group_id | int | 否 | 0 | 按分组过滤；不传或 0 表示所有分组 |
name | string | 否 | - | 按名称模糊搜索（LIKE %name%） |
page_number | int | 否 | 1 | 页码，从 1 开始 |
page_size | int | 否 | 20 | 每页条数，最大 100（超过截断） |
响应示例：
{
"success": true,
"data": {
"items": [{
"id": 88, "name": "示例图片", "group_id": 12,
"url": "https://www.yhapiplatform.com/v1/material/file/88?t=1a2b3c4d5e6f7a8b",
"file_type": "image",
"created_at": "2026-09-09 10:30:00", "updated_at": "2026-09-09 10:30:00",
"volc_channel_count": 1,
"upstream_url": "asset://asset-20260928120000-abcde"
}],
"total_count": 1, "page_number": 1, "page_size": 20
}
}
asset:// 引用地址（未注册为空）。用此引用即可在视频生成 content 中直接使用。POST /v1/material/groups → 取 data.idPOST /v1/material/items/upload（group_id + url，需要视频引用时加 auto_asset:true）POST /v1/material/items/list（group_id 过滤 / name 搜索）upstream_url（asset://）或 url（本平台直链）填入 POST /v1/video/generations 的 content专业版系列采用火山方舟官方格式的独立端点：请求传参（content[] 数组）与响应结构与官方完全一致，仅域名不同，可直接复用官方 SDK 与示例代码。平台扩展参数 bitrate_mode（码率模式）在同端点透传。素材引用与普通版统一：content 中各模态 url 支持 asset://（统一素材库，推荐）、media://（真人素材库，兼容旧引用）与公网 URL / Base64。
| 模型名称 | 说明 |
|---|---|
doubao-seedance-2-0-Professional Edition | 专业版（画质优先），720P/1080P，4~15 秒，参考素材最多 15 个 |
doubao-seedance-2-0-fast-Professional Edition | 专业版（速度优先），生成更快，720P/1080P，4~15 秒，参考素材最多 15 个 |
doubao-seedance-2.5-Professional Edition | 专业版旗舰，时长上限 30 秒，参考素材最多 50 个（图片 30 / 视频 10 / 音频 10），支持视频延长与视频编辑 |
| 接口 | 方法 | 说明 |
|---|---|---|
/api/v3/contents/generations/tasks | POST | 创建任务，响应 {"id": "ag_..."} |
/api/v3/contents/generations/tasks/:id | GET | 查询任务状态及结果（官方扁平响应） |
/api/v3/contents/generations/tasks | GET | 任务列表，支持 filter.status / filter.model / filter.task_ids / page_num / page_size |
/api/v3/contents/generations/tasks/:id | DELETE | 取消排队任务（queued → cancelled）/ 删除已终态任务记录；运行中任务不可强制中止（409） |
Authorization: Bearer <your_api_key> 头部中传入。注意：专业版模型不再通过 /api/video/create 创建（该入口收到专业版模型名会返回迁移提示）。| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
model | string | 是 | - | 上表三个专业版模型名之一 |
content | array | 是 | - | 输入内容数组：{type:"text",text}、{type:"image_url",image_url:{url},role}、{type:"video_url",video_url:{url},role:"reference_video"}、{type:"audio_url",audio_url:{url},role:"reference_audio"}；图片 role 取值 first_frame / last_frame / reference_image |
resolution | string | 否 | 720p | 分辨率：720p、1080p |
ratio | string | 否 | adaptive | 宽高比：16:9、9:16、4:3、3:4、1:1、21:9、adaptive |
duration | integer | 否 | 5 | 时长（秒）4~15，旗舰版最长 30；传 -1 为智能时长 |
generate_audio | boolean | 否 | true | 是否生成同步音频 |
watermark | boolean | 否 | false | 是否添加水印 |
n | integer | 否 | 1 | 单次生成视频个数，1~4（n>1 时响应扩展 content.video_urls[]） |
return_last_frame | boolean | 否 | false | 是否同时返回尾帧图片（三个专业版模型均支持） |
output_format | string | 否 | mp4 | 封装格式 mp4 / mov，仅旗舰版支持 |
omni_reference_task_type | string | 否 | auto | extend=视频延长、edit=视频编辑（仅旗舰版；需配合 reference_video 传入源视频） |
bitrate_mode | string | 否 | - | 平台扩展参数：码率模式 high / standard（透传专业版上游，响应中回显） |
callback_url | string | 否 | - | 任务状态回调地址（须 HTTPS）：任务到达终态且可交付（succeeded 已结算 / failed / cancelled）后，平台向该地址 POST 官方结构任务对象（含 content.video_url、last_frame_url、usage）；按 id 幂等，投递失败按 5s/15s/60s/5m/15m 退避重试至多 5 次 |
seed、camera_fixed、frames、draft、service_tier、execution_expires_after、priority、safety_identifier、tools 等）传入时静默忽略，不报错。| 任务类型 | 所需输入 | 说明 |
|---|---|---|
| 文生视频 | 仅提示词 | content 只有 text |
| 图生视频（首帧） | 1 张图片 | role=first_frame 或不带 role |
| 首尾帧生成 | 2 张图片 | role 分别为 first_frame 与 last_frame |
| 多模态参考生视频 | 图/视频/音频组合 | 参考图带 role=reference_image，或混合音视频素材 |
| 视频延长 / 编辑 | 源视频 + 提示词 | omni_reference_task_type=extend / edit，仅旗舰版 |
asset://<素材ID> 统一素材库（推荐，首次引用自动同步到专业版素材通道，无需重复注册）；media://<media_id> 真人素材库（兼容旧引用）；公网 URL / Base64 直接透传。含真人人物（人脸出镜）的素材可能被版权检测拒绝，请优先使用统一素材库的 asset:// 引用或在真人素材库注册后引用。| 字段 | 说明 |
|---|---|
id | 任务 ID（ag_ 前缀） |
model | 模型名称 |
status | queued / running / succeeded / failed / cancelled |
content.video_url | 第一个产物的视频地址（计费完成后才返回） |
content.video_urls | 平台扩展：全部产物地址数组（n>1 时返回） |
content.last_frame_url | 尾帧图片地址（return_last_frame=true 时返回） |
created_at | 任务创建时间（Unix 时间戳，秒） |
duration / ratio / resolution / generate_audio / output_format | 任务实际参数回显 |
bitrate_mode | 码率模式回显（平台扩展，high / standard） |
usage | 用量对象：completion_tokens = 本任务实际消耗计量（计费依据），total_tokens 同值 |
error | {code, message} 失败信息（status=failed 时返回，否则为 null） |
status:"running"（稍后再查即得终态）；余额不足时返回 HTTP 402 与错误对象，充值后重新查询即可获取视频。DELETE /api/v3/contents/generations/tasks/:id 按任务当前状态区分：
| 当前状态 | 是否支持 | 结果 |
|---|---|---|
queued | 是 | 取消排队，任务状态变为 cancelled（不结算；上游资源已占用，取消请谨慎） |
running | 否（409） | 不支持强制中止，保留任务继续查询 |
succeeded（已结算） | 是 | 删除任务记录，删除后不能再查询 |
failed / cancelled | 是 / 否（409） | 失败任务可删除记录；已取消任务不重复操作 |
succeeded 未结算的任务会返回 409（先查询完成结算再删除）。客户端超时不等于任务失败——请继续用原任务 ID 查询，不要立即重复创建，以免重复计费。创建任务携带 callback_url（HTTPS）时，任务到达终态且可交付后平台向该地址 POST 官方结构任务对象（与查询响应同构，含 content.video_url、content.last_frame_url、usage、error），请求头附 X-Track-Id（任务 ID，幂等键）。
id 幂等去重；收到回调后再调查询接口获取最终权威状态# 创建任务携带回调（回调体 = 查询响应同构，POST 到你的 HTTPS 地址）
curl -X POST "https://www.yhapiplatform.com/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \
-d '{"model":"doubao-seedance-2-0-Professional Edition","content":[{"type":"text","text":"一只猫在窗台"}],"duration":5,"callback_url":"https://your-server.com/video-task-callback"}'
# 取消排队中的任务（queued → cancelled；运行中不可中止）
curl -X DELETE "https://www.yhapiplatform.com/api/v3/contents/generations/tasks/ag_xxxxxxxx" \
-H "Authorization: Bearer sk-xxx"
任务完成后按实际消耗计量（usage.completion_tokens 口径）计费，单价见「定价」页对应模型条目，支持峰谷定价与用户单独定价；创建任务要求账户余额不低于视频生成门槛。用量以查询接口返回的 usage 为准，可在「使用统计」中核对。
const axios = require('axios'); const API_KEY = 'sk-yhapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'; const BASE_URL = 'https://www.yhapiplatform.com'; const headers = { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }; // 创建专业版视频任务（官方 content[] 格式；素材统一用 asset://，bitrate_mode 为平台扩展参数） async function main() { const resp = await axios.post(`${BASE_URL}/api/v3/contents/generations/tasks`, { model: 'doubao-seedance-2-0-Professional Edition', content: [ { type: 'text', text: '图片1中的人物对着镜头微笑挥手，背景是夕阳下的海边' }, { type: 'image_url', image_url: { url: 'asset://你的素材ID' }, role: 'reference_image' } ], ratio: '16:9', duration: 5, resolution: '1080p', generate_audio: true, bitrate_mode: 'high', callback_url: 'https://your-server.com/video-task-callback' }, { headers }); const taskId = resp.data.id; console.log('Task ID:', taskId); // 每 5 秒轮询一次（官方扁平响应） const timer = setInterval(async () => { const r = await axios.get(`${BASE_URL}/api/v3/contents/generations/tasks/${taskId}`, { headers }); const d = r.data; console.log('Status:', d.status); if (d.status === 'succeeded') { clearInterval(timer); console.log('视频地址:', d.content.video_url); console.log('实际消耗计量:', d.usage.completion_tokens); } else if (d.status === 'failed') { clearInterval(timer); console.error('生成失败:', d.error); } }, 5000); } main().catch(console.error);
asset:// 或 media:// 引用，直接传公网 URL 会被版权检测拒绝。本库提供与官方私域素材库（Assets API）请求/响应字段完全一致的接口：全部 POST、帕斯卡命名、嵌套 Filter 结构，可直接复用官方示例代码的字段与流程（仅鉴权用平台 API Key，域名不同）。素材 ID 为官方风格 asset- 前缀，可直接以 asset://<Id> 在专业版视频生成（POST /api/v3/contents/generations/tasks）的 content 中引用。
| 接口 | 方法 | 官方 Action | 入参 → 出参 |
|---|---|---|---|
/api/v3/assets | POST | CreateAsset | {GroupId?, URL, AssetType(Image/Video/Audio), Name?} → {"Id": "asset-..."}（异步检测，轮询 GetAsset 等 Active；GroupId 不传自动用默认组） |
/api/v3/assets/get | POST | GetAsset | {Id} → {Id, GroupId, Name, AssetType, Status, URL, CreateTime, UpdateTime, Moderation:{Strategy}, ProjectName}；Status：Active / Processing / Failed（实时刷新） |
/api/v3/assets/list | POST | ListAssets | {Filter:{GroupIds?, Statuses?, Name?, GroupType?}, MaxResults?, SortBy?(CreateTime/UpdateTime), SortOrder?(Asc/Desc), NextToken?} → {Items:[...], NextToken}（Items 元素与 GetAsset 同构，URL 为 null 时需单独调 GetAsset 取地址） |
/api/v3/assets/update | POST | UpdateAsset | {Id, Name} → {} |
/api/v3/assets/delete | POST | DeleteAsset | {Id} → {} |
/api/v3/asset-groups/list | POST | ListAssetGroups | {Filter:{Name?, GroupIds?}, MaxResults?, NextToken?} → {Items:[{Id, Name, Description, GroupType:"LivenessFace", ProjectName, CreateTime, UpdateTime}], NextToken}（首次调用自动开通默认组） |
/api/v3/asset-groups/get | POST | GetAssetGroup | {Id} → 单个组对象（字段同上） |
/api/v3/asset-groups/update | POST | UpdateAssetGroup | {Id, Name?, Description?} → {} |
/api/v3/asset-groups/delete | POST | DeleteAssetGroup | {Id} → {}（仅空组可删） |
Authorization: Bearer），非官方 AK/SK——字段结构对齐即可复用官方示例代码；② LastInferenceTime 未接入本地统计，按官方「无调用记录不返回」口径省略；③ 官方有、本地无对应能力的参数（ProjectName、Filter.GroupType、SortBy 其他取值）静默忽略；④ 组的创建方式不同——官方需先走真人认证（CreateVisualValidateSession H5 人脸认证 → GetVisualValidateResult 获取 GroupId，每组绑定一个真人，素材入库做人脸一致性比对）后才能 CreateAsset；本平台无需真人认证，首次调用 asset-groups/list 自动开通默认组，CreateAsset 不传 GroupId 即入默认组（按官方流程传 GroupId 也完全兼容），官方 Step 1 的两个认证接口本平台不提供。同一路由的 REST 风格别名（GET/PUT/DELETE）继续可用；视频生成里 asset://<Id> 的解析顺序：先查统一素材库、再查本库。import requests, time BASE_URL = "https://www.yhapiplatform.com" API_KEY = "sk-yhapi-xxx" headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"} # 1. 创建素材（官方字段） resp = requests.post(f"{BASE_URL}/api/v3/assets", headers=headers, json={ "URL": "https://example.com/person.jpg", "AssetType": "Image", "Name": "正脸照片" }) asset_id = resp.json()["Id"] # asset-xxxxx print("素材:", asset_id) # 2. 轮询至 Active for _ in range(30): d = requests.post(f"{BASE_URL}/api/v3/assets/get", headers=headers, json={"Id": asset_id}).json() print("状态:", d["Status"]) if d["Status"] == "Active": break if d["Status"] == "Failed": raise SystemExit("素材检测失败") time.sleep(3) # 3. 专业版视频生成（官方格式，asset:// 引用） resp = requests.post(f"{BASE_URL}/api/v3/contents/generations/tasks", headers=headers, json={ "model": "doubao-seedance-2-0-Professional Edition", "content": [ {"type": "text", "text": "人物微笑着向镜头挥手"}, {"type": "image_url", "image_url": {"url": f"asset://{asset_id}"}, "role": "reference_image"} ], "duration": 5 }) print("视频任务:", resp.json()["id"])
以下旧端点继续可用，存量 media:// 引用不受影响；新接入建议直接使用上方官方格式接口。
| 接口 | 方法 | 说明 |
|---|---|---|
/v1/pro-assets | POST | 注册真人素材（公网 URL → media_id） |
/v1/pro-assets/get | POST | 查询单个素材（状态/封面/文件信息） |
/v1/pro-assets/search | POST | 搜索我的素材（标题关键字/类型过滤，分页） |
/v1/pro-assets/update | POST | 更新素材标题/描述/标签 |
/v1/pro-assets/delete | POST | 批量删除素材 |
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
url | string | 是 | 公网可访问的 http(s) 素材地址 |
media_type | string | 是 | 素材类型：image / video / audio |
title | string | 否 | 标题（便于搜索） |
description | string | 否 | 描述 |
media_tags | string | 否 | 标签，多个用英文逗号分隔 |
同一素材地址重复注册会自动去重（返回已有 media_id）。注册成功后素材进入检测流程，请通过查询接口轮询至可用状态。
curl -X POST "https://www.yhapiplatform.com/v1/pro-assets" \ -H "Authorization: Bearer sk-yhapi-xxxx" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/person.jpg", "media_type": "image", "title": "正脸照片" }'
响应示例：
{
"code": "success",
"data": {
"media_id": "xxxxx",
"media_ref": "media://xxxxx",
"status": "Processing"
}
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
media_id | string | 是 | 素材 ID（media:// 前缀亦可） |
auth_timeout | integer | 否 | 返回的文件/封面地址有效期（秒） |
关键字段：status（Processing → Normal 表示就绪）、third_party_status（版权检测：Init/Processing → Success 可用于生成，Failed 不可用并附原因）、cover_url（封面图）、files（文件地址/时长/宽高）。
status=Normal 且 third_party_status=Success 后再用于视频生成；同一素材只需注册一次，media_id 长期有效。| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
keyword | string | 否 | 标题关键字（中英文/数字/空格/连字符/下划线） |
media_type | string | 否 | image / video / audio |
page_no | integer | 否 | 页码，默认 1 |
page_size | integer | 否 | 每页条数，默认 10，最大 50 |
入参：media_id（必填）+ title / description / media_tags / cover_url（至少一项，cover_url 仅视频素材有效）。
入参：media_ids（数组或逗号分隔字符串）。仅能删除本人素材；响应返回 deleted（已删除）、ignored（不存在/无权限）。
| 类型 | 格式 | 限制 |
|---|---|---|
| 图片 | jpeg / jpg / png / webp | 小于 20MB；短边不低于 400px，长边不超过 8000px |
| 视频 | mp4 / mov | 不超过 100MB；宽高（px）范围 [300, 4096]，像素（宽×高）范围 [409600, 927408] |
| 音频 | mp3 / wav | 不超过 15MB |
注册并确认素材可用后，在专业版视频生成（官方格式端点）中以 media://<media_id> 引用：
{
"model": "doubao-seedance-2.5-Professional Edition",
"content": [
{ "type": "text", "text": "人物微笑着向镜头挥手" },
{ "type": "image_url", "image_url": { "url": "media://xxxxx" }, "role": "reference_image" },
{ "type": "audio_url", "audio_url": { "url": "media://yyyyy" }, "role": "reference_audio" }
],
"duration": 10,
"resolution": "1080p"
}
import requests, time BASE_URL = "https://www.yhapiplatform.com" API_KEY = "sk-yhapi-xxx" headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"} # 1. 注册真人素材 resp = requests.post(f"{BASE_URL}/v1/pro-assets", headers=headers, json={ "url": "https://example.com/person.jpg", "media_type": "image", "title": "正脸照片" }) media_ref = resp.json()["data"]["media_ref"] # media://xxxxx print("素材:", media_ref) # 2. 轮询素材直到可用 for _ in range(30): resp = requests.post(f"{BASE_URL}/v1/pro-assets/get", headers=headers, json={"media_id": media_ref}) d = resp.json()["data"] if d["status"] == "Normal" and d["third_party_status"] == "Success": break if d["third_party_status"] == "Failed": raise SystemExit("素材检测失败:" + str(d.get("third_party_error"))) time.sleep(3) # 3. 创建专业版视频任务（官方格式端点，POST /api/v3/contents/generations/tasks） resp = requests.post(f"{BASE_URL}/api/v3/contents/generations/tasks", headers=headers, json={ "model": "doubao-seedance-2-0-Professional Edition", "content": [ {"type": "text", "text": "人物微笑着向镜头挥手"}, {"type": "image_url", "image_url": {"url": media_ref}, "role": "reference_image"} ], "duration": 5, "resolution": "1080p", "bitrate_mode": "high" }) task_id = resp.json()["id"] print("视频任务:", task_id) # 4. 轮询任务（官方扁平响应） while True: r = requests.get(f"{BASE_URL}/api/v3/contents/generations/tasks/{task_id}", headers=headers) d = r.json() print("状态:", d["status"]) if d["status"] == "succeeded": print("视频地址:", d["content"]["video_url"]) break if d["status"] == "failed": raise SystemExit("生成失败:" + str(d.get("error"))) time.sleep(5)
素材组、素材与真人人像认证的统一网关，采用火山 OpenAPI Action 风格。视频接口与素材接口使用同一枚 API Key（Authorization: Bearer sk-xxx）。素材引用 asset://<asset_id> 可直接用于专业版与普通版视频生成。
| 接口 | 方法 | 说明 |
|---|---|---|
/api/seedance/proxy/openapi?Action=<ACTION>&Version=2024-01-01 | POST | 素材组/素材 10 个 Action（见下表） |
/api/seedance/face-verifications | POST | 创建真人认证会话（返回 h5_url） |
/api/seedance/face-verifications/{verification_id} | GET | 查询认证状态（verified 后返回 group_id） |
/api/seedance/healthz | GET | 健康检查（无需 Token） |
| Action | 请求体要点 | 说明 |
|---|---|---|
CreateAssetGroup | {"Name"(≤64),"Description"?,"GroupType":"AIGC"} | 创建 AIGC 素材组；返回 Result.Id |
ListAssetGroups | {"Filter":{"GroupType":"AIGC|LivenessFace","GroupIds"?,"Name"?},"PageNumber","PageSize"≤100} | 分页查询素材组（含 item 计数口径的 TotalCount） |
GetAssetGroup | {"Id"} | 素材组详情 |
UpdateAssetGroup | {"Id","Name"?} | 改名（Name/Description 至少一项；描述当前仅记录不改上游） |
DeleteAssetGroup | {"Id"} | 删除组及组内素材，不可恢复 |
CreateAsset | {"GroupId","URL","AssetType":"Image|Video|Audio","Name"?} | 异步创建素材，返回 Result.Id；须轮询 GetAsset 至 Active |
ListAssets | {"Filter":{"GroupIds"?,"GroupType"?,"Statuses"?,"Name"?},"PageNumber","PageSize"≤100} | 分页查询素材（仅当前账号） |
GetAsset | {"Id"} | 素材详情与状态（Active/Processing/Failed；Failed 带 Error） |
UpdateAsset | {"Id","Name"} | 修改素材名称 |
DeleteAsset | {"Id"} | 删除素材，不可恢复 |
{"ResponseMetadata":{"RequestId","Action","Version","Error"?},"Result":{...}}，请保存 RequestId 用于排障。错误时 HTTP 状态保留业务码、ResponseMetadata.Error 携带 {Code, Message}。OpenAPI 入口必须 POST（GET 返回 405）；不在白名单的路径返回 404 unsupported_seedance_route。Result.URL 为平台长期有效地址；视频生成引用请使用稳定标识 asset://<asset_id>。POST /api/seedance/face-verifications // body 可为 {} 或 {"return_url":"https://..."}
→ { "verification_id": "fv_xxxxxxxxx", "status": "waiting_user",
"h5_url": "https://...", "expires_at": "2026-09-28T12:00:00.000Z" }
GET /api/seedance/face-verifications/fv_xxxxxxxxx
→ { "verification_id": "fv_xxxxxxxxx", "status": "waiting_user" | "verified" | "expired",
"group_id": "128" } // verified 时返回
让终端用户在有效期内打开 h5_url 完成活体认证；业务系统保存 verification_id 轮询，verified 后拿 group_id（LivenessFace 组），再用 CreateAsset 向该组上传与认证本人一致的素材（触发人脸一致性校验，不一致返回 FaceMismatch 错误）。
# 创建素材组
curl -X POST "https://www.yhapiplatform.com/api/seedance/proxy/openapi?Action=CreateAssetGroup&Version=2024-01-01" \
-H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \
-d '{"Name":"品牌素材组","GroupType":"AIGC"}'
# 创建素材（异步；轮询 GetAsset 至 Active 后用 asset:// 引用）
curl -X POST "https://www.yhapiplatform.com/api/seedance/proxy/openapi?Action=CreateAsset&Version=2024-01-01" \
-H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" \
-d '{"GroupId":"3339","URL":"https://example.com/ref.jpg","AssetType":"Image","Name":"人物参考图"}'
{
"model": "doubao-seedance-2-0-Professional Edition",
"content": [
{ "type": "text", "text": "人物在城市街道缓慢行走" },
{ "type": "image_url", "role": "reference_image",
"image_url": { "url": "asset://asset-xxxxxxxx" } }
],
"resolution": "720p", "ratio": "16:9", "duration": 5
}
本平台兼容 OpenAI API 格式，可接入任何支持自定义 OpenAI API 地址的软件。
| 配置项 | 值 |
|---|---|
| API 地址（Base URL） | https://www.yhapiplatform.com/v1 |
| API Key | 从本平台 "API Keys" 页面生成的 Key |
| 模型（DeepSeek V4 Pro） | deepseekv4pro-0813 |
| 模型（DeepSeek V4 Flash） | deepseek-v4.1-flash-1017 |
https://www.yhapiplatform.com/v1deepseek-v4.1-flash-1017 和 deepseekv4pro-0813https://www.yhapiplatform.com/v1deepseek-v4.1-flash-1017https://www.yhapiplatform.com/v1（注意要包含 /v1）deepseek-v4.1-flash-1017https://www.yhapiplatform.com/v1deepseek-v4.1-flash-1017几乎所有支持 OpenAI 的客户端都遵循相同的配置方式：
https://www.yhapiplatform.com/v1deepseek-v4.1-flash-1017 或 deepseekv4pro-0813Seedance 视频生成是独立的 REST API，不通过 OpenAI SDK 调用。需要自行编写 HTTP 请求代码集成。
| 配置项 | 值 |
|---|---|
| Base URL | https://www.yhapiplatform.com |
| 认证方式 | Bearer Token（JWT Token，登录后获取） |
| 创建任务 | POST /api/video/create |
| 查询状态 | GET /api/video/status/{taskId} |
| 模型（Seedance 2.0） | doubao-seedance-2-0-260128 |
| 模型（Seedance 2.0 Fast） | doubao-seedance-2-0-fast-260128 |
| 模型（Seedance 2.5） | doubao-seedance-2.5（时长上限 30 秒） |
| 模型（专业版系列） | doubao-seedance-2-0-Professional Edition / doubao-seedance-2-0-fast-Professional Edition / doubao-seedance-2.5-Professional Edition（需授权；走官方格式端点 POST /api/v3/contents/generations/tasks，见「专业版视频生成接口」章节） |
https://www.yhapiplatform.com/api/video/createAuthorization: Bearer {你的JWT Token}{
"prompt": "A serene Japanese garden with cherry blossoms",
"model": "doubao-seedance-2-0-260128",
"ratio": "16:9",
"duration": 5,
"resolution": "720p"
}
https://www.yhapiplatform.com/api/video/status/{taskId}Authorization: Bearer {你的JWT Token}视频生成是异步流程，标准集成步骤：
/api/auth/login 获取 JWT Token/api/video/create 提交生成请求/api/video/status/{taskId} 查询进度succeeded 时，从 videoUrl 下载视频详细的请求参数和代码示例请参考上方"视频生成接口"章节。
/v1/chat/completions 端点。部分旧版本软件可能不支持，建议升级到最新版本。使用火山方舟 Seedance AI 模型生成高质量视频
| 时间 | 提示词 | 参数 | 状态 | 操作 | |
|---|---|---|---|---|---|
| 加载中... | |||||