图像 / 视频 / 音乐 API

除四个聊天协议端点外,本平台还提供三类媒体端点。鉴权方式与聊天端点完全一致 —— 同一把 sk-gpushare-* Key,四种方式任选(x-api-key / x-goog-api-key header / ?key= query / Authorization: Bearer),详见 鉴权。所有计费都扣账户余额(全部 Key 共享),余额不足返回 402 quota_exceeded。

这些端点的响应都带 x-gateway-trace header,报障时可连同时间戳、model 与完整错误体一起提供。

重试不会重复扣费：Idempotency-Key#

所有会扣费的 POST 端点（图片 / 视频 / 音乐 / 语音合成 / 音色克隆 / 数字人形象 / 文案提取）都支持 Idempotency-Key 请求头。带上它，同一个请求重发多少次都只会真正执行一次：

IDEM=$(uuidgen)   # 一个提交意图一把键，这次提交的每一次重试都复用它

curl https://jiuye.zsopc.com/v1/videos/generations \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEM" \
  -d '{"model":"doubao-seedance-2-0-260128","prompt":"海边日落","duration":5}'

• 重发同一把键 + 同样的请求体 → 原样返回第一次的响应（含同一个任务 id），响应头多一个 Idempotency-Replayed: true，不会再开一次任务、不会再扣一次钱。
• 这也是找回任务 id 的最简单办法：忘了保存返回的 id？把当初那条 curl 原样再跑一遍（键和请求体都不变），返回的就是原来那条任务。
• 保留期 7 天；超过后同一把键会被当作新请求。
• 键要求：1–200 个可打印 ASCII 字符（推荐直接用 UUID），一个提交意图一把，不要跨不同请求复用。
• 作用域是账号，不是单把 API Key：同一账号下换一把 sk-gpushare-* 重发同一个 Idempotency-Key，一样命中重放。（钱包本来就是全账号共享的，跨 Key 不去重才会漏。）
• 并发：同一把键的两个请求同时到达时，只有一个会真正执行，另一个立刻拿到 409 idempotency_in_flight——不会两个都跑。

import uuid, requests

idem = str(uuid.uuid4())           # 一个提交意图一把键
body = {
    "model": "doubao-seedance-2-0-260128",
    "content": [{"type": "text", "text": "海边日落，无人机航拍"}],
    "duration": 5,
}

def submit():
    r = requests.post(
        "https://jiuye.zsopc.com/v1/videos/generations",
        headers={
            "Authorization": f"Bearer {PLATFORM_API_KEY}",
            "Idempotency-Key": idem,          # ← 每次重试都用同一把
        },
        json=body,
        timeout=60,
    )
    r.raise_for_status()
    # 重放时这个头是 "true"，说明拿到的是第一次的结果，没有二次计费
    replayed = r.headers.get("Idempotency-Replayed") == "true"
    return r.json()["id"], replayed

task_id, _ = submit()
task_id_again, replayed = submit()   # 丢了 id？原样再调一次
assert task_id == task_id_again and replayed

const idem = crypto.randomUUID();          // 一个提交意图一把键

async function submit() {
  const res = await fetch("https://jiuye.zsopc.com/v1/videos/generations", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${PLATFORM_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": idem,             // ← 每次重试都用同一把
    },
    body: JSON.stringify({
      model: "doubao-seedance-2-0-260128",
      content: [{ type: "text", text: "海边日落，无人机航拍" }],
      duration: 5,
    }),
  });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return {
    id: (await res.json()).id,
    replayed: res.headers.get("Idempotency-Replayed") === "true",
  };
}

只有 2xx 会被记住。上游报错、参数错误等失败不会占用这把键，可以直接用同一把键重试。

找回任务 id#

异步任务（视频 / 音乐 / 语音合成）提交后返回一个任务 id。万一没保存，有三条路，按从易到难排：

1. 原样重发那条 curl（带同一个 Idempotency-Key）→ 直接拿回原任务 id。见上一节。
2. 列出任务：GET /v1/videos/generations、GET /v1/music/generations、GET /v1/audio/speech。默认返回全部状态（含排队中、生成中、已失败），按提交时间倒序，?limit= 默认 30 最大 100。
   复制

   curl "https://jiuye.zsopc.com/v1/videos/generations?limit=10" \
     -H "Authorization: Bearer $PLATFORM_API_KEY"
   

   ?status= 可筛选，逗号多选：视频用 queued,running,succeeded,failed,expired,cancelled,all；音乐用 processing,succeeded,failed,expired,cancelled,all；语音合成用 pending,succeeded,failed,all。传 ?status=succeeded 即为 2026-07-31 之前的旧默认行为。
3. 调用日志站 logs.dflop.top：搜索框同时按 任务 ID 与 请求 ID 反查（粘进去就行，不用分辨手里那串是哪一种）。异步任务（视频 / 音乐 / 语音 / 数字人形象 / 音色）的记录会带任务 ID；聊天、出图、文案提取这类没有任务行的调用只有请求 ID。
   • 请求 ID 就是响应头 x-gateway-trace 的值。
   • ⚠️ 异步任务要跑到终态结算后才会在这里入账；还在生成中的任务请用上面第 2 条的列表端点。日志默认只查最近 30 天。

POST /v1/images/generations#

OpenAI Images API 兼容形状,同步返回。

可用模型#

size 原样透传给上游,gateway 不改写 —— Seedream 4.5/5.0 传小于 1920×1920 会直接拿到上游的 400 错误。Seedream 5.0 Pro 按请求的输出像素面积分档计费(阈值 236 万像素 ≈ 1536×1536)。

请求#

{
  "model": "doubao-seedream-4-5-251128",
  "prompt": "一只在竹林里喝茶的熊猫,水彩风格",
  "size": "2048x2048",
  "n": 1
}

响应#

{
  "model": "doubao-seedream-4-5-251128",
  "created": 1765432100,
  "data": [{ "url": "https://...", "size": "2048x2048" }],
  "usage": { "generated_images": 1, "output_tokens": 4096, "total_tokens": 4096 }
}

响应是上游原样透传(OpenAI Images 形状),usage 各字段以上游实际返回为准。

curl#

curl https://jiuye.zsopc.com/v1/images/generations \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4-5-251128",
    "prompt": "一只在竹林里喝茶的熊猫,水彩风格",
    "size": "2048x2048"
  }'

限制#

• 返回的图片 URL 是上游预签名链接,约 24 小时过期 —— 拿到后请尽快下载转存到自己的存储
• 同步接口。gateway 对上游的单跳超时是 240 秒(IMAGES_UPSTREAM_TIMEOUT_SECS),整条渠道阶梯的总上限是 280 秒(IMAGES_LADDER_DEADLINE_SECS)。多数 SKU 生成耗时 5–20 秒,但 gpt-image-2 实测 60–215 秒 —— 客户端超时请设 ≥ 300 秒,否则会在网关仍在正常等待时被自己的超时打断(费用照产生,结果拿不到)
• 错误为 OpenAI 形状 {"error": {"code", "message", "param", "type"}},上游 4xx/5xx 原状态码 + 原响应体透传(不计费)

Nano Banana 家族(nano-banana 15.77/张、nano-banana-pro 54.19/张、nano-banana-2 16.18/张)也走本端点按张计费;nano-banana-2 的响应以 b64_json 返回(自建首跳),其余通常返回 URL。旧 id(gemini-2.5-flash-image / gemini-3-pro-image-preview / gemini-3.1-flash-image(-preview) / tvod-nano-*)作为 alias 长期兼容。

POST /v1/videos/generations#

异步任务:提交后立即返回任务 id,轮询查询直到 succeeded。

可用模型#

提交#

{
  "model": "doubao-seedance-1-0-pro-fast-251015",
  "content": [
    { "type": "text", "text": "海边日落,无人机航拍视角 --ratio 16:9" }
  ],
  "duration": 5
}

grok 视频转译细节:grok SKU 走 xAI 上游,gateway 自动把上面的 Seedance 形状转译成 xAI 形状。content 里追加 {type:"video_url", video_url:{url:"https://..."}} 参考视频时,任务路由到 video-to-video 端点 —— 默认改写(按 prompt 重绘整段,沿用源视频比例/分辨率,不接受自定义 duration);video_mode: "extend" 切到续写(从末帧续 duration 秒,2–10 秒)。图生视频时 gateway 刻意不下发 ratio(跟随源图原生比例,避免拉伸变形)。

真人出镜(真实人脸)#

doubao-seedance-2.0 / doubao-seedance-2.0-fast / doubao-seedance-2.0-mini 三个 SKU 支持上传真人照片生成真人出镜视频。真人合规链路完全在 gateway 内部完成,调用方无需任何特殊步骤 —— 用普通图生视频形状提交即可,gateway 自动把参考图送审并入库(换成合规素材句柄)后再生成。若首选渠道拒绝真人图,gateway 自动切换到支持真人素材化的渠道,对调用方透明。

{
  "model": "doubao-seedance-2.0",
  "resolution": "720p",
  "duration": 5,
  "content": [
    { "type": "text", "text": "照片中的人对着镜头微笑挥手,背景不变" },
    { "type": "image_url", "image_url": { "url": "https://your-cdn.com/face.jpg" } }
  ],
  "portrait_auth": true
}

多模态参考(仅 Seedance 2.0 系):除单张首帧图外,content[] 还可携带带 role 的参考媒体项 —— {type:"image_url", role:"reference_image", image_url:{url}} / {type:"video_url", role:"reference_video", video_url:{url}} / {type:"audio_url", role:"reference_audio", audio_url:{url}}(参考图上限 10 张)。所有外部图同样走上述公网 URL + 自动送审规则。

响应:

{ "id": "9f2c...", "status": "queued", "model": "doubao-seedance-1-0-pro-fast-251015", "created_at": 1765432100 }

提交本身是同步 HTTP(gateway 对上游超时 60 秒),生成在后台异步进行,不占请求时长。

数字人扩展字段(dh-avatar)#

数字人 dh-avatar 复用同一视频提交端点,在请求体顶层追加以下字段(duration 必填 —— 取驱动音频/文案预估秒数,缺失返回 400)。⚠️ 数字人是两段式:必须先有一个可复用的数字人形象 avatar —— 在站内「克隆形象」上传照片/视频创建(平台公共形象因上游不返预览图已从站内下线);sk-key 直调传已有的形象 id 即可。

视频时长 = 驱动音频/文案时长(上游自测真实时长,无固定上限)。duration 仅用于计费预留,结算按上游实际秒数。

注意事项:

• 输入媒体 URL 必须公网可直接访问(本平台 r2.dflop.top 上传产物可直接使用);
• 成片按中国 AIGC 内容标识要求自动叠加"AI 生成"标识。

智能剪辑扩展字段(clip-realman / clip-mixcut / clip-news)#

智能剪辑三个 SKU 复用同一视频提交端点,在请求体顶层追加以下字段。三者共用 style_id(模板 id)、title、language、materials[]、bgm、cover_url,各自另有必填项。成片长度由源媒体决定(realman=源视频、mixcut=口播音频、news=duration),duration 对 realman/mixcut 仅供计费参考、不下发上游。

{
  "model": "clip-realman",
  "style_id": "tpl_xxx",
  "title": "今日要闻",
  "source_video_url": "https://your-cdn.com/talk.mp4",
  "materials": [
    { "type": "image", "file_url": "https://your-cdn.com/a.jpg" },
    { "type": "video", "file_url": "https://your-cdn.com/b.mp4", "sound_switch": false }
  ],
  "bgm": { "mode": "auto" }
}

计费:按成片实际时长(轮询返回的真实秒数)计费。外部 sk-key 提交时按 clip 成片上限(300 秒)预留余额,任务成功后结算退到实际时长;若显式传更长的 duration(如长源视频),按其预留。余额不足返回 402。失败/过期全额退回。

模板 id:style_id 取自平台智能剪辑模板库;当前模板发现仅在站内数字人工作台内可见,sk-key 直调需使用已知的模板 id。

素材与媒体要求（上游硬限）#

所有 URL 必须公网可直接拉取。以下限制与上游一致,不满足会被上游拒(站内数字人工作台在上传时已就格式/分辨率/时长/大小先行校验)。

• 素材总时长 ≤ 5 分钟:图片各按 2s、视频按实际时长累加,超出上游拒。
• 真人口播源视频画面内音频需能语音转文本(用于自动字幕);无清晰人声会失败。
• clip-news 的成片时长由 duration(5–300s)控制;clip-realman/clip-mixcut 成片时长分别由源视频 / 口播音频决定。

轮询#

curl https://jiuye.zsopc.com/v1/videos/generations/$TASK_ID \
  -H "Authorization: Bearer $PLATFORM_API_KEY"

status 取值:queued → running → succeeded / failed / expired / cancelled。

在飞行任务(queued / running)的响应可能带 progress(0-100 整数,上游生成进度)——仅在上游报告进度时出现,当前只有 Seedance 2.0 真人出镜档提供;字段缺失表示该模型无进度数据,不代表 0%。

成功时:

{
  "id": "9f2c...",
  "status": "succeeded",
  "model": "doubao-seedance-1-0-pro-fast-251015",
  "created_at": 1765432100,
  "video_url": "https://...",
  "expires_at": 1765435700
}

失败时带 error: {code, message}。生成一般需要 1–5 分钟,建议 5–10 秒一次轮询。

任务 id 仅本账号可见 —— 查询不存在或他人的任务一律返回 404(code: "not_found"),不做区分。

列出任务#

GET /v1/videos/generations(不带 id)—— 本账号的视频任务,按提交时间倒序。免费。 没保存任务 id 时用它找回,也可以直接当"生成记录"用。

2026-07-31 起默认返回全部状态。此前默认只返回 succeeded,导致"任务还在跑时列表是空的"。要回到旧行为传 ?status=succeeded。

{
  "data": [
    {
      "id": "9a31d5c2-5c13-4caf-ad8b-1ee70ff5887f",
      "status": "running",
      "model": "doubao-seedance-2.0-fast-cheap",
      "created_at": 1785495460,
      "progress": 42
    },
    {
      "id": "ed2ab10b-ceb1-4d0c-8c25-84ade94c95ac",
      "status": "succeeded",
      "model": "doubao-seedance-1-0-pro-fast-251015",
      "created_at": 1785490000,
      "video_url": "https://...",
      "expires_at": 1786094800
    }
  ]
}

import requests
r = requests.get(
    "https://jiuye.zsopc.com/v1/videos/generations",
    headers={"Authorization": f"Bearer {PLATFORM_API_KEY}"},
    params={"limit": 20},                       # 想只看在飞的:{"status": "queued,running"}
    timeout=30,
)
for t in r.json()["data"]:
    print(t["id"], t["status"], t.get("video_url", ""))

计费口径#

• 提交时按 单价 × duration 从账户余额预留(缺 duration 按 12 秒预留);余额不足返回 402
• 任务终态结算:成功按实际时长计费(上游未报实际时长时按请求秒数兜底),失败/过期全额退回;提交阶段任何失败(上游报错、任务落库失败)也即时退回预留
• GET /v1/videos/generations(不带 id)列出本账号的任务,默认返回全部状态(?limit= 默认 30 最大 100;?status=succeeded 可只看成功的),可用于"生成记录"与找回丢失的任务 id —— 详见 找回任务 id

限制#

• 成功的视频会自动转存到本平台对象存储,video_url 是 7 天有效的预签名链接(expires_at 为过期时间);过期后重新调用列表端点会自动重签新链接
• 上游内容审核可能在生成完成后拦截(OutputVideoSensitiveContentDetected 类错误码),该情况按失败处理不计费

POST /v1/music/generations#

Suno AI 音乐生成,异步任务形状与视频端点一致:提交返回任务 id,轮询到终态。一次生成产出 2 首完整歌曲(含歌词与封面图)。

可用模型#

请求#

curl https://jiuye.zsopc.com/v1/music/generations \
  -H "Authorization: Bearer $GPUSHARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v5.5",
    "prompt": "一首关于夏天海边散步的轻快中文流行歌"
  }'

prompt 与 lyrics 至少传一个(纯音乐 instrumental: true 时可都省)。响应:{"id": "<task_id>", "status": "queued", "model": "...", "created_at": ...}。

查询任务#

curl https://jiuye.zsopc.com/v1/music/generations/$TASK_ID \
  -H "Authorization: Bearer $GPUSHARE_API_KEY"

status 取值 processing | succeeded | failed | expired。成功时 tracks 数组给出每首歌:

{
  "id": "…",
  "status": "succeeded",
  "tracks": [
    {
      "clip_id": "…",
      "title": "海风慢慢吹",
      "duration_sec": 192.0,
      "audio_url": "https://…mp3",
      "image_url": "https://…jpeg",
      "lyrics": "[Verse]…"
    }
  ]
}

生成一般需要 2–4 分钟,建议 10–20 秒一次轮询。任务 id 仅本账号可见,他人/不存在的任务一律 404。

列出任务#

GET /v1/music/generations(不带 id)—— 本账号的音乐任务,按提交时间倒序。免费。 没保存任务 id 时用它找回。

响应是 {"data": [ … ]},每项与上面轮询端点的单任务响应逐字段一致(id / model / status / upstream_status / tracks[] / error_code / error_message / created_at / completed_at),拿到列表项可以直接当轮询结果用,不必写两套解析。

curl "https://jiuye.zsopc.com/v1/music/generations?limit=10&status=processing" \
  -H "Authorization: Bearer $PLATFORM_API_KEY"

计费口径#

• 提交时按固定单价从账户余额预留(一次生成 = 2 首,单价已含);余额不足返回 402
• 任务终态结算:至少 1 首成功即按全价计费;两首全部失败或超 30 分钟未完成(过期)全额退回;提交阶段任何失败也即时退回预留
• 音频与封面会自动转存到本平台对象存储,audio_url / image_url 为 7 天预签名链接;转存失败时降级返回上游原始链接

POST /v1/audio/speech#

语音合成:文本(≤5000 字符)→ MP3,支持克隆音色与语速调节(语速仅对克隆音色生效)。按输入字符计费(voice-tts-pro,125.36/千字符)。

⚠️ 长文案请用异步模式。 合成走上游异步队列(短文本几秒返回,长文案可能跑几分钟),而同步调用受 CDN 约 100 秒的非流式响应上限约束 —— 超时被掐断时音频照样渲染完、费用照样产生,但你什么也拿不到。请求体里加 "async": true 即可改成提交 + 轮询。

请求#

{
  "model": "voice-tts-pro",
  "input": "你好,欢迎使用语音合成。",
  "voice": "<可选,平台预设音色 id 或 /v1/audio/voices 返回的克隆音色 id;缺省为默认音色>",
  "speed": 1.0,
  "async": false
}

响应(同步,async 缺省 / false)#

{
  "model": "voice-tts-pro",
  "audio_url": "https://r2.dflop.top/audio-speech/…/xxx.mp3",
  "characters": 12,
  "cost_usd": "0.0037"
}

audio_url 是本平台对象存储的永久公网链接,可直接作为数字人(dh-avatar)的 audio_url 输入。

响应("async": true)#

立即返回任务 id,不阻塞:

{ "id": "3a8e…", "model": "voice-tts-pro", "status": "pending", "characters": 1200, "created_at": "…" }

不带 id 的 GET /v1/audio/speech 列出本账号的合成任务(默认全部状态,?limit= 默认 30 最大 100,?status=pending,succeeded,failed,all 可筛选)—— 没保存任务 id 时用它找回。

再轮询 GET /v1/audio/speech/{id}(免费):

{
  "id": "3a8e…", "model": "voice-tts-pro", "status": "succeeded",
  "characters": 1200, "duration_sec": "86.40",
  "audio_url": "https://r2.dflop.top/audio-speech/…/xxx.mp3", "created_at": "…"
}

status 三态:pending / succeeded / failed。失败自动全额退款;成功时才计费,音频同样落到永久链接。

列出任务#

GET /v1/audio/speech(不带 id)—— 本账号的合成任务,按创建时间倒序。免费。 "async": true 提交后没保存任务 id 时用它找回。

响应是 {"data": [ … ]},每项与 GET /v1/audio/speech/{id} 的单任务响应逐字段一致(id / model / status / characters / created_at,成功时另有 audio_url / duration_sec,失败时有 error.message)。

curl "https://jiuye.zsopc.com/v1/audio/speech?limit=10" \
  -H "Authorization: Bearer $PLATFORM_API_KEY"

/v1/audio/voices — 声音克隆与音色管理#

克隆同样支持 "async": true:立即返回 {id, status:"pending"},再轮询 GET /v1/audio/voices/{id} 到 ready。缺省是阻塞至就绪(数十秒–数分钟)—— 同上,受 CDN 约 100 秒上限约束,新接入一律建议用异步。失败自动全额退款。

克隆得到的音色 id 传入 /v1/audio/speech 的 voice 字段即可用该音色合成,也可以直接作为数字人 dh-avatar 文字驱动的 voice(见 数字人 API)。克隆真实人声前请确认已获得声音所有者授权。

平台还提供一批公共音色(GET /v1/audio/voices 响应里的 presets),无需克隆即可直接把公共音色的 id 传入 voice 使用。

POST /v1/transcripts/extract#

短视频链接 → 口播文案:粘贴一条短视频分享链接 / 分享口令,提取原视频的口播文案正文 + 元信息(标题 / 封面 / 平台 / 时长)。上游自动识别平台(抖音 / 快手 / 小红书 / B站 / 视频号 等主流平台),无需指定来源。

服务端同步阻塞至提取完成(内部:创建任务 → 轮询上游,通常 5–40 秒、最长约 55 秒返回)—— 客户端请把读取超时设足(建议 ≥ 90 秒)。上游并发上限较低,高并发调用会排队变慢。

请求#

{
  "url": "https://v.douyin.com/xxxxxx/   —— 或直接粘贴分享口令原文"
}

响应#

{
  "model": "video-transcript",
  "content": "提取出的口播文案正文……",
  "title": "原视频标题",
  "cover": "https://…封面图 URL",
  "platform": "douyin",
  "duration_sec": 42,
  "origin_link": "https://…上游回显的原始链接"
}

platform 为上游识别到的平台标识(如 douyin / kuaishou)。content 是核心口播文案;title / cover / duration_sec 为附带元信息,视频无对应字段时可能为空。

curl#

curl -X POST https://jiuye.zsopc.com/v1/transcripts/extract \
  -H "Authorization: Bearer $GPUSHARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://v.douyin.com/xxxxxx/"}'

计费口径#

• 按次固定计费(video-transcript,20.22/次),扣账户余额(全部 Key 共享)。
• 仅成功扣费:链接无法解析 / 视频不支持 / 提取超时 / 提取到的文案被内容安全拦截,均不计费;只有干净成功返回文案才扣一次。
• 每次调用在用量与调用日志中以 unit_type=transcript 记录(响应带 x-gateway-trace,报障时连同时间戳一并提供)。

限制与错误#

• cover 封面 URL 可能有时效(约 24 小时),需长期留存请自行下载转存。
• 输入 ≤ 2000 字符;上游并发上限较低,高并发会排队。
• 错误为归一化形状(与其它端点一致):链接无效 / 视频不支持 → 400,提取超时 → 504,服务额度暂不足 → 503,上游连接失败 → 502,余额不足 → 402。
• 如需把某把 Key 限定为只能调用本能力,在该 Key 的 allowed_models 里加入 video-transcript 即可(不设 allowed_models = 可调用账户全部可用模型)。