redfox-python-sdk 0.4.0__tar.gz → 0.5.0__tar.gz

{redfox_python_sdk-0.4.0 → redfox_python_sdk-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redfox-python-sdk
-Version: 0.4.0
+Version: 0.5.0
 Summary: RedFox 红狐数据平台 Python SDK — 同步+异步双客户端，自动重试，零配置
 Home-page: https://redfox.hk
 Author: RedFox
@@ -574,26 +574,26 @@ result = client.ai_search.baidu_result(task_id=task["taskId"])
 # 文生图
 task = client.gpt_image.submit(
     prompt="一只坐在窗台上的橘猫，阳光洒在毛发上",
-    size="1024x1024",
-    quality="medium",
-    output_format="png",
-    model_name="gpt-image-2",
-    operation="generate",
+    resolution="1k",   # 1k / 2k / 4k
+    size="1:1",        # 宽高比，支持 1:1、16:9、9:16 等 13 种
+    n=1,               # 生成数量，最多 4 张
 )
 result = client.gpt_image.result(task_id=task["taskId"])
+print(result["status"], result["imageUrls"])
 
 # 图生图/编辑
 task = client.gpt_image.submit(
     prompt="将背景替换成海滩",
-    size="1024x1024",
-    model_name="gpt-image-2",
-    operation="edit",
-    input_fidelity=5,
-    images=[{"url": "https://example.com/your-image.jpg"}],
+    resolution="2k",
+    size="16:9",
+    n=2,
+    reference_images=["https://example.com/your-image.jpg"],  # 参考图 URL，最多 2 张
 )
 result = client.gpt_image.result(task_id=task["taskId"])
 ```
 
+> **注意**：`result()` 返回的 `imageUrls` 有效期仅数分钟，过期即 404，请立即下载保存；`status` 实测取值 `queued`/`in_progress`/`completed`/`failed`，仅后两者为终态。用平台生成图作参考图时，必须在其失效前提交。
+
 ### 豆包图片生成
 
 ```python

{redfox_python_sdk-0.4.0 → redfox_python_sdk-0.5.0}/README.md

@@ -550,26 +550,26 @@ result = client.ai_search.baidu_result(task_id=task["taskId"])
 # 文生图
 task = client.gpt_image.submit(
     prompt="一只坐在窗台上的橘猫，阳光洒在毛发上",
-    size="1024x1024",
-    quality="medium",
-    output_format="png",
-    model_name="gpt-image-2",
-    operation="generate",
+    resolution="1k",   # 1k / 2k / 4k
+    size="1:1",        # 宽高比，支持 1:1、16:9、9:16 等 13 种
+    n=1,               # 生成数量，最多 4 张
 )
 result = client.gpt_image.result(task_id=task["taskId"])
+print(result["status"], result["imageUrls"])
 
 # 图生图/编辑
 task = client.gpt_image.submit(
     prompt="将背景替换成海滩",
-    size="1024x1024",
-    model_name="gpt-image-2",
-    operation="edit",
-    input_fidelity=5,
-    images=[{"url": "https://example.com/your-image.jpg"}],
+    resolution="2k",
+    size="16:9",
+    n=2,
+    reference_images=["https://example.com/your-image.jpg"],  # 参考图 URL，最多 2 张
 )
 result = client.gpt_image.result(task_id=task["taskId"])
 ```
 
+> **注意**：`result()` 返回的 `imageUrls` 有效期仅数分钟，过期即 404，请立即下载保存；`status` 实测取值 `queued`/`in_progress`/`completed`/`failed`，仅后两者为终态。用平台生成图作参考图时，必须在其失效前提交。
+
 ### 豆包图片生成
 
 ```python

{redfox_python_sdk-0.4.0 → redfox_python_sdk-0.5.0}/redfox/__init__.py

@@ -3,7 +3,7 @@
 from .client import RedFoxClient, AsyncRedFoxClient
 from .exceptions import RedFoxAPIError, RedFoxAuthError, RedFoxRateLimitError
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 __all__ = [
     "RedFoxClient",
     "AsyncRedFoxClient",

redfox_python_sdk-0.5.0/redfox/endpoints/gpt_image.py

@@ -0,0 +1,77 @@
+"""GPT 图片生成工具 API 端点"""
+
+from typing import Optional, Dict, Any, List
+
+
+class GPTImageAPI:
+    """
+    GPT 图片生成工具 API 集合
+
+    基于 gpt-image-2 模型，支持文生图和参考图生图（最多 2 张参考图）。
+    异步执行：submit() 返回 taskId，再轮询 result() 取 imageUrls。
+
+    注意：result() 返回的图片 URL 有效期仅数分钟，过期后访问返回 404，
+    需立即下载保存；用平台生成图做参考图时也必须在其失效前提交。
+    """
+
+    # 服务端支持的输出分辨率档位
+    RESOLUTIONS = ("1k", "2k", "4k")
+
+    # 服务端支持的输出宽高比
+    SIZES = (
+        "1:1", "3:2", "2:3", "4:3", "3:4", "5:4", "4:5",
+        "16:9", "9:16", "2:1", "1:2", "21:9", "9:21",
+    )
+
+    # result() 的 status 取值，仅后两者为终态
+    TERMINAL_STATUSES = ("completed", "failed")
+
+    def __init__(self, client):
+        self._client = client
+
+    def submit(
+        self,
+        prompt: str,
+        resolution: str = "1k",
+        size: str = "1:1",
+        n: int = 1,
+        reference_images: Optional[List[str]] = None,
+    ) -> dict:
+        """
+        提交 GPT-Image-2 图片生成任务
+
+        :param prompt: 图片生成提示词，描述期望的生成效果（必填）
+        :param resolution: 输出分辨率档位，支持 1k/2k/4k
+        :param size: 输出图片宽高比，支持 1:1、3:2、2:3、4:3、3:4、5:4、4:5、
+                     16:9、9:16、2:1、1:2、21:9、9:21
+        :param n: 生成图片数量，最大 4（超限服务端报 1002）
+        :param reference_images: 参考图片 URL 列表，最多 2 张，用于图生图场景；
+                                 不传则为纯文生图。URL 必须公网可访问且未过期，
+                                 否则任务会以 failed 结束
+        :return: 包含 taskId 的字典
+        """
+        data: Dict[str, Any] = {
+            "prompt": prompt,
+            "resolution": resolution,
+            "size": size,
+            "n": n,
+        }
+        if reference_images:
+            data["referenceImages"] = reference_images
+        return self._client.post(
+            "/story/api/parseWork/imageGen/gptImage2Submit", data=data
+        )
+
+    def result(self, task_id: str) -> dict:
+        """
+        查询 GPT-Image-2 图片生成任务结果
+
+        :param task_id: 任务 ID（由 submit 接口返回）
+        :return: 任务结果字典，包含 status/progress/imageUrls/failReason/
+                 model/resolution/size。status 取值 queued/in_progress/completed/
+                 failed，仅 completed 与 failed 为终态；imageUrls 数量与 n 一致，
+                 但有效期仅数分钟，需立即下载保存
+        """
+        return self._client.post(
+            "/story/api/parseWork/imageGen/gptImage2Result", data={"taskId": task_id}
+        )

{redfox_python_sdk-0.4.0 → redfox_python_sdk-0.5.0}/redfox_python_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redfox-python-sdk
-Version: 0.4.0
+Version: 0.5.0
 Summary: RedFox 红狐数据平台 Python SDK — 同步+异步双客户端，自动重试，零配置
 Home-page: https://redfox.hk
 Author: RedFox
@@ -574,26 +574,26 @@ result = client.ai_search.baidu_result(task_id=task["taskId"])
 # 文生图
 task = client.gpt_image.submit(
     prompt="一只坐在窗台上的橘猫，阳光洒在毛发上",
-    size="1024x1024",
-    quality="medium",
-    output_format="png",
-    model_name="gpt-image-2",
-    operation="generate",
+    resolution="1k",   # 1k / 2k / 4k
+    size="1:1",        # 宽高比，支持 1:1、16:9、9:16 等 13 种
+    n=1,               # 生成数量，最多 4 张
 )
 result = client.gpt_image.result(task_id=task["taskId"])
+print(result["status"], result["imageUrls"])
 
 # 图生图/编辑
 task = client.gpt_image.submit(
     prompt="将背景替换成海滩",
-    size="1024x1024",
-    model_name="gpt-image-2",
-    operation="edit",
-    input_fidelity=5,
-    images=[{"url": "https://example.com/your-image.jpg"}],
+    resolution="2k",
+    size="16:9",
+    n=2,
+    reference_images=["https://example.com/your-image.jpg"],  # 参考图 URL，最多 2 张
 )
 result = client.gpt_image.result(task_id=task["taskId"])
 ```
 
+> **注意**：`result()` 返回的 `imageUrls` 有效期仅数分钟，过期即 404，请立即下载保存；`status` 实测取值 `queued`/`in_progress`/`completed`/`failed`，仅后两者为终态。用平台生成图作参考图时，必须在其失效前提交。
+
 ### 豆包图片生成
 
 ```python

{redfox_python_sdk-0.4.0 → redfox_python_sdk-0.5.0}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="redfox-python-sdk",
-    version="0.4.0",
+    version="0.5.0",
     description="RedFox 红狐数据平台 Python SDK — 同步+异步双客户端，自动重试，零配置",
     long_description=open("README.md", encoding="utf-8").read(),
     long_description_content_type="text/markdown",

redfox_python_sdk-0.4.0/redfox/endpoints/gpt_image.py

@@ -1,77 +0,0 @@
-"""GPT 图片生成工具 API 端点"""
-
-from typing import Optional, Dict, Any, List
-
-
-class GPTImageAPI:
-    """
-    GPT 图片生成工具 API 集合
-
-    支持文生图和图生图，基于 image2-GPT 模型。
-    """
-
-    def __init__(self, client):
-        self._client = client
-
-    def submit(
-        self,
-        prompt: str,
-        n: int = 1,
-        size: str = "1024x1024",
-        quality: str = "medium",
-        background: str = "auto",
-        output_format: str = "png",
-        output_compression: int = None,
-        model_name: str = "gpt-image-2",
-        operation: str = "generate",
-        input_fidelity: str = None,
-        images: List[Dict[str, str]] = None,
-    ) -> dict:
-        """
-        提交 GPT 图片生成任务
-
-        :param prompt: 图片生成提示词（必填）
-        :param n: 生成数量，1~10
-        :param size: 图片尺寸，如 "1024x1024"
-        :param quality: 质量，支持 low/medium/high/auto
-        :param background: 背景类型，支持 transparent/opaque/auto
-        :param output_format: 输出格式，支持 png/jpeg/webp
-        :param output_compression: 输出压缩比，0~100
-        :param model_name: 模型名称，默认 gpt-image-2
-        :param operation: 操作类型，generate（文生图）/ edit（图生图）
-        :param input_fidelity: 输入图保真度，编辑模式（operation=edit）支持 high/low
-        :param images: 图片编辑输入图列表，operation=edit 时必填
-        :return: 包含 taskId 的字典
-        """
-        parameters: Dict[str, Any] = {
-            "modelName": model_name,
-            "n": n,
-            "size": size,
-            "quality": quality,
-            "background": background,
-            "outputFormat": output_format,
-        }
-        if output_compression is not None:
-            parameters["outputCompression"] = output_compression
-        if input_fidelity is not None:
-            parameters["inputFidelity"] = input_fidelity
-
-        data: Dict[str, Any] = {
-            "prompt": prompt,
-            "operation": operation,
-            "parameters": parameters,
-        }
-        if images is not None:
-            data["images"] = images
-        return self._client.post("/story/api/parseWork/imageGen/submitSkill", data=data)
-
-    def result(self, task_id: str) -> dict:
-        """
-        查询 GPT 图片生成任务结果
-
-        :param task_id: 任务 ID（由 submit 接口返回）
-        :return: 任务结果字典，包含 status/imagePaths/failReason
-        """
-        return self._client.post(
-            "/story/api/parseWork/imageGen/result", data={"taskId": task_id}
-        )