API 文档

接入信息

快速开始

Python(openai SDK ≥ 1.0)

复制from openai import OpenAI

client = OpenAI(
    api_key="您的密钥",
    base_url="https://pay.uniwork.top/v1",
)

resp = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "给宠物服饰店写三条小红书标题"}],
)
print(resp.choices[0].message.content)

Node.js

复制import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.UNIWORK_KEY,
  baseURL: "https://pay.uniwork.top/v1",
});

const r = await client.chat.completions.create({
  model: "deepseek-flash",
  messages: [{ role: "user", content: "你好" }],
});

cURL

复制curl https://pay.uniwork.top/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-flash","messages":[{"role":"user","content":"你好"}]}'

模型总表

您的密钥实际可调用的模型,以 GET /v1/models 返回为准。需要开通新模型请联系服务顾问。

单价与实时用量请登录门户查看——余额、逐条调用明细与消耗金额都在控制台,实际扣费以账单为准。

对话与多模态理解

POST /v1/chat/completions — 标准 OpenAI 格式,支持流式输出。

流式输出

复制{
  "model": "deepseek-flash",
  "messages": [{"role": "user", "content": "写一段产品介绍"}],
  "stream": true
}

SSE 分片返回,最后一片为 data: [DONE]。

图片理解

复制{
  "model": "deepseek-flash",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://你的素材域名/photo.jpg"}},
      {"type": "text", "text": "这张商品图有什么卖点?"}
    ]
  }]
}

Qwen3.8 Omni Flash：思考默认关闭

调用 POST /v1/chat/completions，模型名为 qwen3.8-omni-flash，Base URL 和元工 Key 不变。支持文字、图片、音频、视频输入，当前仅输出文本；需要 Omni 语音输出时继续使用 qwen3.5-omni-flash。3.8 请使用 Chat Completions 接口，当前不提供 /v1/responses 接入。

• 未传思考参数时默认关闭思考；也可显式传 "reasoning_effort": "none"。下面示例中的该字段可省略。
• 需要思考时显式传 "reasoning_effort": "low"，或传 "enable_thinking": true；平台保留客户显式传入的思考设置。也支持 "enable_thinking": false 关闭思考。请选一种方式，不同时传入相互冲突的开关。
• Python OpenAI SDK 中 reasoning_effort 直接作为请求参数；enable_thinking 放入 extra_body，例如 extra_body={"enable_thinking": True}。
• 流式传 "stream": true。开启思考后，推理 token 计入输出用量，max_tokens 应为推理与正文留足预算；用量以响应的 usage 和账户账单为准。

视频理解：视频用公网 URL 直接传，画面和音轨一起理解（不用 base64、不用抽帧）。原有 qwen3.5-omni-flash 也可继续调用：

复制{
  "model": "qwen3.8-omni-flash",
  "reasoning_effort": "none",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "video_url", "video_url": {"url": "https://你的素材域名/video.mp4"}},
      {"type": "text", "text": "总结这个视频的内容和卖点"}
    ]
  }]
}

DeepSeek V4.1 接入与兼容

deepseek-flash 是当前推荐名称，提供文字与图片理解。deepseek-v4-flash 和 deepseek-v4-flash-vision-exp 继续兼容，由同一代 Flash 模型承接；既有客户端无需立即改名。deepseek-v4-pro 继续独立提供服务。Base URL 和元工 Key 不变。

• Chat Completions：用 thinking.type=enabled/disabled 控制思考；reasoning_effort 建议使用 low/high/max。默认开启思考，强度为 high；SDK中thinking放入extra_body。输出预算包含推理与正文，应按任务留足。
• 思考模式的工具调用使用 tool_choice: auto；不要强制指定某个函数，该组合会被上游拒绝。携带 tools 进行思考模式多轮对话时，后续请求完整回传 assistant 消息的 reasoning_content、tool_calls 及相应 tool 结果，即使某一轮没有实际调用工具。
• 思考模式中 temperature、presence_penalty、frequency_penalty 不生效；top_p 下限为0.95。非思考模式中 top_p 固定为1。
• Responses：使用 POST /v1/responses，以 reasoning.effort=none/low/high/max 控制思考；none表示关闭。接口不保存会话，每轮自行回传完整历史。
• 看图可传URL或Base64；外链/内联单图上限32MiB，请求体上限48MiB，这些是官方限制。支持detail为low/high/original/auto。Files API上传与file_id跨账户路由未列入本次元工接入承诺，请使用URL或Base64。
• 图片与文字计入输入用量，推理计入输出用量；按返回的usage和控制台账单核对。

Kimi K2.8 Preview、K3与旧名称兼容

调用 POST /v1/chat/completions，Base URL与元工Key不变。kimi-k2.8-preview、kimi-k3-256k 是元工模型名，分别映射官方 kimi-for-coding（当前K2.8 Preview）和 k3-256k。直接调用官方时应填写官方ID，不能照搬元工别名。

• kimi-k2.8-preview：当前仅接已核实的K2.8渠道；渠道不可用会返回错误，不自动改用K2.7。旧名称 kimi-k2.7-code 保持已有兼容降级，因此不同请求可能由2.8或2.7承接，不能按名称认定为固定版本。
• kimi-k3-256k：固定256K入口，当前没有第二条同规格备用；支持图片，不支持视频。kimi-k3继续保留，当前主线按256K上下文使用，不承诺所有请求均可使用1M。
• K2.8与K3均支持 reasoning_effort: low/high/max；默认K2.8为max、K3为high。建议按任务显式选定，同一会话尽量保持一致；更换模型或思考程度会影响缓存复用。
• K2.8可用 thinking: {"type":"disabled"} 或 reasoning_effort: "none" 关闭思考。按官方规则，Kimi Code的K3系列关闭思考后也由K2.8无思考能力承接；响应model字段可能仍保留K3名称。旧K3入口若切到其他备用渠道，关闭思考参数可能被拒绝；需要无思考模式请直接选 kimi-k2.8-preview。
• 高速版仍为K2.7 Code，不支持K2.8的三档effort设置；kimi-k2-turbo-preview是高速版旧别名，不要把它当作2.8。
• K2.8图片与视频建议传Base64：image_url.url="data:image/png;base64,..."、video_url.url="data:video/mp4;base64,..."。K3-256K仅使用图片内容项。字段虽叫url，普通公网图片/视频外链也可能被官方拒绝；本次外链实测返回unsupported URL，不能把公网可访问等同于模型接受。Files API/file_id不在当前接入承诺内。输入素材只用于理解，不能通过这些对话模型生成图片或视频文件。
• 工具调用传 tools；思考模式多轮完整回传assistant的 reasoning_content、tool_calls 与对应tool结果。流式使用 stream: true，需要流末用量时传 stream_options: {"include_usage":true}。
• max_tokens预算包含推理和正文；记录返回的usage与控制台账单，不以正文字符数估算总用量。Key受限模型名单仍以 GET /v1/models 为准。

K2.8调用示例（Python SDK中非标准thinking字段放入extra_body）：

{
  "model": "kimi-k2.8-preview",
  "messages": [{"role": "user", "content": "检查这段程序的边界条件"}],
  "reasoning_effort": "high",
  "max_tokens": 4096,
  "stream": true,
  "stream_options": {"include_usage": true}
}

文本向量(Embedding)

POST /v1/embeddings — 标准 OpenAI 格式,模型名 qwen3.7-text-embedding-flash。 把文本转成向量,用于知识库检索(RAG)、语义搜索、相似度计算、聚类与去重;支持多语言与跨语言检索。

复制from openai import OpenAI

client = OpenAI(api_key="您的密钥", base_url="https://pay.uniwork.top/v1")

resp = client.embeddings.create(
    model="qwen3.7-text-embedding-flash",
    input=["退货需要在签收后七天内申请", "How do I return an item?"],
)
vectors = [d.embedding for d in resp.data]   # 顺序与 input 一致,默认每条 1024 维
print(len(vectors), len(vectors[0]), resp.usage.prompt_tokens)

复制curl https://pay.uniwork.top/v1/embeddings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model": "qwen3.7-text-embedding-flash", "input": "退货需要在签收后七天内申请", "dimensions": 512}'

复制// 返回
{
  "object": "list",
  "model": "qwen3.7-text-embedding-flash",
  "data": [
    {"object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, ...]}
  ],
  "usage": {"prompt_tokens": 17, "total_tokens": 17}
}

• 分批:超过 25 条请在业务侧分批调用;返回的 index 对应本次请求内的顺序。
• 维度要一致:同一个向量库里,入库与查询必须使用同一模型、同一 dimensions;更换维度需要整库重新生成。
• 计量:按输入 token 计量,无输出费用;usage.prompt_tokens 即本次计量值。
• 参数错误返回 400(维度不在可选值内、单次超过 25 条、单条超长等),不扣费;修正参数后重试即可,无需退避。

计费补充 · 2026-10-02

以下规则适用于更新后新提交的请求，失败不计费。异步视频已提交的任务沿用提交时规则。最终以账户账单为准，金额按平台最小计费单位取整。

• 万相 3.0 / Prime：按输出时长、参考视频计费时长和实际分辨率结算；输出时长向上取整到秒，参考视频时长以上游回传的计费用量为准。
• Qwen3.5 Omni 音频：分别记录音频输入与音频输出 token，区分文字、图片等其他模态用量。
• Qwen3.8 Omni：文字、图片、音频、视频均计入输入 token，使用相同输入计费标准；缓存命中单独核算。当前仅文本输出，开启思考后的推理 token 也计入输出用量。实际消耗以响应的 usage 和账户账单为准。
• CosyVoice：文本/音频用量与字符计量分别核算，取较高结果，不重复叠加。汉字每字计两个字符，其余每个字符计一个；上游回传字符数时以回传值为准。
• Seedream：按张结算；多参考图请求还需记录参考图数量和输出像素档位，参考素材附加消耗以账户账单为准。
• H3 系列：按输出秒数、分辨率及参考图、视频、音频的实际用量结算。结果或计费信息暂缺时继续查询同一任务，避免重复提交。

图片生成

POST /v1/images/generations

GPT Image 系列:三个模型,同一套参数、同一个价

三个模型的 size / quality / n 和改图接口完全一样,换模型只改 model 字段;三个都按 token 计费。注意:response_format 只有 gpt-image-2 接受,2.5 两款传了会返回 400 Unknown parameter——它们默认就回 b64_json,不要传。

复制curl https://pay.uniwork.top/v1/images/generations \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "简约陶土橙圆形 logo,白色背景",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1
  }'
# 换成 "gpt-image-2" 或 "gpt-image-2.5-sunburst" 即可,其他一个字不改

• 默认返回 b64_json(base64 编码图片),自行解码保存;gpt-image-2 和 seedream 支持 "response_format": "b64_json" / "url";gpt-image-2.5-flare / gpt-image-2.5-sunburst 不接受 response_format(传了 400),按默认 b64_json 处理即可(2026-09-10 实测)
• size:常用 1024x1024 / 1536x1024 / 1024x1536,2K/4K 档(如 2048x2048、3840x2160)也可。09-09 实测 768x1024、1344x2016、2048x1152、2048x2048、1536x2048 三款全部通过,实出尺寸与请求一致
• quality:gpt-image-2 认 low / medium / high / auto(传 standard 会被拒);2.5 两款在此之上多 xhigh / max 两档。越高吐的 token 越多、越贵
• token 用量参考(09-09 实测,flare 与 sunburst 逐档相同):

  规格	gpt-image-2	gpt-image-2.5 flare / sunburst
  768×1024 low	134	134
  1024×1024 low	196	196
  2048×2048 low	—	397
  1536×2048 medium	2223	556
  1536×2048 high	—	2223
  1024×1024 high	7024	—
  1024×1024 xhigh	不支持	3122
  改图 edits 768×1024 low	—	入 798 / 出 134

  2.5 的 medium 只用 2.0 medium 约四分之一的 token;要 2.0 medium 的观感,用 2.5 的 high,token 数相同。
• doubao-seedream-5-0-pro-260628(2026-08-19 实测):size 写精确宽高,像素面积须在 921,600 ~ 4,624,220 之间(如 768x1024 太小、任何 4K 档太大,都返回 400)——即 不支持 4K;不支持组图(sequential_image_generation 会被忽略,只回 1 张、不报错,多张请多次调用);默认带「AI生成」角标,加 "watermark": false 即无;无参考图/单参考图按张计量，多参考图见计费补充
• 把 seedream 当 GPT Image 系列的兜底时,切换前先把尺寸映射进上面的像素区间、多张拆成多次调用

参考图改图 / 多图合成

都能改图,但走的门不同,别用混:

复制# GPT Image 系列:multipart 传文件(精修推荐 sunburst,换成 gpt-image-2 / flare 同样可用)
curl https://pay.uniwork.top/v1/images/edits \
  -H "Authorization: Bearer $KEY" \
  -F model=gpt-image-2.5-sunburst \
  -F image=@pet.jpg \
  -F image=@clothes.jpg \
  -F prompt="让这只宠物穿上这件衣服,保持宠物原本的样貌"

复制# seedream:generations + image 字段(公网 URL 或 data:base64 直塞,单图字符串或多图数组)
curl https://pay.uniwork.top/v1/images/generations \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "把这个logo的颜色改成深蓝色,其他保持不变",
    "image": "https://您的图片URL.png",
    "size": "1024x1024",
    "watermark": false
  }'

视频生成

视频为异步任务:提交后立即返回任务 ID,轮询至完成后取视频地址。

两个端点,按需选门

以下详述功能全版(门二):

① 提交任务

POST /v1/video/generations

复制// 文生视频
{
  "model": "doubao-seedance-2-0-mini-260615",
  "prompt": "一只橘猫从木桌轻盈跳下,午后阳光客厅,写实风格",
  "metadata": { "duration": 5, "ratio": "9:16", "resolution": "720p" }
}

复制// 图生视频(以图片作为首帧)
{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "镜头缓慢推进,人物从静止到抬头微笑",
  "metadata": {
    "duration": 8, "resolution": "720p",
    "content": [
      {"type": "image_url",
       "image_url": {"url": "https://.../first.jpg"},
       "role": "first_frame"}
    ]
  }
}

复制// 口型重配:人物视频 + 人声音频 → 口型对上的新视频
{
  "model": "videoretalk",
  "prompt": "lip sync",
  "metadata": {
    "content": [
      {"type": "video_url", "video_url": {"url": "https://.../person.mp4"}},
      {"type": "audio_url", "audio_url": {"url": "https://.../speech.mp3"}}
    ]
  }
}

复制// 万相 wan3.0:同一个门,换 model 名即可(参数放 metadata 根)
{
  "model": "wan3.0-video",
  "prompt": "一只橘猫在窗台上晒太阳,轻轻摇尾巴,写实风格",
  "metadata": {
    "resolution": "480P", "duration": 5, "audio": true,
    "content": [
      {"type": "image_url",
       "image_url": {"url": "https://.../first.jpg"},
       "role": "first_frame"}
    ]
  }
}

MiniMax H3 系列视频生成

minimax-h3-max-turbo、minimax-h3-max、minimax-h3 使用元工 key 调用。POST /v1/video/generations 提交；推荐 GET /v1/videos/{id} 轮询，状态为 queued → in_progress → completed / failed，成功后读取 metadata.url。H3 接受 fal 官方生成参数原名，直接放 JSON 顶层或放入 metadata；同名字段以 metadata 为准。原有 metadata.content 写法继续支持。

模型与入口

三款均为 5–15 秒、24 fps、有声视频。Max/Turbo 的 1080P 是由 768P 基础结果进行潜空间细化；H3 的 2K/4K 是从 768P 放大，不能理解为原生 2K/4K。兼容别名 720P → 768P；仅基础 H3 保留旧别名 1080P → 2K。Max/Turbo 的 1080P 按 1080P 提交，不再降到 768P。建议始终显式指定分辨率。

resolution 是模型档位，具体像素随画幅变化；duration 是请求时长，成片可能有帧长偏差。2026-09-14 实测 H3 的 480P / 21:9 / 6秒 返回 960×416、约6.592秒，元工保留上游原始文件。metadata.resolution / metadata.duration 记录提交值，不是成片测量值；对精确像素或片长有要求时，请核验返回媒体。

官方参数完整表

以下覆盖三款模型当前的文生、图生和参考生视频接口（2026-09-14 核对）。

参考图、视频、音频合计最多 12 份。这些是官方要求。素材可传上游能读取的公开 URL（含有效签名链接）或 Base64 data URI；元工不额外设置文件大小上限，素材格式和时长由上游校验。

入口选择：有参考素材参数进入参考生视频；有首帧或尾帧进入图生视频；其余进入文生视频。首尾帧与参考素材属于不同官方接口，不能混用。图生的画幅跟随首帧（仅尾帧时跟随尾帧），aspect_ratio 不用于覆盖图片画幅。Turbo 官方没有参考生视频接口，参考素材请使用 H3 / Max。

原生参数示例：Max 参考视频生成 1080P

复制{
  "model": "minimax-h3-max",
  "prompt": "参考 Video 1 的运动方式，让红色产品缓慢旋转，保持 Image 1 的外观，背景安静。",
  "resolution": "1080P",
  "duration": 5,
  "aspect_ratio": "16:9",
  "seed": 123,
  "prompt_expansion_mode": "balanced",
  "enable_safety_checker": true,
  "sync_mode": false,
  "reference_image_urls": ["https://example.com/product.png"],
  "reference_video_urls": ["https://example.com/motion.mp4"]
}

原生参数示例：Turbo 单尾帧

复制{
  "model": "minimax-h3-max-turbo",
  "prompt": "镜头缓慢靠近，最后停在图片中的产品构图。",
  "duration": 5,
  "resolution": "1080P",
  "end_image_url": "https://example.com/end.png",
  "prompt_expansion_mode": "balanced"
}

兼容元工原有素材写法

metadata.content 中的 first_frame / last_frame 映射为 image_url / end_image_url；reference_image、video_url、audio_url 分别映射到对应的三个参考数组，素材顺序保留。metadata.ratio 是 aspect_ratio 的别名，seconds 是 duration 的别名；重复提供不同值会报错。推荐一次请求只选一种素材写法。

复制{
  "model": "minimax-h3-max",
  "prompt": "参考 Video 1 的动作，保持 Image 1 的产品外观。",
  "metadata": {
    "duration": 5,
    "resolution": "1080P",
    "ratio": "16:9",
    "prompt_expansion_mode": "balanced",
    "content": [
      {"type":"image_url","image_url":{"url":"https://example.com/product.png"},"role":"reference_image"},
      {"type":"video_url","video_url":{"url":"https://example.com/motion.mp4"},"role":"reference_video"}
    ]
  }
}

从 Seedance 切换时，检查 H3 的 5–15 秒范围和模型档位；generate_audio、audio、camera_fixed、watermark、return_last_frame、frames、draft 等参数并非这几个 fal 接口的官方参数。中台会明确提示不支持，不会悄悄丢掉后继续生成。需要的声音效果请写在提示词中。

结果字段与计费

• 队列完成不等于生成成功：上游已保存的明确终态错误（包括部分504）会返回 failed 并退回预扣；单纯查询网络故障或计费信息暂缺继续查询原任务，避免误判和重复生成。
• 推荐轮询 GET /v1/videos/{id}：成片在 metadata.url；metadata.fal_result 保留 fal 返回的完整结果，包括 video、seed、expanded_prompt、timings 等实际返回字段，字段是否存在取决于所选模型。metadata.resolution / metadata.duration 为提交档位和时长。
• 原任务接口 GET /v1/video/generations/{id} 保持原结构：外层 code=success 表示查询成功，不代表视频生成成功。任务状态看 data.status（SUCCESS / FAILURE 等）；原始结果看 data.data，成片在 data.data.content.video_url，完整 fal 结果在 data.data.fal_result。
• sync_mode=true 时上述成片字段为 data:video/mp4;base64,...；否则为临时 CDN URL，拿到后及时转存。
• 输出按提交秒数和分辨率结算；参考输入使用上游实际计费单位结算。生成失败不收取生成费；结果或计费信息暂时不可读时继续查询同一任务，避免重复提交。

H3 轻量轮询与成片下载（可选）

现有调用方式与默认响应保持不变。需要减少轮询返回体时，用 GET /v1/videos/{id}?view=compact，继续读取 status 和 metadata.url；该模式省略 metadata.fal_result，不返回视频 Base64。仅适用于 H3 系列，不改变生成参数或计费。需要完整原生结果时，查询不带 view=compact 的原接口。

• sync_mode=false（推荐用于网站/小程序）：上游返回临时 CDN 视频链接；轻量查询仍返回该链接，请及时下载转存。
• sync_mode=true：官方 Base64 能力继续支持，默认查询仍返回完整 data URI；轻量查询把 metadata.url 换成元工 /v1/videos/{id}/content 下载地址。由后端使用同一用户的元工 key、携带 Authorization: Bearer ... 下载，支持 GET、HEAD 和字节 Range；其他用户无法读取。不要把 key 暴露在浏览器页面中。
• H3 建议由一层后台任务每 3–5 秒查询一次，避免前后端轮询间隔叠加。单次查询暂时失败时保留任务 ID，稍后继续查询；不要因此重复提交生成。
• sync_mode 决定成片以链接还是 Base64 返回，不代表同步生成或加速开关。timings.inference 等模型计算时间不包含完整的排队、网络传输和业务保存耗时。

curl 'https://pay.uniwork.top/v1/videos/TASK_ID?view=compact' \
  -H 'Authorization: Bearer YOUR_UNIWORK_KEY'
# 仅当 metadata.url 为元工 /v1/videos/{id}/content 地址时，携带元工 key 下载：
curl 'https://pay.uniwork.top/v1/videos/TASK_ID/content' \
  -H 'Authorization: Bearer YOUR_UNIWORK_KEY' -o result.mp4

seedance ↔ wan3.0 切换对照

两家走同一个任务门,提交/轮询/参考图写法完全一致,改 model 名即切;差异只有这几处:

H3 支持官方原生参数，其字段与默认值见上方 H3 专节。

② 轮询结果

GET /v1/video/generations/{task_id}：外层 code=success 仅表示查询成功，任务状态看 data.status（SUCCESS / FAILURE 等）；原始结果在 data.data，视频地址在 data.data.content.video_url。也可查询 GET /v1/videos/{task_id}，成功状态为 completed，视频地址在 metadata.url。建议轮询间隔 8–10 秒。

语音合成

POST /v1/audio/speech — 响应体直接是音频二进制(默认 mp3),保存即可播放。

复制curl https://pay.uniwork.top/v1/audio/speech \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"cosyvoice-v2","input":"欢迎使用元工智能","voice":"longxiaochun_v2"}' \
  -o out.mp3

声音克隆(创建专属音色)

克隆走独立管理接口(同一把密钥鉴权),得到 voice_id 后照常走 /v1/audio/speech 合成:

复制# 创建音色(audio_url = 10-20 秒干净人声,公网可访问)
curl https://pay.uniwork.top/voice/clone \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"provider": "aliyun", "audio_url": "https://.../sample.mp3", "name": "boss"}'
# → {"voice_id": "cosyvoice-v3.5-flash-boss-xxxx"}

# 用克隆音色合成(可带情绪指令与语速)
curl https://pay.uniwork.top/v1/audio/speech \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model": "cosyvoice-v3.5-flash", "input": "你好", "voice": "克隆返回的voice_id",
       "instructions": "用非常开心、兴奋的语气说", "speed": 1.2}' -o out.mp3

• provider:目前只支持 aliyun;可选 target_model:cosyvoice-v3.5-flash(默认)或 cosyvoice-v3.5-plus(高保真)——音色与所选模型绑定,不互通,换档要重克隆
• 音色按账户隔离:list 只返回你自己创建的音色,delete 只能删自己的;新克隆的 voice_id 前缀是账户标识(如 u113-),name 仅作为你自己系统里的显示名
• voice_id 请当密钥保管:持有 id 即可用该音色合成,不要写进小程序前端 / 网页 JS / 公开仓库
• instructions:情绪/语气自然语言指令(如"用温柔安抚的语气说"),仅 cosyvoice-v3.5-flash + 克隆音色生效;注意是复数拼写,单数会被网关忽略
• speed:语速 0.5–2.0,超出取边界值
• 管理接口:GET /voice/list?provider=aliyun 列音色、POST /voice/delete 删音色;每小时限 20 次管理操作
• 克隆音色偶发"音色未就绪"报错,重试 1-2 次即可
• audio_url 也支持 data:audio/mpeg;base64,... 直塞——没有对象存储可以把样本直接放进请求体(样本通常不到 1MB)

正文富文本标记(局部控制)

instructions 控制整段语气,富文本标记控制单个词或单句,两者可同时使用。 标记直接写在 input 正文里,不会被朗读出来:

复制curl https://pay.uniwork.top/v1/audio/speech \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model": "cosyvoice-v3.5-flash", "voice": "克隆返回的voice_id",
       "input": "这款抽纸<strong>130抽</strong>,湿水<strong>不易破</strong>[breath],囤起来很划算。",
       "instructions": "用开心、有感染力的带货语气说", "speed": 1.1}' -o out.mp3

cosyvoice-v2 常用系统音色:longxiaochun_v2(标准女声)、 longwan_v2(温柔女声)、longyue_v2(客服女声)、longshu_v2(男声)。 单次文本建议不超过 2000 字。

语音识别(转文字)

POST /v1/audio/transcriptions — multipart 表单上传音频文件(与 OpenAI 官方一致)。 返回文本,并附带逐词时间戳,可直接用于生成字幕或卡点。

复制curl https://pay.uniwork.top/v1/audio/transcriptions \
  -H "Authorization: Bearer $KEY" \
  -F model=qwen-audio-3.0-asr-flash \
  -F file=@voice.mp3

复制// 返回
{
  "text": "hello world,这里是阿里巴巴语音实验室。",
  "words": [
    {"word": "hello", "start": 0.6, "end": 1.0},
    {"word": " world,", "start": 1.0, "end": 1.28}
  ]
}

音频不超过 5 分钟、10 MB。须上传文件本体,暂不支持只传音频 URL。

音乐 / BGM 生成

POST /v1/chat/completions — 与对话同一个接口,任何 OpenAI SDK 直接可用。 一次调用直接返回成品音频链接,无需轮询;实测约 60-90 秒出一首,单曲最长约 2.5 分钟。 按首计费,生成失败不计费。

复制# 一句风格描述 = 一首纯音乐 BGM
curl https://pay.uniwork.top/v1/chat/completions \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"music-3.0","messages":[{"role":"user","content":"轻快明亮的企业宣传片背景音乐,现代电子,积极向上"}]}'

返回体 choices[0].message.content 是音频直链(24 小时有效,请及时转存), 同时给了顶层 audio_url 与 duration(秒)方便直接取用。

要带人声的歌:把 content 写成 JSON 字符串,给 lyrics(用 [verse] / [chorus] 分段):

复制{"model": "music-3.0", "messages": [{"role": "user", "content":
  "{\"prompt\":\"流行,温暖,女声\",\"lyrics\":\"[verse]\\n街灯微亮晚风轻抚\\n[chorus]\\n推开木门香气弥漫\"}"}]}

• 模型:music-3.0(推荐)、music-2.6
• content 为纯文本时 = 风格描述,默认出纯音乐(BGM 场景);给了 lyrics 则出带唱的歌
• JSON 形态可选字段:prompt(≤2000 字)、lyrics(≤3500 字)、is_instrumental、format、sample_rate、bitrate
• 只给风格、让 AI 自动写词并唱:加 "lyrics_optimizer": true(lyrics 留空)。实测约 2 分钟出一首 3 分钟完整歌。
• 单次请求耗时较长,客户端超时请设 ≥180 秒

只作词不出歌(model = music-lyrics)

先出词、让用户看/改,满意再送去唱——比 lyrics_optimizer 多一道"人工过目"。返回带 [Intro]/[Verse]/[Chorus]… 结构标签的完整歌词 + 自动起的歌名 + 风格标签,秒级返回。

复制# 纯文本 = 歌曲主题,写整首;顶层另给 song_title / style_tags / lyrics
{"model": "music-lyrics", "messages": [{"role": "user", "content": "一首关于宠物服饰店开业的欢快歌"}]}

# 续写 / 改写已有歌词
{"model": "music-lyrics", "messages": [{"role": "user", "content":
  "{\"mode\":\"edit\",\"lyrics\":\"[Verse]\\n已有的词…\",\"prompt\":\"扩写成完整一首\"}"}]}

• mode:write_full_song(默认)/ edit(需给 lyrics);可加 title 指定歌名
• 拿到的 lyrics 可原样塞给 music-3.0 唱出来;按次计量

翻唱(model = music-cover)

拿一段参考音频,换新歌词 / 换风格重唱——门店主题曲、活动歌、把喜欢的曲子换成自己的词,都靠它。

复制{"model": "music-cover", "messages": [{"role": "user", "content":
  "{\"audio_url\":\"https://.../reference.mp3\",\"lyrics\":\"[verse]\\n晨光穿过木窗\\n[chorus]\\n每一分钱花得明白\",\"prompt\":\"保持原曲风格\"}"}]}

• 参考音频:公网 URL(或 audio_base64),6 秒 – 6 分钟、≤ 50MB
• lyrics:新歌词,10–1000 字;不给则用从参考音频自动提取的原词(= 纯换风格)
• prompt:目标风格(可选,默认"保持原曲风格");想换风格就写,如"改成慢板抒情,钢琴伴奏"
• 返回顶层多带:cover_feature_id(24 小时内可复用——再出新版本时直接传它、免去重新分析,快约 30 秒)、 source_lyrics(从参考音频提取的原词,带分段)、structure(歌曲结构与时间戳)
• 实测:首次翻唱约 85 秒(含分析),复用 cover_feature_id 约 55 秒;按首计量

用量查询

错误处理

错误响应格式:{"error": {"message": "...", "type": "..."}}

图片接口最终结果 · v2.11（2026-09-11）

POST /v1/images/generations 和 /v1/images/edits 遇到可重试故障时，平台先在重试预算内执行可用渠道切换，再返回成功或最终失败。成功响应体保持不变。不同模型和账户的备用能力可能不同。

请将响应头 X-Uniwork-Request-Id 与业务任务 ID 一起保存。失败体另含 error.request_id、error.retryable、error.retried（平台重发次数，v2.18），审核拒绝另含 error.reason；该 ID 用于日志核查，当前不是可查询成品的异步任务 ID。

调用方超时或连接中断也可能是结果未知，不能只凭超时认定未生成。成功收到 HTTP 响应后，调用方仍需完成成品保存与展示。

接入建议

1. 按终端用户记账 —— 若您的产品面向自己的用户,请将每次调用的 usage 记入自己的数据库,按控制台上的单价换算后扣减该用户余额。平台侧仅对您的账户结总账。
2. 设置用量上限 —— 为每个终端用户设置日限额(如每天最多生成 N 条视频),避免单个用户异常消耗。
3. 长任务落库 —— 视频任务 ID 持久化保存,轮询放在后台队列执行,不要挂在 HTTP 请求中同步等待。
4. 并发控制 —— 建议业务侧限制并发:视频约 10 路、图片约 20 路;超出部分排队,体验更稳定。
5. 内容合规 —— 对外发布的 AI 生成图片 / 视频,请按《人工智能生成合成内容标识办法》添加标识; 小程序、App 等场景请接入平台方的内容安全审核接口。
6. 模型选择 —— 新接入优先评估 deepseek-flash 的文字、图片理解与工具能力；deepseek-v4-pro 保留，按具体任务效果选择。