API 接口文档

基准路径（Base URL）

所有 API 请求均以以下地址为基准路径：

示例：调用图片生成接口的完整 URL 为 https://api.huameng.space/v1/images/generations

鉴权说明

所有 API 请求（除 /health 外）均需携带 API Key 进行身份认证，支持以下两种方式：

通用错误码

错误响应格式：

{
  "error": "错误信息描述"
}
// 生成中限制的特殊格式：
{
  "error": "当前有 N 个任务正在生成中，请等待完成后再提交",
  "code": "GENERATING_LIMIT"
}

GET 查询余额 /v1/balance

查询当前 API Key 的账户余额及统计信息。

请求示例

GET /v1/balance
Authorization: Bearer your-api-key

响应字段

响应示例

{
  "balance": 1500,
  "frozen": 200,
  "total_recharged": 5000,
  "total_consumed": 3300,
  "created_at": "2026-03-15T08:00:00.000Z"
}

GET 消费流水 /v1/transactions

查询当前 API Key 的消费/充值流水记录，支持分页和类型过滤。

查询参数

响应示例

{
  "transactions": [
    {
      "id": 123,
      "type": "confirm",
      "amount": -200,
      "balance_after": 1300,
      "model": "jimeng-video-seedance-2.0-fast",
      "task_type": "video",
      "task_id": "a1b2c3d4-...",
      "channel": "official",
      "note": "视频生成 5s 720p",
      "created_at": "2026-04-02T12:00:00.000Z"
    }
  ],
  "total": 56,
  "page": 1,
  "page_size": 20
}

GET 渠道列表 /v1/channels

获取所有已启用的计费渠道及其定价配置。仅用于展示，不可修改。

响应示例

{
  "channels": [
    {
      "name": "default",
      "display_name": "逆向渠道",
      "description": "基于逆向工程的默认渠道",
      "is_default": true,
      "pricing": { /* 各模型定价配置 */ }
    }
  ]
}

POST 充值 /v1/recharge

使用卡密为当前 API Key 充值。

请求参数

请求示例

POST /v1/recharge
Content-Type: application/json

{
  "card_code": "XXXX-XXXX-XXXX"
}

响应示例

{
  "balance": 2500,
  "recharged_amount": 1000
}

GET 模型列表 /v1/models

获取当前可用的所有模型列表。

响应示例

{
  "data": [
    { "id": "HM-Image-5.0Lite", "type": "image" },
    { "id": "HM-Video-SD2.0", "type": "video" },
    { "id": "HM-Avatar-Pro", "type": "lip_sync" }
  ]
}

支持的模型

图像模型：（均为逆向渠道）

视频模型：

视频模型能力矩阵

数字人模型：（均为逆向渠道）

POST 图片生成 /v1/images/generations

提交图片生成任务。支持文本生图和参考图生图。请求格式为 multipart/form-data。

请求参数

请求示例（cURL）

纯文本生图

curl -X POST "https://api.huameng.space/v1/images/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=一只可爱的橘猫在花园里晒太阳" \
  -F "model=HM-Image-5.0Lite" \
  -F "ratio=16:9" \
  -F "resolution=2k" \
  -F "channel=official"

单图参考生图（文件上传）

curl -X POST "https://api.huameng.space/v1/images/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=将这张照片转换为动漫风格" \
  -F "model=HM-Image-5.0Lite" \
  -F "sample_strength=0.7" \
  -F "images=@/path/to/reference.jpg"

单图参考生图（URL 方式）

curl -X POST "https://api.huameng.space/v1/images/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=将这张照片转换为水彩画风格" \
  -F "model=HM-Image-5.0Lite" \
  -F "sample_strength=0.6" \
  -F "image_url=https://example.com/photo.jpg"

多图参考生图（文件上传，最多 6~10 张）

curl -X POST "https://api.huameng.space/v1/images/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=融合这些图片的风格，生成一幅新画作" \
  -F "model=HM-Image-5.0Lite" \
  -F "sample_strength=0.5" \
  -F "images=@/path/to/ref1.jpg" \
  -F "images=@/path/to/ref2.jpg" \
  -F "images=@/path/to/ref3.jpg"

多图参考生图（URL 方式）

curl -X POST "https://api.huameng.space/v1/images/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=融合这些参考图的元素" \
  -F "model=HM-Image-4.5" \
  -F "sample_strength=0.5" \
  -F 'image_urls=["https://example.com/ref1.jpg","https://example.com/ref2.jpg","https://example.com/ref3.jpg"]'

响应示例

// HTTP 202 Accepted
{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "model": "HM-Image-5.0Lite",
  "created_at": "2026-04-01T12:00:00.000Z"
}

POST 视频生成 /v1/videos/generations

提交视频生成任务。支持多种功能模式：首尾帧、多帧引导、全能引用。请求格式为 multipart/form-data。

基础参数

首尾帧模式参数 first_last_frames

多帧引导模式参数 multi_frame

全能引用模式参数 omni_reference

请求示例（按功能模式）

① 纯文生视频
支持所有视频模型

# SD2.0 — 支持 4~15 秒连续时长
curl -X POST "https://api.huameng.space/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=一只猫咪在草地上奔跑" \
  -F "model=HM-Video-SD2.0" \
  -F "ratio=16:9" \
  -F "duration=8"

# SD2.0Fast — 快速生成 14 秒长视频
curl -X POST "https://api.huameng.space/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=城市夜景延时摄影，霓虹灯闪烁" \
  -F "model=HM-Video-SD2.0Fast" \
  -F "ratio=16:9" \
  -F "duration=14"

# SD1.0 — 10 秒 + 1080p
curl -X POST "https://api.huameng.space/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=海浪拍打礁石，日落余晖" \
  -F "model=HM-Video-SD1.0" \
  -F "ratio=16:9" \
  -F "duration=10" \
  -F "video_resolution=1080p"

② 仅首帧引导（文件上传）
支持：SD2.0 / SD2.0Fast / SD1.5Pro / SD1.0Mini / SD1.0Fast（SD1.0 部分地区）

curl -X POST "https://api.huameng.space/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=花朵慢慢盛开" \
  -F "model=HM-Video-SD1.5Pro" \
  -F "first_frame=@/path/to/flower.jpg" \
  -F "duration=5"

② 仅首帧引导（URL 方式）

curl -X POST "https://api.huameng.space/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=花朵慢慢盛开" \
  -F "model=HM-Video-SD1.5Pro" \
  -F "first_frame_url=https://example.com/flower.jpg" \
  -F "duration=5"

③ 首尾帧模式（文件上传）
支持：SD2.0 / SD2.0Fast / SD1.5Pro（SD1.0/Mini/Fast 部分地区）

curl -X POST "https://api.huameng.space/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=人物从站立缓缓坐下" \
  -F "model=HM-Video-SD1.5Pro" \
  -F "first_frame=@/path/to/standing.jpg" \
  -F "end_frame=@/path/to/sitting.jpg" \
  -F "duration=12" \
  -F "video_resolution=1080p"

③ 首尾帧模式（URL 方式）

curl -X POST "https://api.huameng.space/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=人物从站立缓缓坐下" \
  -F "model=HM-Video-SD2.0" \
  -F "first_frame_url=https://example.com/standing.jpg" \
  -F "end_frame_url=https://example.com/sitting.jpg" \
  -F "duration=5"

④ 多帧引导（文件上传，至少 2 帧，最多 5~10 帧）
支持：SD1.0Mini（SD1.0Fast 部分地区）。SD2.0/SD1.5Pro/SD1.0 不支持多帧

curl -X POST "https://api.huameng.space/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=人物从站立到坐下再到躺下的动作过渡" \
  -F "model=HM-Video-SD1.0Mini" \
  -F "function_mode=multi_frame" \
  -F "frame_1=@/path/to/standing.jpg" \
  -F "frame_2=@/path/to/sitting.jpg" \
  -F "frame_3=@/path/to/lying.jpg" \
  -F "duration=10"

④ 多帧引导（URL 方式）

curl -X POST "https://api.huameng.space/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=人物从站立到坐下再到躺下的动作过渡" \
  -F "model=HM-Video-SD1.0Mini" \
  -F "function_mode=multi_frame" \
  -F 'multi_frames=["https://example.com/standing.jpg","https://example.com/sitting.jpg","https://example.com/lying.jpg"]' \
  -F "duration=10"

⑤ 全能引用 omni_reference — 单素材 + @引用（文件上传）
仅支持：SD2.0 / SD2.0Fast

# prompt 中用 @名称 引用素材，materials 中的 name 必须与之对应
# 注意：prompt 以 @ 开头时须用 --form-string 代替 -F，避免 curl 将 @ 解读为文件路径
curl -X POST "https://api.huameng.space/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  --form-string "prompt=@角色A 在咖啡馆微笑" \
  -F "model=HM-Video-SD2.0" \
  -F "function_mode=omni_reference" \
  -F "ratio=16:9" \
  -F "duration=5" \
  -F 'materials=[{"type":"image","name":"角色A"}]' \
  -F "image_file_1=@/path/to/charA.jpg"

⑤ 全能引用 omni_reference — 多素材 + @引用（URL 方式，含图片/视频/音频）

# 可同时引用多个图片素材、视频素材和音频素材
curl -X POST "https://api.huameng.space/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  --form-string "prompt=@角色A 在咖啡馆和 @角色B 聊天，背景播放音乐" \
  -F "model=HM-Video-SD2.0" \
  -F "function_mode=omni_reference" \
  -F "ratio=16:9" \
  -F "duration=10" \
  -F 'materials=[{"type":"image","url":"https://example.com/charA.jpg","name":"角色A"},{"type":"image","url":"https://example.com/charB.jpg","name":"角色B"},{"type":"video","url":"https://example.com/cafe-bg.mp4","name":"背景"},{"type":"audio","url":"https://example.com/bgm.mp3","name":"音乐"}]'

响应示例

// HTTP 202 Accepted
{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "model": "HM-Video-SD2.0",
  "created_at": "2026-04-01T12:00:00.000Z"
}

POST 数字人（自动模式） /v1/videos/lip-sync

一步完成数字人口播视频生成：上传人像和音频，系统自动进行人脸检测并提交生成任务。

请求参数（multipart/form-data）

请求示例

curl -X POST "https://api.huameng.space/v1/videos/lip-sync" \
  -H "Authorization: Bearer your-api-key" \
  -F "image=@/path/to/portrait.jpg" \
  -F "audio=@/path/to/speech.mp3" \
  -F "model=HM-Avatar-Pro"

响应示例

// HTTP 202 Accepted
{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "model": "HM-Avatar-Pro",
  "created_at": "2026-04-01T12:00:00.000Z"
}

数字人（手动模式）

手动模式将流程拆分为多步操作，可以预览人脸检测结果并精确选择目标人脸。

步骤 1：上传图片

POST /v1/videos/lip-sync/upload-image

// 响应
{
  "image_uri": "tos://bucket/path/image.jpg",
  "width": 1024,
  "height": 768
}

步骤 2：上传音频

POST /v1/videos/lip-sync/upload-audio

// 响应
{
  "audio_vid": "v0d2a1g10000...",
  "duration_ms": 15000
}

步骤 3：人脸检测

POST /v1/videos/lip-sync/detect-faces

// 响应
{
  "session_id": "sess_abc123",
  "faces": [ ... ],
  "face_count": 2,
  "image_uri": "tos://...",
  "expires_in": 300
}

步骤 4：提交生成

POST /v1/videos/lip-sync/submit

// 响应 HTTP 202
{
  "task_id": "a1b2c3d4-...",
  "status": "pending",
  "model": "HM-Avatar-Turbo",
  "created_at": "2026-04-01T12:00:00.000Z"
}

取消会话

POST /v1/videos/lip-sync/cancel

GET 查询任务状态 /v1/tasks/{taskId}

通过 task_id 轮询任务状态。建议每 3~5 秒查询一次。

请求示例

GET /v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Bearer your-api-key

响应字段

成功响应示例

{
  "task_id": "a1b2c3d4-...",
  "status": "success",
  "model": "HM-Image-5.0Lite",
  "task_type": "image",
  "progress_pct": 100,
  "progress_text": "生成完成",
  "result_urls": [
    "https://cdn.example.com/result/image_001.png"
  ],
  "created_at": "2026-04-01T12:00:00.000Z"
}

失败响应示例

{
  "task_id": "a1b2c3d4-...",
  "status": "failed",
  "model": "HM-Image-5.0Lite",
  "task_type": "image",
  "progress_pct": 0,
  "progress_text": "生成失败",
  "fail_reason": "内容审核未通过，请修改后重试",
  "created_at": "2026-04-01T12:00:00.000Z"
}

常见失败原因

完整调用流程

完整示例（Python）

import requests, time

API_BASE = "https://api.huameng.space"
API_KEY = "your-api-key"
headers = {"Authorization": f"Bearer {API_KEY}"}

# 1. 提交图片生成任务
resp = requests.post(f"{API_BASE}/v1/images/generations",
    headers=headers,
    data={
        "prompt": "一只可爱的橘猫在花园里晒太阳",
        "model": "HM-Image-5.0Lite",
        "ratio": "16:9",
        "resolution": "2k",
        "channel": "official"
    })
task_id = resp.json()["task_id"]
print(f"任务已提交: {task_id}")

# 2. 轮询任务状态
while True:
    time.sleep(3)
    result = requests.get(
        f"{API_BASE}/v1/tasks/{task_id}",
        headers=headers
    ).json()
    print(f"状态: {result['status']} | {result.get('progress_text', '')}")

    if result["status"] == "success":
        print("生成成功！", result["result_urls"])
        break
    elif result["status"] == "failed":
        print("生成失败:", result.get("fail_reason"))
        break

渠道与计费说明

• 请求时通过 channel 参数指定渠道（如 official 官方渠道、default 逆向渠道），不指定时使用系统默认渠道（管理员设置）
• 不同渠道对同一模型可能有不同定价策略
• 计费模式包括：一口价（flat）、按分辨率（resolution）、按时长（duration） 等
• 余额单位为「积分」，1 元 = 1000 积分，下方价格均以元为单位展示

各渠道模型定价