chore: sync from ark-apis d20f0d68da

VERSION

@@ -1 +1 @@
-0.5.0
+0.6.0

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "arkruntime"
-version = "0.5.0"
+version = "0.6.0"
 description = "Ark runtime SDK for Python"
 readme = "README.md"
 requires-python = ">=3.8"

src/arkruntime/resources/images/images.py

@@ -4,7 +4,7 @@
 
 from __future__ import annotations
 
-from typing import List, Optional
+from typing import List, Optional, Union
 
 import httpx
 
@@ -14,6 +14,7 @@
 from ..._types import Body, Headers, Query
 
 # AUTOGEN-START create-imports
+from ...types.images.background import Background
 from ...types.images.image_generation_response import ImageGenerationResponse
 from ...types.images.image_generation_stream_event import ImageGenerationStreamEvent
 from ...types.images.optimize_prompt_options_param import OptimizePromptOptionsParam
@@ -36,8 +37,8 @@ def generate(
         *,
         # AUTOGEN-START create-kwargs
         model: str,
-        prompt: str,
-        image: Optional[List[str]] = None,
+        prompt: Optional[str] = None,
+        image: Optional[Union[str, List[str]]] = None,
         stream: Optional[bool] = None,
         response_format: Optional[ResponseFormat] = None,
         seed: Optional[int] = None,
@@ -50,6 +51,7 @@ def generate(
         optimize_prompt_options: Optional[OptimizePromptOptionsParam] = None,
         tools: Optional[List[ToolParam]] = None,
         output_format: Optional[OutputFormat] = None,
+        background: Optional[Background] = None,
         layer_decomposition: Optional[bool] = None,
         # AUTOGEN-END create-kwargs
         extra_headers: Headers | None = None,
@@ -76,6 +78,7 @@ def generate(
                 "optimize_prompt_options": optimize_prompt_options,
                 "tools": tools,
                 "output_format": output_format,
+                "background": background,
                 "layer_decomposition": layer_decomposition,
                 # AUTOGEN-END create-body
             },
@@ -97,8 +100,8 @@ async def generate(
         *,
         # AUTOGEN-START create-kwargs
         model: str,
-        prompt: str,
-        image: Optional[List[str]] = None,
+        prompt: Optional[str] = None,
+        image: Optional[Union[str, List[str]]] = None,
         stream: Optional[bool] = None,
         response_format: Optional[ResponseFormat] = None,
         seed: Optional[int] = None,
@@ -111,6 +114,7 @@ async def generate(
         optimize_prompt_options: Optional[OptimizePromptOptionsParam] = None,
         tools: Optional[List[ToolParam]] = None,
         output_format: Optional[OutputFormat] = None,
+        background: Optional[Background] = None,
         layer_decomposition: Optional[bool] = None,
         # AUTOGEN-END create-kwargs
         extra_headers: Headers | None = None,
@@ -137,6 +141,7 @@ async def generate(
                 "optimize_prompt_options": optimize_prompt_options,
                 "tools": tools,
                 "output_format": output_format,
+                "background": background,
                 "layer_decomposition": layer_decomposition,
                 # AUTOGEN-END create-body
             },

src/arkruntime/types/images/__init__.py

@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+from .background import Background
 from .bounding_box import BoundingBox
 from .create_image_generation_request import CreateImageGenerationRequest
 from .image_data_item import ImageDataItem
@@ -25,6 +26,7 @@
 from .usage import Usage
 
 __all__ = [
+    "Background",
     "BoundingBox",
     "CreateImageGenerationRequest",
     "ImageDataItem",

src/arkruntime/types/images/background.py

@@ -0,0 +1,18 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` in ark-apis.
+#
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Background(str, Enum):
+    """
+    Background of the generated image.
+    """
+
+    opaque = "opaque"
+    transparent = "transparent"

src/arkruntime/types/images/create_image_generation_request.py

@@ -6,10 +6,11 @@
 
 from __future__ import annotations
 
-from typing import List, Optional
+from typing import List, Optional, Union
 
 from arkruntime._models import BaseModel
 
+from .background import Background
 from .optimize_prompt_options import OptimizePromptOptions
 from .output_format import OutputFormat
 from .response_format import ResponseFormat
@@ -23,13 +24,13 @@ class CreateImageGenerationRequest(BaseModel):
     """
     The model identifier to use.
     """
-    prompt: str
+    prompt: Optional[str] = None
     """
-    Text prompt describing the desired image.
+    Text prompt describing the desired image. Required for standard generation; may be omitted for automatic layer decomposition when `layer_decomposition=true`.
     """
-    image: Optional[List[str]] = None
+    image: Optional[Union[str, List[str]]] = None
     """
-    Reference / edit images. Each entry is a URL or a `data:` URI.
+    Reference / edit images, as a single URL or `data:` URI, or an array of them.
     """
     stream: Optional[bool] = None
     """
@@ -81,6 +82,10 @@ class CreateImageGenerationRequest(BaseModel):
     """
     Container/codec for the generated image bytes.
     """
+    background: Optional[Background] = None
+    """
+    Output background. Defaults to `opaque`. `transparent` requires exactly one PNG reference image with an alpha channel and PNG output.
+    """
     layer_decomposition: Optional[bool] = None
     """
     Decompose one reference image into a base image and independently

src/arkruntime/types/images/create_image_generation_request_param.py

@@ -6,10 +6,11 @@
 
 from __future__ import annotations
 
-from typing import List, Optional
+from typing import List, Optional, Union
 
 from typing_extensions import Required, TypedDict
 
+from .background import Background
 from .optimize_prompt_options_param import OptimizePromptOptionsParam
 from .output_format import OutputFormat
 from .response_format import ResponseFormat
@@ -24,11 +25,11 @@ class CreateImageGenerationRequestParam(TypedDict, total=False):
     model: Required[str]
     """The model identifier to use."""
 
-    prompt: Required[str]
-    """Text prompt describing the desired image."""
+    prompt: Optional[str]
+    """Text prompt describing the desired image. Required for standard generation; may be omitted for automatic layer decomposition when `layer_decomposition=true`."""
 
-    image: Optional[List[str]]
-    """Reference / edit images. Each entry is a URL or a `data:` URI."""
+    image: Optional[Union[str, List[str]]]
+    """Reference / edit images, as a single URL or `data:` URI, or an array of them."""
 
     stream: Optional[bool]
     """Stream partial images as they are generated (server-sent events)."""
@@ -66,6 +67,9 @@ class CreateImageGenerationRequestParam(TypedDict, total=False):
     output_format: Optional[OutputFormat]
     """Container/codec for the generated image bytes."""
 
+    background: Optional[Background]
+    """Output background. Defaults to `opaque`. `transparent` requires exactly one PNG reference image with an alpha channel and PNG output."""
+
     layer_decomposition: Optional[bool]
     """
     Decompose one reference image into a base image and independently

src/arkruntime/types/session/__init__.py

@@ -8,18 +8,21 @@
 
 from .agent_identifier import AgentIdentifier
 from .agent_ref import AgentRef
+from .agent_with_upgrades import AgentWithUpgrades
 from .base64_document_source import Base64DocumentSource
 from .base64_image_source import Base64ImageSource
 from .cache_creation import CacheCreation
 from .create_session_request import CreateSessionRequest
 from .create_session_resource_request import CreateSessionResourceRequest
+from .create_session_upgrade_request import CreateSessionUpgradeRequest
 from .delete_session_response import DeleteSessionResponse
 from .document_source import DocumentSource
 from .environment_config_override import EnvironmentConfigOverride
 from .environment_networking_config import EnvironmentNetworkingConfig
 from .environment_packages_config import EnvironmentPackagesConfig
 from .environment_tos_config import EnvironmentTosConfig
 from .environment_with_overrides import EnvironmentWithOverrides
+from .environment_with_upgrades import EnvironmentWithUpgrades
 from .file_document_source import FileDocumentSource
 from .file_image_source import FileImageSource
 from .image_source import ImageSource
@@ -72,6 +75,7 @@
     ManagedAgentsUserToolResultEventParams,
 )
 from .model_overrides import ModelOverrides
+from .model_upgrades import ModelUpgrades
 from .plain_text_document_source import PlainTextDocumentSource
 from .search_result_citations import SearchResultCitations
 from .search_result_content import SearchResultContent
@@ -94,18 +98,21 @@
 __all__ = [
     "AgentIdentifier",
     "AgentRef",
+    "AgentWithUpgrades",
     "Base64DocumentSource",
     "Base64ImageSource",
     "CacheCreation",
     "CreateSessionRequest",
     "CreateSessionResourceRequest",
+    "CreateSessionUpgradeRequest",
     "DeleteSessionResponse",
     "DocumentSource",
     "EnvironmentConfigOverride",
     "EnvironmentNetworkingConfig",
     "EnvironmentPackagesConfig",
     "EnvironmentTosConfig",
     "EnvironmentWithOverrides",
+    "EnvironmentWithUpgrades",
     "FileDocumentSource",
     "FileImageSource",
     "ImageSource",
@@ -142,6 +149,7 @@
     "ManagedAgentsUserToolConfirmationEventParams",
     "ManagedAgentsUserToolResultEventParams",
     "ModelOverrides",
+    "ModelUpgrades",
     "PlainTextDocumentSource",
     "SearchResultCitations",
     "SearchResultContent",

src/arkruntime/types/session/agent_with_upgrades.py

@@ -0,0 +1,73 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` in ark-apis.
+#
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Dict, List, Literal, Optional
+
+from arkruntime._models import BaseModel
+
+from .model_upgrades import ModelUpgrades
+
+
+class AgentWithUpgrades(BaseModel):
+    """
+    Session upgrade 的目标 Agent 运行配置。
+
+    `id` 必须等于当前 Session 的 Agent ID —— upgrade 不支持换绑到另一个
+    Agent，不一致返回 403 `AgentMismatch`。
+
+    数组字段（`tools` / `mcp_servers` / `skills`）是**整组替换**语义：省略
+    表示保留原值，显式传 `[]` 表示清空。两者在 wire 上必须可区分，SDK 不能
+    把空数组优化成省略字段。
+    """
+
+    type: Literal["agent_with_upgrades"]
+    """
+    固定 `"agent_with_upgrades"`。
+    """
+    id: str
+    """
+    Agent ID；必须与当前 Session 的 Agent ID 一致。
+    """
+    version: Optional[int] = None
+    """
+    目标 Agent 版本号。
+
+    省略或传 `0` 表示**不锁版本、沿用 Session 当前的 Agent 快照**（注意与创建
+    期不同：这里不是"走最新版"）。传正整数则以该版本的 payload 为基线物化
+    ——`system` / `tools` / `mcp_servers` / `skills` / `multiagent` / `model`
+    整组跟着版本走，本次请求里的同名字段再叠加其上；版本不存在返回 404。
+    传负数返回 400。
+    """
+    model: Optional[ModelUpgrades] = None
+    """
+    模型运行参数升级。
+    """
+    system: Optional[str] = None
+    """
+    System prompt。
+    """
+    tools: Optional[List[Dict[str, object]]] = None
+    """
+    工具配置（整组替换）。
+    """
+    mcp_servers: Optional[List[Dict[str, object]]] = None
+    """
+    MCP server 配置（整组替换）。
+    """
+    skills: Optional[List[Dict[str, object]]] = None
+    """
+    Skill 配置（整组替换）。
+    """
+    multiagent: Optional[Dict[str, object]] = None
+    """
+    多 Agent 配置。
+    """
+    display_name: Optional[str] = None
+    """
+    Agent 展示名。
+    """

src/arkruntime/types/session/create_session_upgrade_request.py

@@ -0,0 +1,53 @@
+# Generated by datamodel-code-generator from ark-apis typespec/openapi.
+# DO NOT EDIT — regenerate with `make gen-py-<api>` in ark-apis.
+#
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from arkruntime._models import BaseModel
+
+from .agent_with_upgrades import AgentWithUpgrades
+from .environment_with_upgrades import EnvironmentWithUpgrades
+from .managed_agents_event_params import ManagedAgentsEventParams
+
+
+class CreateSessionUpgradeRequest(BaseModel):
+    """
+    发起一次已有 Session 的运行配置升级。
+
+    `agent` / `environment` / `vault_ids` 至少提供一个作为升级目标，全部省略
+    返回 400 `MissingUpgradeTarget`（只传 `initial_events` 不算升级目标）。
+    Session 必须处于 `idle` 且上一轮 turn 以 `end_turn` 收尾，否则返回 403
+    `SessionNotIdle` / `SessionNotEndTurn`；同一 Session 上一次升级尚未收敛时
+    返回 403 `UpgradeInProgress`。
+    """
+
+    agent: Optional[AgentWithUpgrades] = None
+    """
+    目标 Agent 运行配置。
+    """
+    environment: Optional[EnvironmentWithUpgrades] = None
+    """
+    目标 Environment 运行配置。
+    """
+    vault_ids: Optional[List[str]] = None
+    """
+    Session 绑定的 Vault 列表。
+
+    只能用来**刷新已绑定 Vault 的内容**，不能改变绑定集合：传入集合必须与
+    当前 Session 的 `vault_ids` 相等（忽略顺序与重复），否则返回 403
+    `VaultMismatch`。显式传 `[]` 表示声明空集，仅当当前 Session 本身没有
+    Vault 绑定时通过 —— 因此省略与 `[]` 在 wire 上必须可区分，SDK 不能把
+    空数组优化成省略字段。
+    """
+    initial_events: Optional[List[ManagedAgentsEventParams]] = None
+    """
+    配置切换收敛后由服务端补投的事件。当前只接受**恰好一个** `user.message`
+    事件，且 content 为单个 text block、内容是 `/compact` 命令 XML；不满足
+    返回 400 `InvalidInitialEvents` / `InvalidCompactCommand`。省略或传 `[]`
+    表示本次不投递事件。
+    """