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-v4-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-v4-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-v4-flash","messages":[{"role":"user","content":"你好"}]}'

模型总表

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

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

对话与图片理解

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

流式输出

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

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

图片理解

复制{
  "model": "kimi-k2.7-code",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://.../photo.jpg"}},
      {"type": "text", "text": "这张商品图有什么卖点?"}
    ]
  }]
}

图片生成

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 即无;按张一口价,1K/2K 同价
• 把 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)

同一个任务门,5-15 秒、24 fps、原生有声且对白口型同步;素材决定入口:first_frame(可加 last_frame)=首帧图生,reference_image / audio_url=参考生视频(锁人脸、道具、声线),都不带=文生。turbo 只有文生和首帧图生(最快最便宜),max 多参考生视频,h3 多 2K / 4K 档。

复制// MiniMax H3 Max:参考图锁同脸 + 参考音频锁声线,对白直接写在提示词里
{
  "model": "minimax-h3-max",
  "prompt": "中式书房,老人接过飞机模型笑了。老人说:\"第一架不是。后头三架,有我一份。\" 环境音:窗外鸟鸣。无音乐,画面无字幕",
  "metadata": {
    "resolution": "768P", "ratio": "9:16", "duration": 8,
    "content": [
      {"type": "image_url", "image_url": {"url": "https://.../老人.png"}, "role": "reference_image"},
      {"type": "audio_url", "audio_url": {"url": "https://.../声音样本.mp3"}}
    ]
  }
}

• resolution:turbo / max 为 480P / 768P,h3 另有 2K / 4K;写 720p 自动落 768P。duration 5–15。参考视频(video_url)暂不受理;turbo 带参考素材会被拒绝并提示换模型。
• 对白写法 角色说:"台词",一镜一人;提示词里写明"无音乐、画面无字幕"。
• 计费按提交秒数 × 分辨率(失败不计费):turbo 480P=6250 token/秒、768P=1 万;max 12500 / 2 万;h3 12500 / 15000 / 32500 / 4 万;参考图前 4 张免费,之后每张 5000 token。单价看门户。
• 结果 URL 保留期不长,拿到立即转存。

seedance ↔ wan3.0 切换对照

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

② 轮询结果

GET /v1/video/generations/{task_id} — 状态流转 queued → running → succeeded / failed。 成功后响应中 content.video_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 秒;按首计费,与 music-3.0 同价

用量查询

错误处理

错误响应格式:{"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；该 ID 用于日志核查，当前不是可查询成品的异步任务 ID。

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

接入建议

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