API REFERENCE

网站模型 API

支持文本、图片、视频生成与角色音色设计，按模型选择对应接口。下游只需要配置本站地址、API Key 和模型 ID，不需要了解上游渠道。

GET/v1/modelsPOST/v1/videos异步任务

基础信息

Base URL：

Base URL

https://ai.tongyoua.com/v1

所有请求使用同一个 API Key：

HTTP Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

API Key 只保存在下游服务端，不要写入浏览器前端、公开网页、安装包或日志。

读取模型和能力

创建任务前请求模型列表。不同 API Key 可用的模型可能不同，调用时必须使用返回的完整 id。

GET/v1/models

curl

curl https://ai.tongyoua.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

视频模型通过 type 或 supported_endpoint_types 标识：

响应示例

{
  "id": "seedance2.5-720p",
  "type": "video",
  "supported_endpoint_types": ["openai-video", "openai"]
}

客户端应识别 type=video 或 openai-video，不要只判断是否包含 openai，也不要根据渠道名或模型名称猜测类型。

创建视频任务

POST/v1/videos

文生视频

JSON

{
  "model": "YOUR_VIDEO_MODEL_ID",
  "prompt": "海边日落，镜头缓慢向前推进，电影感画面",
  "seconds": 8,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}

图像、视频、音频参考

JSON

{
  "model": "YOUR_VIDEO_MODEL_ID",
  "prompt": "参考素材生成自然流畅的视频",
  "seconds": 10,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "images": ["https://example.com/image.jpg"],
  "videos": ["https://example.com/reference.mp4"],
  "audios": ["https://example.com/reference.mp3"]
}

字段	类型	说明
`model`	string	/v1/models 返回的完整模型 ID。
`prompt`	string	视频提示词。
`seconds`	integer	符合模型能力范围的时长。
`aspect_ratio`	string	例如 16:9、9:16、1:1。
`resolution`	string	例如 480p、720p、1080p；固定分辨率模型可省略。
`images/videos/audios`	string[]	公网可直接访问的参考素材 URL 数组。

请使用标准字段 seconds、aspect_ratio、images、videos、audios。不要混用上游专用字段或旧字段。

提交响应

JSON

{
  "id": "task_PUBLIC_ID",
  "task_id": "task_PUBLIC_ID",
  "object": "video",
  "status": "queued",
  "progress": 0
}

查询任务状态

GET/v1/videos/{task_id}

保存提交响应中的 task_id，没有时使用 id。建议每 10 至 30 秒查询一次，直到 completed 或 failed。

curl

curl https://ai.tongyoua.com/v1/videos/task_PUBLIC_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

状态	含义
`queued`	任务已创建，等待处理。
`in_progress`	正在生成，继续轮询。
`completed`	已完成，可以获取视频。
`failed`	生成失败，停止轮询并读取错误。

获取或播放视频

GET/v1/videos/{task_id}/content

任务完成后，响应中的 video_url、url 或 content 会指向本站内容接口，不返回上游真实地址。

下载 MP4

curl -L https://ai.tongyoua.com/v1/videos/task_PUBLIC_ID/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o result.mp4

浏览器播放建议由下游服务端代理并携带 API Key，不要把长期有效的 API Key 暴露给浏览器。

接入检查和错误

Base URL 填写 https://ai.tongyoua.com/v1。
使用同一个 API Key 请求模型、创建、查询和下载接口。
模型使用 /v1/models 返回的完整 ID。
视频模型调用 POST /v1/videos，不是 Chat Completions。
创建成功后保存任务 ID，不能把创建响应当作最终视频。
参考素材必须是服务器可直接访问的 HTTPS 文件 URL。
提交超时后先查询任务，不要盲目重复创建。

HTTP	含义	处理方式
400	参数或模型能力不匹配	重新读取模型能力并修正请求。
401/403	Key 无效或无权限	检查服务端 Key 和模型权限。
404	任务或内容不存在	检查任务 ID。
429	请求过于频繁	降低轮询频率。
500/502/503	服务暂时异常	查询已有任务状态，不要立即重复创建。

文本模型

文本模型使用 OpenAI 兼容的 Chat Completions 接口。

POST/v1/chat/completions

JSON

{
  "model": "YOUR_TEXT_MODEL_ID",
  "messages": [{"role": "user", "content": "请介绍一下人工智能"}],
  "stream": false
}

文本结果主要位于 choices[0].message.content。

图片生成模型

图片模型使用 OpenAI 兼容的 Images 接口。

POST/v1/images/generations

JSON

{
  "model": "YOUR_IMAGE_MODEL_ID",
  "prompt": "一间阳光明亮的现代工作室，写实风格",
  "size": "1024x1024",
  "n": 1
}

图片结果读取 data[].url 或 data[].b64_json。

角色音色设计与语音生成

模型 mimo-v2.5-tts-voicedesign 根据音色描述和朗读台词生成声音，无需参考音频。可以描述年龄、音色、口音、语速和情绪；实际效果以生成结果为准。

POST/v1/chat/completions

该模型使用 Chat Completions 请求，但输出是音频。不要调用 /v1/audio/speech，不要只读取 message.content，也不需要创建视频任务或轮询。

请求字段

字段	填写方式
`model`	mimo-v2.5-tts-voicedesign；当前 Key 须有该模型的调用权限。
`messages[0]`	role 为 user，content 填写角色与音色描述。
`messages[1]`	role 为 assistant，content 填写实际朗读的台词。此消息由客户端主动提交，不要删除或改为 user。
`audio.format`	本示例使用 wav；客户端和 SDK 必须保留 audio 字段。
`stream`	先使用 false，按完整 JSON 响应处理；本节不定义流式音频解析方式。

请求 JSON

{
  "model": "mimo-v2.5-tts-voicedesign",
  "messages": [
    {
      "role": "user",
      "content": "年轻女性，清亮温柔，标准普通话，语速稍慢，带一点神秘感。"
    },
    {
      "role": "assistant",
      "content": "别害怕，我会带你走出这片森林。"
    }
  ],
  "audio": {
    "format": "wav"
  },
  "stream": false
}

直接请求

以下命令适用于 Linux / macOS 的 Bash。先设置本站密钥环境变量 NEW_API_KEY；命令保存的是 JSON，不能把它直接当作音频播放。

Bash

curl -sS --max-time 180 'https://ai.tongyoua.com/v1/chat/completions' -H "Authorization: Bearer ${NEW_API_KEY}" -H 'Content-Type: application/json' -d '{"model":"mimo-v2.5-tts-voicedesign","messages":[{"role":"user","content":"年轻女性，清亮温柔，标准普通话，语速稍慢，带一点神秘感。"},{"role":"assistant","content":"别害怕，我会带你走出这片森林。"}],"audio":{"format":"wav"},"stream":false}' -o role-voice-response.json

响应与音频提取

读取 choices[0].message.audio.data，将其 Base64 解码成 WAV 二进制。下面仅展示需要读取的字段，占位文本不是可播放音频。

响应结构示意

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "audio": {
          "data": "BASE64_WAV_DATA"
        }
      }
    }
  ]
}

Node.js 18+ 完整示例

在下游服务端以 voice-design.mjs 运行以下代码：node voice-design.mjs。环境变量 NEW_API_KEY 使用本站密钥。成功后生成 role-voice.wav；代码不会自动重试生成。

JavaScript · voice-design.mjs

import { writeFile } from "node:fs/promises";

const key = process.env.NEW_API_KEY;
if (!key) throw new Error("请设置环境变量 NEW_API_KEY");
const response = await fetch("https://ai.tongyoua.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "mimo-v2.5-tts-voicedesign",
    "messages": [
      {
        "role": "user",
        "content": "年轻女性，清亮温柔，标准普通话，语速稍慢，带一点神秘感。"
      },
      {
        "role": "assistant",
        "content": "别害怕，我会带你走出这片森林。"
      }
    ],
    "audio": {
      "format": "wav"
    },
    "stream": false
  }),
  signal: AbortSignal.timeout(180000)
});
const raw = await response.text();
let result;
try {
  result = JSON.parse(raw);
} catch {
  throw new Error(`HTTP ${response.status}：响应不是 JSON，请检查服务端日志`);
}
if (!response.ok || result.error) {
  throw new Error(result.error?.message || `HTTP ${response.status}`);
}
const encoded = result.choices?.[0]?.message?.audio?.data;
if (typeof encoded !== "string" || !encoded.trim()) {
  throw new Error("响应缺少 choices[0].message.audio.data");
}
const audio = Buffer.from(encoded, "base64");
if (audio.length < 12 ||
    audio.toString("ascii", 0, 4) !== "RIFF" ||
    audio.toString("ascii", 8, 12) !== "WAVE") {
  throw new Error("响应不是预期的 WAV 音频，请检查服务端响应");
}
await writeFile("role-voice.wav", audio);
console.log(`已保存 role-voice.wav，共 ${audio.length} 字节`);

下游界面与错误处理

界面分别提供“音色描述”和“朗读台词”，按上表组合 messages。
后端解码音频后，向已鉴权的用户提供音频文件或播放接口，Content-Type 使用 audio/wav。浏览器不携带平台长期 API Key。
请求完成且成功提取音频后才显示成功；HTTP 200 但没有音频数据时，应显示获取音频失败。
示例等待上限为 180 秒，下游代理也需设置相应超时。超时不等于生成失败，不要自动重新提交，先核对请求日志与计费。
401/403 检查密钥和权限；模型不可用时检查该 Key 的模型列表；400 检查 messages、角色和 audio 字段。排查时保留请求 ID，勿记录密钥或完整 Base64 音频。
首次接入使用短台词验证本站请求、音频播放和计费，再开放正式使用。

按模型选择接口与结果类型

先读取 /v1/models 确认可用模型。能力字段可辅助选择接口；若字段不完整，客户端应允许按模型显式配置接口和输出类型，不能仅凭名称或 openai 标签判断。

能力	接口	结果处理
普通文本	/v1/chat/completions	读取 choices[0].message.content
本文图片生成	/v1/images/generations	读取 data[].url 或 b64_json
本文视频生成	/v1/videos	保存任务 ID，轮询至终态
mimo-v2.5-tts-voicedesign	/v1/chat/completions	解码 choices[0].message.audio.data

同一个 Chat Completions 入口可输出文本或音频。角色音色设计必须配置为音频结果，不能因为入口是聊天接口就按普通文本展示。其他语音模型须按各自文档接入，不能套用本模型的协议。

模型可用性以当前 API Key 请求 /v1/models 的结果为准；参数按对应模型文档填写，价格以本站当前计费配置为准。本站对外只提供统一接口，不要求下游配置上游地址、渠道号或适配器地址。