Skip to main content
本节说明如何通过 Rivus AI 平台调用即梦 4.0（jimeng_t2i_v40）的 火山 Visual 原生接口。

​
1. 接口总览

  • 提交任务（文生图 / 图生图统一入口）
    POST /volcark/visual?Action=CVSync2AsyncSubmitTask&Version=2022-08-31
  • 查询任务结果
    POST /volcark/visual?Action=CVSync2AsyncGetResult&Version=2022-08-31
所有请求均通过 One Hub 进行鉴权和路由，不需要直接对火山域名做签名。
你只需要在 Header 中携带自己的 Rivus AI API Key： 
Authorization: Bearer YOUR_RIVUS_API_KEY
Content-Type: application/json
Base URL 一般为你的 Rivus AI 网关地址，例如： 
https://models.rivus.cn
下面示例统一假设： 
BASE_URL = https://models.rivus.cn

​
2. 提交任务（文生图）

​
2.1 cURL 示例

curl -X POST \
  "$BASE_URL/volcark/visual?Action=CVSync2AsyncSubmitTask&Version=2022-08-31" \
  -H "Authorization: Bearer YOUR_RIVUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "req_key": "jimeng_t2i_v40",
    "prompt": "一只可爱的熊猫在图书馆看书，赛博朋克风格",
    "force_single": true,
    "size": 4194304
  }'
请求体关键字段：
  • req_key：必须为 jimeng_t2i_v40；
  • prompt：中文/英文提示词，建议控制在 800 字符以内；
  • force_single：是否强制仅生成 1 张图；为 false 时，模型可能根据理解一次输出多张；
  • size：目标图像面积，单位为像素点个数，例如：
    • 2048*2048 = 4194304（默认 2K 正方形）；
    • 4096*4096 等更高分辨率，延迟会明显增加。
成功返回示例： 
{
  "code": 10000,
  "data": {
    "task_id": "15977608121972527084"
  },
  "message": "Success",
  "request_id": "20251125005330F6F4B7E94EB473180018",
  "status": 10000,
  "time_elapsed": "34.730867ms"
}
你需要记录 data.task_id，用于后续查询结果。

​
3. 查询任务结果

即梦 4.0 为异步接口，需要使用 task_id 轮询查询结果：

​
3.1 cURL 示例

curl -X POST \
  "$BASE_URL/volcark/visual?Action=CVSync2AsyncGetResult&Version=2022-08-31" \
  -H "Authorization: Bearer YOUR_ONE_HUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "req_key": "jimeng_t2i_v40",
    "task_id": "15977608121972527084",
    "req_json": "{\"return_url\":true}"
  }'
字段说明：
  • req_key：同样必须为 jimeng_t2i_v40；
  • task_id：提交任务接口返回的任务 ID（字符串类型）；
  • req_json：JSON 字符串，用于配置返回方式：
    • return_url: true 表示返回图片 URL 列表（有效期 24 小时）；
    • 也可以在其中配置水印等信息。
典型返回示例： 
{
  "code": 10000,
  "data": {
    "binary_data_base64": null,
    "image_urls": [
      "https://xxx/xxx.jpg"
    ],
    "status": "done"
  },
  "message": "Success",
  "request_id": "20251125005330F18F0B2B787132542098",
  "status": 10000,
  "time_elapsed": "27.519922ms"
}
data.status 取值含义：
  • in_queue：已提交，等待执行；
  • generating：处理中；
  • done：处理完成（成功或失败，需结合 code/message 判断）；
  • not_found / expired：任务不存在或已过期（任务最长保留约 12 小时）。

​
4. Python 调用示例

即梦 4.0 Visual 接口不走 OpenAI SDK，而是通过 HTTP 请求调用 Rivus AI 提供的 /volcark/visual 原生接口。 
import os
import time
import requests

BASE_URL = os.environ.get("RIVUS_BASE_URL", "https://models.rivus.cn")
API_KEY = os.environ["RIVUS_API_KEY"]

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

def submit_task():
    url = f"{BASE_URL}/volcark/visual?Action=CVSync2AsyncSubmitTask&Version=2022-08-31"
    payload = {
        "req_key": "jimeng_t2i_v40",
        "prompt": "一只可爱的熊猫在图书馆看书，赛博朋克风格",
        "force_single": True,
        "size": 4194304
    }
    resp = requests.post(url, json=payload, headers=headers, timeout=60)
    resp.raise_for_status()
    data = resp.json()
    if data.get("code") != 10000:
        raise RuntimeError(f"submit failed: {data}")
    return data["data"]["task_id"]

def get_result(task_id: str):
    url = f"{BASE_URL}/volcark/visual?Action=CVSync2AsyncGetResult&Version=2022-08-31"
    payload = {
        "req_key": "jimeng_t2i_v40",
        "task_id": task_id,
        "req_json": "{\"return_url\":true}"
    }
    resp = requests.post(url, json=payload, headers=headers, timeout=60)
    resp.raise_for_status()
    return resp.json()

if __name__ == "__main__":
    task_id = submit_task()
    print("task_id:", task_id)

    for _ in range(30):
        result = get_result(task_id)
        status = result.get("data", {}).get("status")
        print("status:", status)
        if status == "done":
            print("image_urls:", result["data"].get("image_urls"))
            break
        time.sleep(2)

​
5. 常见问题与建议

​
5.1 task_id 类型必须是字符串

火山 Visual 接口要求 task_id 为字符串类型。如果你在代码中不小心将其转换为数字（例如 JSON 解析后当作 int 使用），会得到类似错误：
Invalid Input Parameters: task_id type is not string
建议：
  • 始终把 task_id 作为字符串处理和传递；
  • 若使用自定义脚本拼装 JSON，确保 task_id 被双引号包裹。

​
5.2 计费与图片张数

  • jimeng_t2i_v40 按 生成的图片张数 计费；
  • 即使某次调用只指定 force_single=true，内部生成逻辑仍可能根据 prompt 输出多图；
    One Hub 会根据最终 image_urls / binary_data_base64 的张数进行扣费。
具体单价以 /panel/pricing 中 jimeng_t2i_v40 的配置为准（当前约 ¥0.22/张）。