self-media-james/doc/passport/即梦.md

# 即梦 AI 图片生成 API

## 密钥

Access Key ID：AKLTOWVjYmE2NGVhZTFhNDQ2OThiYTNhZDdjZTZiYTc3ZTQ
Secret Access Key：WXpVd016azFPVEF3TURjNE5EbGxOV0psTlRNek1qaGpaalEyWkdKa1kyRQ==

## API 基本信息

| 项目 | 值 |
|------|------|
| Endpoint | `https://visual.volcengineapi.com` |
| Region | `cn-north-1` |
| Service | `cv` |
| 签名算法 | HMAC-SHA256 (V4) |
| Content-Type | `application/json` |

## 接口列表

### 1. 文生图 - 提交任务（异步）

```
POST https://visual.volcengineapi.com?Action=CVSync2AsyncSubmitTask&Version=2022-08-31
```

请求体：
```json
{
  "req_key": "jimeng_t2i_v40",
  "prompt": "一只卡通龙虾站在电路板上，科技感，扁平插画风格",
  "width": 1024,
  "height": 1024
}
```

返回：
```json
{
  "code": 10000,
  "data": {
    "task_id": "7392616336519610409"
  },
  "message": "Success",
  "request_id": "20240720103939AF0029465CF6A74E51EC",
  "time_elapsed": "104.852309ms"
}
```

### 2. 查询任务结果

```
POST https://visual.volcengineapi.com?Action=CVSync2AsyncGetResult&Version=2022-08-31
```

请求体：
```json
{
  "req_key": "jimeng_t2i_v40",
  "task_id": "7392616336519610409"
}
```

### 3. 同步调用（小任务）

```
POST https://visual.volcengineapi.com?Action=CVProcess&Version=2022-08-31
```

## Python 调用方法

### 方式一：SDK 调用（推荐）

```bash
pip install volcengine-python-sdk
```

```python
from volcengine.visual.VisualService import VisualService

visual_service = VisualService()
visual_service.set_ak('AKLTOWVjYmE2NGVhZTFhNDQ2OThiYTNhZDdjZTZiYTc3ZTQ')
visual_service.set_sk('WXpVd016azFPVEF3TURjNE5EbGxOV0psTlRNek1qaGpaalEyWkdKa1kyRQ==')

# 提交文生图任务
resp = visual_service.cv_sync2async_submit_task({
    "req_key": "jimeng_t2i_v40",
    "prompt": "一只卡通龙虾站在电路板上，科技感，扁平插画风格",
    "width": 1024,
    "height": 1024
})
print(resp)
task_id = resp["data"]["task_id"]

# 查询结果
import time
time.sleep(10)  # 等待生成

result = visual_service.cv_sync2async_get_result({
    "req_key": "jimeng_t2i_v40",
    "task_id": task_id
})
print(result)
```

### 方式二：HTTP 签名调用

```python
import json
import sys
import datetime
import hashlib
import hmac
import requests

# ===== 配置 =====
ACCESS_KEY = 'AKLTOWVjYmE2NGVhZTFhNDQ2OThiYTNhZDdjZTZiYTc3ZTQ'
SECRET_KEY = 'WXpVd016azFPVEF3TURjNE5EbGxOV0psTlRNek1qaGpaalEyWkdKa1kyRQ=='
HOST = 'visual.volcengineapi.com'
ENDPOINT = 'https://visual.volcengineapi.com'
REGION = 'cn-north-1'
SERVICE = 'cv'

def sign(key, msg):
    return hmac.new(key, msg.encode('utf-8'), hashlib.sha256).digest()

def get_signature_key(key, date_stamp, region_name, service_name):
    k_date = sign(key.encode('utf-8'), date_stamp)
    k_region = sign(k_date, region_name)
    k_service = sign(k_region, service_name)
    k_signing = sign(k_service, 'request')
    return k_signing

def format_query(parameters):
    return '&'.join(f'{k}={parameters[k]}' for k in sorted(parameters))

def jimeng_request(action, body_params):
    """发送即梦API请求"""
    t = datetime.datetime.utcnow()
    current_date = t.strftime('%Y%m%dT%H%M%SZ')
    datestamp = t.strftime('%Y%m%d')

    query_params = format_query({'Action': action, 'Version': '2022-08-31'})
    req_body = json.dumps(body_params)
    payload_hash = hashlib.sha256(req_body.encode('utf-8')).hexdigest()

    signed_headers = 'content-type;host;x-content-sha256;x-date'
    canonical_headers = (
        f'content-type:application/json\n'
        f'host:{HOST}\n'
        f'x-content-sha256:{payload_hash}\n'
        f'x-date:{current_date}\n'
    )
    canonical_request = f'POST\n/\n{query_params}\n{canonical_headers}\n{signed_headers}\n{payload_hash}'

    credential_scope = f'{datestamp}/{REGION}/{SERVICE}/request'
    string_to_sign = (
        f'HMAC-SHA256\n{current_date}\n{credential_scope}\n'
        + hashlib.sha256(canonical_request.encode('utf-8')).hexdigest()
    )

    signing_key = get_signature_key(SECRET_KEY, datestamp, REGION, SERVICE)
    signature = hmac.new(signing_key, string_to_sign.encode('utf-8'), hashlib.sha256).hexdigest()

    authorization = (
        f'HMAC-SHA256 Credential={ACCESS_KEY}/{credential_scope}, '
        f'SignedHeaders={signed_headers}, Signature={signature}'
    )

    headers = {
        'X-Date': current_date,
        'Authorization': authorization,
        'X-Content-Sha256': payload_hash,
        'Content-Type': 'application/json'
    }

    r = requests.post(f'{ENDPOINT}?{query_params}', headers=headers, data=req_body)
    return r.json()


def generate_image(prompt, width=1024, height=1024):
    """文生图：提交任务并轮询获取结果"""
    # 1. 提交任务
    submit_resp = jimeng_request('CVSync2AsyncSubmitTask', {
        'req_key': 'jimeng_t2i_v40',
        'prompt': prompt,
        'width': width,
        'height': height
    })

    if submit_resp.get('code') != 10000:
        print(f"提交失败: {submit_resp}")
        return None

    task_id = submit_resp['data']['task_id']
    print(f"任务已提交, task_id: {task_id}")

    # 2. 轮询查询结果
    import time
    for i in range(30):
        time.sleep(5)
        result = jimeng_request('CVSync2AsyncGetResult', {
            'req_key': 'jimeng_t2i_v40',
            'task_id': task_id
        })
        if result.get('code') == 10000 and result.get('data', {}).get('status') == 'done':
            print("生成完成!")
            return result
        print(f"等待中... ({i+1}/30)")

    print("超时")
    return None


if __name__ == '__main__':
    result = generate_image("一只卡通龙虾站在电路板上，科技感，扁平插画风格")
    print(json.dumps(result, indent=2, ensure_ascii=False))
```

## 参考文档

- [即梦AI图片生成4.0 产品介绍](https://www.volcengine.com/docs/85621/1820192)
- [即梦AI图片生成4.0 接口文档](https://www.volcengine.com/docs/85621/1817045)
- [Python SDK (GitHub)](https://github.com/volcengine/volc-sdk-python)
- [SDK 使用说明](https://www.volcengine.com/docs/6444/1340578)
- [HTTP 请求示例](https://www.volcengine.com/docs/6444/1390583)