图像 / 视频 / 音乐 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 与完整错误体一起提供。

POST /v1/images/generations#

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

可用模型#

size 原样透传给上游,gateway 不改写 —— Seedream 4.5/5.0 传小于 1920×1920 会直接拿到上游的 400 错误。

请求#

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

响应#

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

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

curl#

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

限制#

• 返回的图片 URL 是上游预签名链接,约 24 小时过期 —— 拿到后请尽快下载转存到自己的存储
• 同步接口,gateway 侧对上游的超时为 120 秒;上游生成耗时一般 5–20 秒,客户端超时建议设 ≥ 120s
• 错误为 OpenAI 形状 {"error": {"code", "message", "param", "type"}},上游 4xx/5xx 原状态码 + 原响应体透传(不计费)

Nano Banana 家族(nano-banana $0.039/张、nano-banana-pro $0.134/张、nano-banana-2 $0.04/张)也走本端点按张计费;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(跟随源图原生比例,避免拉伸变形)。

响应:

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

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

轮询#

curl https://api.dflop.top/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"),不做区分。

计费口径#

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

限制#

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

POST /v1/music/generations#

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

可用模型#

请求#

curl https://api.dflop.top/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://api.dflop.top/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。

计费口径#

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