GPT Image 2 图片生成 API 接口对接文档

文档基于云声配音官方标准接口规范编制，一站式整合各类接口配置、参数说明、响应范例与开发代码，一站式解决接口对接难题，大幅提升开发效率。

云声配音本接口接入 OpenAI GPT Image 2 模型，提供文生图 与参考图编辑两种核心模式，可快速生成高清创意图像。

一、接口概述

GPT Image 2 是 OpenAI 新一代 AI 生图模型，理解能力强、画面细节丰富，支持文生图、参考图编辑、风格复刻与创意调整，出图质量与写实度大幅提升。

基础信息

接口域名：https://www.yuntts.com
API 前缀：/api/v1
请求方法：POST
认证方式：Bearer Token

二、GPT Image 2 生图接口

接口地址

Plain 复制代码

POST https://www.yuntts.com/api/v1/gpt-image2/generate

请求头

字段名	类型	必填	描述
Authorization	string	是	Bearer Token
Content-Type	string	是	application/json

请求参数

参数	类型	必填	说明
prompt	string	是	图片描述提示词
aspect_ratio	string	否	图片比例，默认 1:1；可选 3:2、2:3、4:3、3:4、16:9、9:16
reference_images	array	否	参考图片 URL 数组（参考图编辑模式）
x_channel	string	否	通道选择，默认 default

请求示例

模式 1：文生图

json 复制代码

{
  "prompt": "一只可爱的橘猫在阳光明媚的花园里玩耍，高清摄影风格，细节丰富，色彩鲜艳",
  "aspect_ratio": "16:9",
  "x_channel": "premium"
}

模式 2：参考图编辑

json 复制代码

{
  "prompt": "将这张图片转换为赛博朋克风格，添加霓虹灯效果，夜晚场景",
  "aspect_ratio": "1:1",
  "reference_images": [
    "https://example.com/reference.jpg"
  ],
  "x_channel": "official"
}

响应格式

成功响应

json 复制代码

{
  "code": 200,
  "message": "任务提交成功",
  "data": {
    "task_id": "gpt_image2_69eca0e4747e3",
    "status": "submitted"
  }
}

失败响应

json 复制代码

{
  "code": 400,
  "message": "请输入提示词",
  "data": null
}

三、GPT Image 2 任务状态查询接口

接口地址

Plain 复制代码

POST https://www.yuntts.com/api/v1/gpt-image2/status

请求头

字段名	类型	必填	描述
Authorization	string	是	Bearer Token
Content-Type	string	是	application/json

请求参数

参数	类型	必填	说明
task_id	string	是	任务 ID，由生图接口返回

请求示例

json 复制代码

{
  "task_id": "gpt_image2_69eca0e4747e3"
}

响应格式

处理中响应

json 复制代码

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "gpt_image2_69eca0e4747e3",
    "status": "processing",
    "progress": 50,
    "prompt": "一只可爱的橘猫在阳光明媚的花园里玩耍...",
    "aspect_ratio": "16:9",
    "created_at": "2026-04-25 19:18:35",
    "updated_at": "2026-04-25 19:18:36"
  }
}

完成响应

json 复制代码

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "gpt_image2_69eca0e4747e3",
    "status": "completed",
    "progress": 100,
    "prompt": "一只可爱的橘猫在阳光明媚的花园里玩耍...",
    "aspect_ratio": "16:9",
    "result_image_url": "https://www.yuntts.com/uploads/da569727-cb54-4d4a-a017-014.png",
    "created_at": "2026-04-25 19:18:35",
    "updated_at": "2026-04-25 19:18:36"
  }
}

失败响应

json 复制代码

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "gpt_image2_69eca0e4747e3",
    "status": "failed",
    "progress": 0,
    "prompt": "一只可爱的橘猫在阳光明媚的花园里玩耍...",
    "aspect_ratio": "16:9",
    "error_message": "API请求失败: 超时",
    "created_at": "2026-04-25 19:18:35",
    "updated_at": "2026-04-25 19:19:00"
  }
}

四、任务状态说明

状态	描述
pending	任务等待中
submitted	任务已提交到 API
processing	图片生成中
completed	生成完成
failed	生成失败

五、完整调用流程

提交生图任务

调用生成接口，获取 task_id。
轮询任务状态

使用 task_id 轮询查询接口，直到状态为 completed 或 failed。
获取生成结果

状态为 completed 时，取 result_image_url 下载图片。

curl 调用示例

bash 复制代码

# 步骤1：提交任务
curl -X POST https://www.yuntts.com/api/v1/gpt-image2/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "prompt": "一只可爱的橘猫在花园里玩耍",
    "aspect_ratio": "16:9",
    "x_channel": "premium"
  }'

# 步骤2：轮询状态
curl -X POST https://www.yuntts.com/api/v1/gpt-image2/status \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"task_id": "gpt_image2_69eca0e4747e3"}'

六、错误码说明

错误码	消息	说明
400	请输入提示词	prompt 参数不能为空
400	余额不足，请先充值	用户余额不足以支付生成费用
401	无效的 API 密钥	API 密钥错误或已过期
500	API 密钥未配置	系统未配置 MXAPI API 密钥
500	任务创建失败	数据库操作失败
500	积分扣除失败	余额扣除操作失败
500	API 提交失败	调用远程 API 失败

七、支持的图片比例与适用场景

比例	适用场景
1:1	社交媒体头像、产品展示
3:2	风景照片、横幅
2:3	人像照片、社交媒体帖子
4:3	传统照片、文档
3:4	竖版照片、移动设备
16:9	宽屏展示、视频封面
9:16	竖屏视频、Instagram 故事

八、示例代码

JavaScript 示例

javascript 复制代码

// 提交生图任务
async function submitGenerateTask() {
  const response = await fetch('https://www.yuntts.com/api/v1/gpt-image2/generate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({
      prompt: '一只可爱的橘猫在花园里玩耍',
      aspect_ratio: '16:9'
    })
  });

  const result = await response.json();
  if (result.code === 200) {
    const taskId = result.data.task_id;
    startPolling(taskId);
  }
}

// 轮询任务状态
function startPolling(taskId) {
  const interval = setInterval(async () => {
    const response = await fetch('https://www.yuntts.com/api/v1/gpt-image2/status', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
      },
      body: JSON.stringify({ task_id: taskId })
    });

    const result = await response.json();
    if (result.code === 200) {
      const status = result.data.status;
      if (status === 'completed') {
        clearInterval(interval);
        console.log('生成完成:', result.data.result_image_url);
      } else if (status === 'failed') {
        clearInterval(interval);
        console.error('生成失败:', result.data.error_message);
      }
    }
  }, 3000);
}

Python 示例

python 复制代码

import requests
import time

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://www.yuntts.com/api/v1'

def submit_task():
    url = f'{BASE_URL}/gpt-image2/generate'
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {API_KEY}'
    }
    data = {
        'prompt': '一只可爱的橘猫在花园里玩耍',
        'aspect_ratio': '16:9'
    }

    response = requests.post(url, headers=headers, json=data)
    result = response.json()
    if result['code'] == 200:
        return result['data']['task_id']
    return None

def check_status(task_id):
    url = f'{BASE_URL}/gpt-image2/status'
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {API_KEY}'
    }
    data = {'task_id': task_id}

    response = requests.post(url, headers=headers, json=data)
    return response.json()

# 调用示例
task_id = submit_task()

if task_id:
    while True:
        status = check_status(task_id)
        if status['code'] == 200:
            task_status = status['data']['status']
            if task_status == 'completed':
                print('生成完成:', status['data']['result_image_url'])
                break
            elif task_status == 'failed':
                print('生成失败:', status['data']['error_message'])
                break
        time.sleep(3)

九、注意事项

所有请求必须在请求头中携带 Authorization: Bearer YOUR\_API\_KEY。
任务轮询建议间隔 3--5 秒，避免请求过于频繁。
参考图片 URL 必须为可公开访问的有效地址。
生成图片会消耗积分，具体价格以系统设置为准。
不同 x_channel 可能影响生成速度与稳定性。
请根据使用场景选择合适的图片比例，以获得最佳效果。