图片与视频生成

本文说明 GoesAI 图片生成与视频生成接口的技术接入方式。接口使用同一套鉴权方式，请在请求头中携带 Authorization: Bearer sk-your-goesai-api-key。

示例中的 API_BASE 请替换为控制台提供的服务地址，例如 https://api.goesai.com 或您的私有部署地址。图片、视频参考素材 URL 必须公网可访问，建议先用 curl -I -L 确认返回 200，且 Content-Type 为对应媒体类型。

1. 图片生成

图片生成使用 OpenAI 兼容接口。文生图不传 image 字段；单图生图传 1 张参考图；多图参考融合传 2 张或更多参考图。

Request URL:POST /v1/images/generations

1.1 文生图

API_BASE='https://api.goesai.com'
API_KEY='sk-your-goesai-api-key'

curl --location "${API_BASE}/v1/images/generations" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${API_KEY}" \
--data '{
    "model": "Seedream-5.0-overseas-1",
    "prompt": "一杯苹果水果茶产品图，干净白底，商业摄影风格",
    "size": "2K",
    "n": 1,
    "watermark": false
}'

1.2 参考图生成

API_BASE='https://api.goesai.com'
API_KEY='sk-your-goesai-api-key'

curl --location "${API_BASE}/v1/images/generations" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${API_KEY}" \
--data '{
    "model": "Seedream-5.0-overseas-1",
    "prompt": "融合参考图中的杯型和水果元素，生成一张新品海报",
    "image": [
        "https://example.com/reference-cup.png",
        "https://example.com/reference-fruit.png"
    ],
    "size": "2K",
    "n": 1
}'

常用参数：

参数	类型	说明
model	string	图片模型名称，例如 Seedream-5.0-overseas-1
prompt	string	图片生成提示词
image	string 或 string[]	可选，参考图 URL；传多张时表示多图参考
size	string	输出尺寸；Seedream 5.0 建议使用 2K，过小尺寸可能被上游拒绝
n	number	输出图片数量
watermark	boolean	可选，是否添加水印；关闭水印请传顶层字段 false

2. 视频生成

视频生成使用异步任务接口。创建任务后会返回 id 或 task_id，请使用视频查询接口轮询任务状态。

Request URL:POST /v1/video/generations

2.1 文生视频

API_BASE='https://api.goesai.com'
API_KEY='sk-your-goesai-api-key'

curl --location "${API_BASE}/v1/video/generations" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${API_KEY}" \
--data '{
    "model": "Seedance-2.0-overseas-1",
    "prompt": "苹果水果茶广告，镜头缓慢推进，清爽明亮的商业视频",
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
}'

2.2 单图首帧视频

API_BASE='https://api.goesai.com'
API_KEY='sk-your-goesai-api-key'

curl --location "${API_BASE}/v1/video/generations" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${API_KEY}" \
--data '{
    "model": "Seedance-2.0-overseas-1",
    "prompt": "保持参考图中的主体，生成一段顺滑的产品展示视频",
    "image": "https://example.com/reference.png",
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
}'

2.3 多参考图视频

多参考图使用 content 数组。每个参考图对象之间必须用英文逗号分隔；duration 必须是数字，不能写成 秒数 这类占位文本。

API_BASE='https://api.goesai.com'
API_KEY='sk-your-goesai-api-key'

curl --location "${API_BASE}/v1/video/generations" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${API_KEY}" \
--data '{
    "model": "Seedance-2.0-overseas-1",
    "content": [
        {
            "type": "text",
            "text": "根据两张参考图生成一段简短的产品宣传视频，画面高级、干净、商业质感，镜头缓慢推进，突出产品主体。"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://example.com/reference-1.png"
            },
            "role": "reference_image"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://example.com/reference-2.png"
            },
            "role": "reference_image"
        }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
}'

常用参数：

参数	类型	说明
model	string	视频模型名称，例如 Seedance-2.0-overseas-1
prompt	string	文生视频提示词
image	string	可选，单张首帧图片 URL
content	array	可选，多模态输入；支持文本和图片 URL；图片项建议设置 role: "reference_image"
resolution	string	输出分辨率，例如 480p、720p、1080p
ratio	string	输出比例，例如 16:9、9:16、1:1
duration	number	输出视频时长，具体可用范围以模型能力为准

创建任务成功时，响应会返回任务 ID：

{
  "id": "7832344788b7430ead5aa699d5e840a1",
  "object": "video",
  "model": "seedance-2-0-oversea",
  "status": "queued",
  "progress": 0,
  "created_at": 1782401988
}

3. 查询任务

视频生成任务通常需要异步完成。创建任务后，请保存返回的任务 ID，并按接口返回状态轮询结果。

API_BASE='https://api.goesai.com'
API_KEY='sk-your-goesai-api-key'
TASK_ID='7832344788b7430ead5aa699d5e840a1'

curl --location "${API_BASE}/v1/video/generations/${TASK_ID}" \
--header "Authorization: Bearer ${API_KEY}"

当任务状态为成功时，响应中会包含生成结果地址；当任务失败时，请记录响应中的错误信息和请求 ID 以便排查。

4. 常见排查

• JSON 语法错误：数组元素之间必须有英文逗号；字符串必须用双引号；duration 必须是数字。
• 参考图不可访问：上游需要能直接访问参考图 URL。请先执行 curl -I -L 'https://example.com/reference.png'，确认 HTTP 状态为 200。
• 模型不存在：请使用控制台模型列表中的模型名称。Seedance 海外视频示例使用 Seedance-2.0-overseas-1。
• 任务异步失败：创建任务返回 queued 仅表示提交成功，最终结果以查询任务接口返回的状态为准。