enhance-media

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

What This Skill Does

本技能的功能

Uses Sivi's

generate

API to:

Generate new images from a text prompt (e.g., "A modern minimalist logo for a coffee shop")
Enhance existing images (e.g., "Make this product photo more vibrant and professional")

The API is asynchronous — it returns a

requestId

that you poll via

get-request-status

until the image is ready.

使用Sivi的

generate

API实现：

生成：根据文本提示词生成新图片（例如：“一个面向咖啡店的现代极简风格logo”）
增强：优化现有图片（例如：“让这张产品照片更鲜艳、更具专业感”）

该API为异步接口——返回一个

requestId

，你需要通过

get-request-status

接口轮询，直到图片生成完成。

⚠️ Cross-Platform Compatibility — MANDATORY

⚠️ 跨平台兼容性——强制要求

NEVER use
head -n -1
or
```
jq
```
. Use
```
python3
```
for JSON parsing.
ALWAYS use
curl -o <file> -w '%{http_code}'
to separate HTTP status from response body.
Temp files: Use
```
/tmp/
```
.

**绝对不要使用
```
head -n -1
```
**或
```
jq
```
。请使用
```
python3
```
进行JSON解析。
**务必使用
```
curl -o <file> -w '%{http_code}'
```
**来分离HTTP状态码与响应体。
临时文件：使用
```
/tmp/
```
目录。

Steps

操作步骤

1. Parse arguments

1. 解析参数

```
prompt
```
— description of the image to generate or enhancement instructions (required).
```
imageUrl
```
— existing image URL to enhance (optional; if absent, generates a new image).
```
mediaId
```
— Sivi media ID for an existing image (optional alternative to imageUrl).
```
width
```
— output image width (default: 1024)
```
height
```
— output image height (default: 1024)
```
model
```
— AI model to use (default:
```
z-image-turbo
```
for generation,
```
nano-banana:1k
```
for enhancement)
```
negativePrompt
```
— what to avoid in the image (optional)

prompt

is missing, ask: "What image would you like to generate or how would you like to enhance your image?"

```
prompt
```
——生成图片的描述或图片增强的指令（必填）。
```
imageUrl
```
——待增强的现有图片URL（可选；若未提供，则生成新图片）。
```
mediaId
```
——现有图片对应的Sivi媒体ID（作为imageUrl的可选替代参数）。
```
width
```
——输出图片宽度（默认值：1024）
```
height
```
——输出图片高度（默认值：1024）
```
model
```
——使用的AI模型（默认值：生成图片用
```
z-image-turbo
```
，增强图片用
```
nano-banana:1k
```
）
```
negativePrompt
```
——图片中需要避免的元素（可选）

如果缺少

prompt

，请询问：“你想要生成什么样的图片，或者希望如何增强你的图片？”

2. Resolve brand

2. 解析品牌信息

Follow the Active Brand Resolution flow in

_shared/conventions.md

. A brand must be resolved —

bId

is mandatory for the generate API.

遵循

_shared/conventions.md

中的活跃品牌解析流程。必须解析出品牌信息——

bId

是调用generate API的必填参数。

3. Step A — Submit generate request (Bash tool call #1)

3. 步骤A——提交生成请求（Bash工具调用#1）

bash

#!/bin/bash
set -e
source <SKILL_REPO>/.env

BRAND_ID="<BRAND_ID>"

PAYLOAD=$(python3 -c "
import json
data = {
    'prompt': '''PROMPT_PLACEHOLDER''',
    'dimensions': {'width': 1024, 'height': 1024},
    'model': 'z-image-turbo',
    'negativePrompt': 'blurry, low quality',
    'bId': '$BRAND_ID'
}

bash

#!/bin/bash
set -e
source <SKILL_REPO>/.env

BRAND_ID="<BRAND_ID>"

PAYLOAD=$(python3 -c "
import json
data = {
    'prompt': '''PROMPT_PLACEHOLDER''',
    'dimensions': {'width': 1024, 'height': 1024},
    'model': 'z-image-turbo',
    'negativePrompt': 'blurry, low quality',
    'bId': '$BRAND_ID'
}

For enhancement, add:

若为增强图片，添加以下内容：

data['model'] = 'nano-banana:1k'

data['assets'] = {'photo': [{'url': 'IMAGE_URL_PLACEHOLDER'}]}

data['siviAssets'] = [{'mId': 'MEDIA_ID_PLACEHOLDER'}]

print(json.dumps(data)) ")

HTTP_CODE=$(curl -s -o /tmp/sivi_genmedia_response.json -w '%{http_code}'
-X POST "https://connect.sivi.ai/api/prod/v2/general/media/generate"
-H "Content-Type: application/json"
-H "sivi-api-key: $SIVI_API_KEY"
-d "$PAYLOAD")

BODY=$(cat /tmp/sivi_genmedia_response.json)

if [ "$HTTP_CODE" != "200" ]; then echo "ERROR: HTTP $HTTP_CODE" echo "$BODY" exit 1 fi

REQUEST_ID=$(python3 -c "import json,sys; d=json.load(sys.stdin); print(d['body']['requestId'])" <<< "$BODY")

echo "REQUEST_ID=$REQUEST_ID"

undefined

print(json.dumps(data)) ")

BODY=$(cat /tmp/sivi_genmedia_response.json)

if [ "$HTTP_CODE" != "200" ]; then echo "ERROR: HTTP $HTTP_CODE" echo "$BODY" exit 1 fi

REQUEST_ID=$(python3 -c "import json,sys; d=json.load(sys.stdin); print(d['body']['requestId'])" <<< "$BODY")

echo "REQUEST_ID=$REQUEST_ID"

undefined

4. Step B — Poll for result (Bash tool call #2)

4. 步骤B——轮询结果（Bash工具调用#2）

bash

#!/bin/bash
set -e
source <SKILL_REPO>/.env

REQUEST_ID="<REQUEST_ID_FROM_STEP_A>"
MAX_ATTEMPTS=30
ATTEMPT=0

while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
  ATTEMPT=$((ATTEMPT + 1))
  echo "Poll attempt $ATTEMPT/$MAX_ATTEMPTS..."

  QUERY_PARAMS=$(python3 -c "
import json, urllib.parse
params = json.dumps({'requestId': '$REQUEST_ID'})
print(urllib.parse.quote(params, safe=''))
")

  HTTP_CODE=$(curl -s -o /tmp/sivi_media_status.json -w '%{http_code}' \
    -X GET "https://connect.sivi.ai/api/prod/v2/general/get-request-status?queryParams=$QUERY_PARAMS" \
    -H "sivi-api-key: $SIVI_API_KEY")

  BODY=$(cat /tmp/sivi_media_status.json)

  if [ "$HTTP_CODE" != "200" ]; then
    echo "ERROR: HTTP $HTTP_CODE"
    echo "$BODY"
    exit 1
  fi

  STATUS=$(python3 -c "import json,sys; d=json.load(sys.stdin); print(d['body']['status'])" <<< "$BODY")

  if [ "$STATUS" = "completed" ]; then
    echo "MEDIA GENERATION COMPLETE"
    python3 -c "
import json, sys
d = json.load(sys.stdin)
result = d['body'].get('result', {})
media = result.get('media', {})
if media:
    print(f\"MEDIA_URL={media.get('url', '')}\")
    print(f\"MEDIA_ID={media.get('mId', '')}\")
else:
    # Try alternate response format
    print(f\"RESULT={json.dumps(result)}\")
" <<< "$BODY"
    exit 0
  elif [ "$STATUS" = "failed" ] || [ "$STATUS" = "suspended" ]; then
    echo "MEDIA GENERATION FAILED ($STATUS)"
    echo "$BODY"
    exit 1
  fi

  sleep 10
done

echo "TIMEOUT"
exit 1

bash

#!/bin/bash
set -e
source <SKILL_REPO>/.env

REQUEST_ID="<REQUEST_ID_FROM_STEP_A>"
MAX_ATTEMPTS=30
ATTEMPT=0

while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
  ATTEMPT=$((ATTEMPT + 1))
  echo "Poll attempt $ATTEMPT/$MAX_ATTEMPTS..."

  QUERY_PARAMS=$(python3 -c "
import json, urllib.parse
params = json.dumps({'requestId': '$REQUEST_ID'})
print(urllib.parse.quote(params, safe=''))
")

  HTTP_CODE=$(curl -s -o /tmp/sivi_media_status.json -w '%{http_code}' \
    -X GET "https://connect.sivi.ai/api/prod/v2/general/get-request-status?queryParams=$QUERY_PARAMS" \
    -H "sivi-api-key: $SIVI_API_KEY")

  BODY=$(cat /tmp/sivi_media_status.json)

  if [ "$HTTP_CODE" != "200" ]; then
    echo "ERROR: HTTP $HTTP_CODE"
    echo "$BODY"
    exit 1
  fi

  STATUS=$(python3 -c "import json,sys; d=json.load(sys.stdin); print(d['body']['status'])" <<< "$BODY")

  if [ "$STATUS" = "completed" ]; then
    echo "MEDIA GENERATION COMPLETE"
    python3 -c "
import json, sys
d = json.load(sys.stdin)
result = d['body'].get('result', {})
media = result.get('media', {})
if media:
    print(f\"MEDIA_URL={media.get('url', '')}\")
    print(f\"MEDIA_ID={media.get('mId', '')}\")
else:
    # 尝试备用响应格式
    print(f\"RESULT={json.dumps(result)}\")
" <<< "$BODY"
    exit 0
  elif [ "$STATUS" = "failed" ] || [ "$STATUS" = "suspended" ]; then
    echo "MEDIA GENERATION FAILED ($STATUS)"
    echo "$BODY"
    exit 1
  fi

  sleep 10
done

echo "TIMEOUT"
exit 1

5. Download result and save to brand assets

5. 下载结果并保存到品牌资产

bash

#!/bin/bash
set -e

MEDIA_URL="<MEDIA_URL_FROM_STEP_B>"
BRAND_SLUG="<brand-slug>"
ASSETS_DIR="brands/$BRAND_SLUG/assets"
mkdir -p "$ASSETS_DIR"

if [ -n "$MEDIA_URL" ] && [[ "$MEDIA_URL" == https://* ]]; then
  FILE_NAME="generated_$(date +%s).jpg"
  curl -sL -o "$ASSETS_DIR/$FILE_NAME" "$MEDIA_URL"
  echo "IMAGE_SAVED=$ASSETS_DIR/$FILE_NAME"
else
  echo "IMAGE_SAVED=none"
fi

bash

#!/bin/bash
set -e

MEDIA_URL="<MEDIA_URL_FROM_STEP_B>"
BRAND_SLUG="<brand-slug>"
ASSETS_DIR="brands/$BRAND_SLUG/assets"
mkdir -p "$ASSETS_DIR"

if [ -n "$MEDIA_URL" ] && [[ "$MEDIA_URL" == https://* ]]; then
  FILE_NAME="generated_$(date +%s).jpg"
  curl -sL -o "$ASSETS_DIR/$FILE_NAME" "$MEDIA_URL"
  echo "IMAGE_SAVED=$ASSETS_DIR/$FILE_NAME"
else
  echo "IMAGE_SAVED=none"
fi

6. Display result

6. 展示结果

Read the downloaded image file.

Render

<img src="</absolute/path/to/file.jpg>" alt="Generated Image" style="box-shadow: 0px 0px 18px rgba(0,0,0,0.18);">

Print the image URL and media ID.
Offer to use this image in generate-design or campaign.

读取下载的图片文件。

渲染

<img src="</absolute/path/to/file.jpg>" alt="Generated Image" style="box-shadow: 0px 0px 18px rgba(0,0,0,0.18);">

。

打印图片URL和媒体ID。
询问用户是否要将此图片用于generate-design或营销活动。

7. Handle errors

7. 错误处理

On 401: "Your SIVI_API_KEY is missing or invalid."
On 402: "Insufficient Sivi credits."
On 422: "Invalid input: <error>. Check your prompt and parameters."
On 500: "Sivi server errored. Please retry."

401错误：“你的SIVI_API_KEY缺失或无效。”
402错误：“Sivi积分不足。”
422错误：“输入无效：<error>。请检查你的提示词和参数。”
500错误：“Sivi服务器出错，请重试。”

Notes

注意事项

For generation (new images): use
```
model: "z-image-turbo"
```
and no
```
assets
```
/
```
siviAssets
```
.

For enhancement (existing images): use

model: "nano-banana:1k"

and include

assets.photo[].url

siviAssets[].mId

Maximum of 4 image assets total (combined
```
siviAssets
```
+
```
assets
```
).
The
```
bId
```
parameter is mandatory — a brand must be resolved before calling the generate API.
Supported models may change — check the Sivi API docs for the latest model names.
The generated image can be used as an asset in generate-design by passing the media URL.

生成图片（新图片）：使用
```
model: "z-image-turbo"
```
，不要添加
```
assets
```
/
```
siviAssets
```
参数。
增强图片（现有图片）：使用
```
model: "nano-banana:1k"
```
，并添加
```
assets.photo[].url
```
或
```
siviAssets[].mId
```
参数。
最多支持4个图片资产（
```
siviAssets
```
+
```
assets
```
合计）。
```
bId
```
参数为必填项——调用generate API前必须解析出品牌信息。
支持的模型可能会变更——请查看Sivi API文档获取最新的模型名称。
生成的图片可作为generate-design的资产，只需传入媒体URL即可。