ads_dev 1.0.0__tar.gz → 1.1.0__tar.gz

{ads_dev-1.0.0 → ads_dev-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ads_dev
-Version: 1.0.0
+Version: 1.1.0
 Summary: The ads.dev API for Python: image, video and audio generation on your brand, the brand kit and library, and competitor ads
 Keywords: ads.dev,sandstorm,ads,image generation,video generation,ai,api
 License-Expression: MIT
@@ -153,6 +153,7 @@ uv sync
 uv run pytest
 uv run python scripts/generate.py
 uv build
+uv run python scripts/aliases.py
 ```
 
-`ads_dev/types.py` is generated from `../sdk/openapi.json`, the API's own document, and `ads_dev/_sync/client.py` from the async client with `unasync`; `scripts/generate.py` writes both, and the tests fail when either is stale. Build with uv 0.13 or newer.
+`ads_dev/types.py` is generated from `../sdk/openapi.json`, the API's own document, and `ads_dev/_sync/client.py` from the async client with `unasync`; `scripts/generate.py` writes both, and the tests fail when either is stale. `scripts/aliases.py` builds `adsdotdev` and `sandstormapp`, which install `ads_dev` under those names, into `dist/` beside it, so `uv publish` uploads all three. Build with uv 0.13 or newer.

{ads_dev-1.0.0 → ads_dev-1.1.0}/README.md

@@ -134,6 +134,7 @@ uv sync
 uv run pytest
 uv run python scripts/generate.py
 uv build
+uv run python scripts/aliases.py
 ```
 
-`ads_dev/types.py` is generated from `../sdk/openapi.json`, the API's own document, and `ads_dev/_sync/client.py` from the async client with `unasync`; `scripts/generate.py` writes both, and the tests fail when either is stale. Build with uv 0.13 or newer.
+`ads_dev/types.py` is generated from `../sdk/openapi.json`, the API's own document, and `ads_dev/_sync/client.py` from the async client with `unasync`; `scripts/generate.py` writes both, and the tests fail when either is stale. `scripts/aliases.py` builds `adsdotdev` and `sandstormapp`, which install `ads_dev` under those names, into `dist/` beside it, so `uv publish` uploads all three. Build with uv 0.13 or newer.

{ads_dev-1.0.0 → ads_dev-1.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ads_dev"
-version = "1.0.0"
+version = "1.1.0"
 description = "The ads.dev API for Python: image, video and audio generation on your brand, the brand kit and library, and competitor ads"
 readme = "README.md"
 license = "MIT"

{ads_dev-1.0.0 → ads_dev-1.1.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ads_dev"
-version = "1.0.0"
+version = "1.1.0"
 description = "The ads.dev API for Python: image, video and audio generation on your brand, the brand kit and library, and competitor ads"
 readme = "README.md"
 license = "MIT"

{ads_dev-1.0.0 → ads_dev-1.1.0}/src/ads_dev/_async/client.py

@@ -15,6 +15,7 @@ from .._core import (
     RETRYABLE,
     RUN_TIMEOUT_S,
     GenerationFailed,
+    answer_of,
     delay_of,
     headers_of,
     is_finished,
@@ -328,8 +329,8 @@ class AsyncSandstorm:
                 attempt += 1
                 continue
             if response.is_success:
-                return shape.model_validate(response.json())
+                return shape.model_validate(answer_of(response, self._base_url))
             if response.status_code not in RETRYABLE or attempt >= self._max_retries:
-                raise refusal_of(response)
+                raise refusal_of(response, self._base_url)
             await anyio.sleep(delay_of(attempt, response))
             attempt += 1

{ads_dev-1.0.0 → ads_dev-1.1.0}/src/ads_dev/_core.py

@@ -24,12 +24,6 @@ RETRYABLE = frozenset({408, 429, 500, 502, 503, 504})
 
 FINISHED = frozenset({"succeeded", "failed", "canceled"})
 
-MISSING_KEY = (
-    "Pass api_key or set SANDSTORM_API_KEY. To make a key: "
-    "curl -fsSL https://ads.dev/login.mjs -o sandstorm-login.mjs && node sandstorm-login.mjs"
-)
-
-
 class SandstormError(Exception):
     def __init__(self, status: int, refusal: Mapping[str, Any]) -> None:
         super().__init__(refusal.get("message", ""))
@@ -51,10 +45,14 @@ def is_finished(generation: Generation) -> bool:
 
 
 def settings(api_key: str | None, base_url: str | None) -> tuple[str, str]:
+    url = (base_url or os.environ.get("SANDSTORM_API_URL") or BASE_URL).rstrip("/")
     key = api_key or os.environ.get("SANDSTORM_API_KEY")
     if not key:
-        raise ValueError(MISSING_KEY)
-    return key, (base_url or os.environ.get("SANDSTORM_API_URL") or BASE_URL).rstrip("/")
+        raise ValueError(
+            "Pass api_key or set SANDSTORM_API_KEY. To make a key: "
+            f"curl -fsSL {url}/login.mjs -o sandstorm-login.mjs && node sandstorm-login.mjs"
+        )
+    return key, url
 
 
 def headers_of(api_key: str, brand: str | None) -> dict[str, str]:
@@ -65,14 +63,32 @@ def query_of(params: Mapping[str, Any]) -> dict[str, str]:
     return {name: ("true" if value is True else "false" if value is False else str(value)) for name, value in params.items() if value is not None}
 
 
-def refusal_of(response: httpx.Response) -> SandstormError:
-    try:
-        return SandstormError(response.status_code, response.json()["error"])
-    except (ValueError, KeyError, TypeError):
-        return SandstormError(
-            response.status_code,
-            {"message": response.text or response.reason_phrase, "request_id": response.headers.get("sandstorm-request-id")},
-        )
+def is_json(response: httpx.Response) -> bool:
+    return "json" in response.headers.get("content-type", "")
+
+
+def not_the_api(response: httpx.Response, base_url: str) -> SandstormError:
+    kind = response.headers.get("content-type", "no content type")
+    return SandstormError(
+        response.status_code,
+        {
+            "code": "not_the_api",
+            "message": f"{base_url} answered {response.status_code} with {kind} instead of the API's JSON. "
+            f"If {base_url} is not the Sandstorm API, pass base_url or set SANDSTORM_API_URL.",
+        },
+    )
+
+
+def answer_of(response: httpx.Response, base_url: str) -> Any:
+    if not is_json(response):
+        raise not_the_api(response, base_url)
+    return response.json()
+
+
+def refusal_of(response: httpx.Response, base_url: str) -> SandstormError:
+    if not is_json(response):
+        return not_the_api(response, base_url)
+    return SandstormError(response.status_code, response.json()["error"])
 
 
 def delay_of(attempt: int, response: httpx.Response | None) -> float:

{ads_dev-1.0.0 → ads_dev-1.1.0}/src/ads_dev/_sync/client.py

@@ -15,6 +15,7 @@ from .._core import (
     RETRYABLE,
     RUN_TIMEOUT_S,
     GenerationFailed,
+    answer_of,
     delay_of,
     headers_of,
     is_finished,
@@ -328,8 +329,8 @@ class Sandstorm:
                 attempt += 1
                 continue
             if response.is_success:
-                return shape.model_validate(response.json())
+                return shape.model_validate(answer_of(response, self._base_url))
             if response.status_code not in RETRYABLE or attempt >= self._max_retries:
-                raise refusal_of(response)
+                raise refusal_of(response, self._base_url)
             time.sleep(delay_of(attempt, response))
             attempt += 1

{ads_dev-1.0.0 → ads_dev-1.1.0}/src/ads_dev/types.py

@@ -4,7 +4,6 @@
 from __future__ import annotations
 
 from typing import Any, Literal
-from uuid import UUID
 
 from pydantic import (
     AnyUrl,
@@ -54,7 +53,7 @@ class CreateNanoBananaPro(BaseModel):
 class CreateNanoBananaProEditInput(BaseModel):
     prompt: constr(min_length=3, max_length=50000) = Field(
         ...,
-        description="The change to make, or how the images come together, naming each image by its place in images.",
+        description="The change to make, or how the images come together, citing each image by its place in images as @image1, @image2.",
     )
     aspect_ratio: (
         Literal[
@@ -80,7 +79,7 @@ class CreateNanoBananaProEditInput(BaseModel):
     )
     images: list[str] = Field(
         ...,
-        description="The 1 to 14 images to edit or combine, in the order the prompt names them, each an asset id (asset_…) or an https URL.",
+        description="The 1 to 14 images to edit or combine, in the order the prompt cites them, each an asset id (asset_…) or an https URL.",
         max_length=14,
         min_length=1,
     )
@@ -157,7 +156,7 @@ class CreateNanoBanana2(BaseModel):
 class CreateNanoBanana2EditInput(BaseModel):
     prompt: constr(min_length=3, max_length=50000) = Field(
         ...,
-        description="The change to make, or how the images come together, naming each image by its place in images.",
+        description="The change to make, or how the images come together, citing each image by its place in images as @image1, @image2.",
     )
     aspect_ratio: (
         Literal[
@@ -187,7 +186,7 @@ class CreateNanoBanana2EditInput(BaseModel):
     )
     images: list[str] = Field(
         ...,
-        description="The 1 to 14 images to edit or combine, in the order the prompt names them, each an asset id (asset_…) or an https URL.",
+        description="The 1 to 14 images to edit or combine, in the order the prompt cites them, each an asset id (asset_…) or an https URL.",
         max_length=14,
         min_length=1,
     )
@@ -261,7 +260,7 @@ class CreateNanoBanana2Lite(BaseModel):
 class CreateNanoBanana2LiteEditInput(BaseModel):
     prompt: constr(min_length=3, max_length=50000) = Field(
         ...,
-        description="The change to make, or how the images come together, naming each image by its place in images.",
+        description="The change to make, or how the images come together, citing each image by its place in images as @image1, @image2.",
     )
     aspect_ratio: (
         Literal[
@@ -288,7 +287,7 @@ class CreateNanoBanana2LiteEditInput(BaseModel):
     )
     images: list[str] = Field(
         ...,
-        description="The 1 to 14 images to edit or combine, in the order the prompt names them, each an asset id (asset_…) or an https URL.",
+        description="The 1 to 14 images to edit or combine, in the order the prompt cites them, each an asset id (asset_…) or an https URL.",
         max_length=14,
         min_length=1,
     )
@@ -363,7 +362,7 @@ class CreateGptImage25Flare(BaseModel):
 class CreateGptImage25FlareEditInput(BaseModel):
     prompt: constr(min_length=1, max_length=32000) = Field(
         ...,
-        description="The change to make, or how the images come together, naming each image by its place in images and writing out exactly any words the image must show.",
+        description="The change to make, or how the images come together, citing each image by its place in images as @image1, @image2 and writing out exactly any words the image must show.",
     )
     aspect_ratio: (
         Literal[
@@ -403,7 +402,7 @@ class CreateGptImage25FlareEditInput(BaseModel):
     )
     images: list[str] = Field(
         ...,
-        description="The 1 to 16 images to edit or combine, in the order the prompt names them, each an asset id (asset_…) or an https URL.",
+        description="The 1 to 16 images to edit or combine, in the order the prompt cites them, each an asset id (asset_…) or an https URL.",
         max_length=16,
         min_length=1,
     )
@@ -478,7 +477,7 @@ class CreateGptImage25Sunburst(BaseModel):
 class CreateGptImage25SunburstEditInput(BaseModel):
     prompt: constr(min_length=1, max_length=32000) = Field(
         ...,
-        description="The change to make, or how the images come together, naming each image by its place in images and writing out exactly any words the image must show.",
+        description="The change to make, or how the images come together, citing each image by its place in images as @image1, @image2 and writing out exactly any words the image must show.",
     )
     aspect_ratio: (
         Literal[
@@ -518,7 +517,7 @@ class CreateGptImage25SunburstEditInput(BaseModel):
     )
     images: list[str] = Field(
         ...,
-        description="The 1 to 16 images to edit or combine, in the order the prompt names them, each an asset id (asset_…) or an https URL.",
+        description="The 1 to 16 images to edit or combine, in the order the prompt cites them, each an asset id (asset_…) or an https URL.",
         max_length=16,
         min_length=1,
     )
@@ -581,7 +580,7 @@ class CreateSeedream5Pro(BaseModel):
 class CreateSeedream5ProEditInput(BaseModel):
     prompt: constr(min_length=3) = Field(
         ...,
-        description="The change to make as one paragraph, at most 600 words, naming each image by its place in images (image 1, image 2), with the exact words the result must show written out.",
+        description="The change to make as one paragraph, at most 600 words, citing each image by its place in images as @image1, @image2, with the exact words the result must show written out.",
     )
     aspect_ratio: (
         Literal[
@@ -608,7 +607,7 @@ class CreateSeedream5ProEditInput(BaseModel):
     )
     images: list[str] = Field(
         ...,
-        description="The images to edit or combine, in the order the prompt names them, at most 10, each an asset id (asset_…) or an https URL.",
+        description="The images to edit or combine, in the order the prompt cites them, at most 10, each an asset id (asset_…) or an https URL.",
         max_length=10,
         min_length=1,
     )
@@ -664,7 +663,7 @@ class CreateSeedream5Lite(BaseModel):
 class CreateSeedream5LiteEditInput(BaseModel):
     prompt: constr(min_length=3) = Field(
         ...,
-        description="The change to make as one paragraph, at most 600 words, naming each image by its place in images (image 1, image 2), with the exact words the result must show written out.",
+        description="The change to make as one paragraph, at most 600 words, citing each image by its place in images as @image1, @image2, with the exact words the result must show written out.",
     )
     aspect_ratio: (
         Literal[
@@ -688,7 +687,7 @@ class CreateSeedream5LiteEditInput(BaseModel):
     )
     images: list[str] = Field(
         ...,
-        description="The images to edit or combine, in the order the prompt names them, at most 14, each an asset id (asset_…) or an https URL.",
+        description="The images to edit or combine, in the order the prompt cites them, at most 14, each an asset id (asset_…) or an https URL.",
         max_length=14,
         min_length=1,
     )
@@ -898,7 +897,7 @@ class CreateSeedance25ImageToVideo(BaseModel):
 class CreateSeedance25ReferenceToVideoInput(BaseModel):
     prompt: constr(min_length=3, max_length=50000) = Field(
         ...,
-        description="What happens in the clip, citing each image, video or audio by its place in its list as @Image1, @Video1 or @Audio1.",
+        description="What happens in the clip, citing each image, video or audio by its place in its list as @image1, @video1 or @audio1.",
     )
     task: Literal["auto", "reference", "editing", "extension"] | None = Field(
         "auto",
@@ -911,12 +910,12 @@ class CreateSeedance25ReferenceToVideoInput(BaseModel):
     )
     videos: list[str] | None = Field(
         [],
-        description="Up to 10 videos, 30 seconds together at most, each an asset id (asset_…) or an https URL; none when left out.",
+        description="Up to 10 videos, each an asset id (asset_…) or an https URL; none when left out. Past 30 seconds together the longer ones are cut to their opening seconds, and beside audio their own sound is left out; editing and extension take them whole, so those must run 30 seconds or less together.",
         max_length=10,
     )
     audio: list[str] | None = Field(
         [],
-        description="Up to 10 wav or mp3 files, 30 seconds together at most, each an asset id (asset_…) or an https URL; none when left out.",
+        description="Up to 10 audio files, each an asset id (asset_…) or an https URL; none when left out. Past 30 seconds together the longer ones are cut to their opening seconds.",
         max_length=10,
     )
     aspect_ratio: (
@@ -1095,7 +1094,7 @@ class CreateKlingO3ProReferenceToVideoInputElements1(BaseModel):
     )
     video: str = Field(
         ...,
-        description="A clip of the character or object, 3 to 10 seconds at 720 to 2160 px a side, as an asset id (asset_…) or an https URL, in place of images.",
+        description="A clip of the character or object of at least 3 seconds, as an asset id (asset_…) or an https URL, in place of images; past 10 seconds it is cut to its opening 10, and outside 720 to 2160 px a side it is resized to fit.",
     )
 
 
@@ -1121,7 +1120,7 @@ class CreateKlingO3ProReferenceToVideoInput(BaseModel):
     )
     images: list[str] | None = Field(
         [],
-        description="Up to 4 images whose subject or look the clip keeps, each an asset id (asset_…) or an https URL, cited in the prompt as @Image1, @Image2 in this order; none when left out.",
+        description="Up to 4 images whose subject or look the clip keeps, each an asset id (asset_…) or an https URL, cited in the prompt as @image1, @image2 in this order; none when left out.",
         max_length=4,
     )
     elements: (
@@ -1129,7 +1128,7 @@ class CreateKlingO3ProReferenceToVideoInput(BaseModel):
             CreateKlingO3ProReferenceToVideoInputElements | CreateKlingO3ProReferenceToVideoInputElements1
         ]
         | None
-    ) = Field([], description="Characters or objects held to one look across the clip, cited in the prompt as @Element1, @Element2 in this order; images and elements take 4 together at most, and none when left out.", max_length=4, validate_default=True)
+    ) = Field([], description="Characters or objects held to one look across the clip, cited in the prompt as @element1, @element2 in this order; images and elements take 4 together at most, and none when left out.", max_length=4, validate_default=True)
     aspect_ratio: Literal["16:9", "9:16", "1:1"] | None = Field(
         "16:9", description="Shape of the clip as width:height; 16:9 when left out."
     )
@@ -1242,7 +1241,7 @@ class CreateGeminiOmniFlashImageToVideo(BaseModel):
 class CreateGeminiOmniFlashReferenceToVideoInput(BaseModel):
     prompt: constr(min_length=3, max_length=20000) = Field(
         ...,
-        description="What happens in the clip, citing each image or video inline by its place in its list from 0, as <IMAGE_REF_0> or <VIDEO_REF_0>, with any spoken line in double quotes.",
+        description="What happens in the clip, citing each image or video by its place in its list as @image1 or @video1, with any spoken line in double quotes.",
     )
     images: list[str] | None = Field(
         [],
@@ -1251,7 +1250,7 @@ class CreateGeminiOmniFlashReferenceToVideoInput(BaseModel):
     )
     videos: list[str] | None = Field(
         [],
-        description="Up to 3 videos, each shorter than 3 seconds, for a likeness or a motion to copy, whose sound is ignored, each an asset id (asset_…) or an https URL; none when left out.",
+        description="Up to 3 videos for a likeness or a motion to copy, whose sound is ignored, each an asset id (asset_…) or an https URL and cut to its opening 3 seconds when longer; none when left out.",
         max_length=3,
     )
     aspect_ratio: Literal["9:16", "16:9"] | None = Field(
@@ -1575,8 +1574,8 @@ class GenerationOutputItem(BaseModel):
     name: str | None
     url: str
     content_type: str
-    width: float | None = None
-    height: float | None = None
+    width: int | None = None
+    height: int | None = None
     duration: float | None = None
     role: Literal["main", "last_frame", "layer"]
     layer: GenerationOutputItemLayer | None = None
@@ -1619,7 +1618,11 @@ class ModelPricingRate(BaseModel):
     usd: float
     when: dict[str, Any] = Field(
         ...,
-        description="The input settings the rate applies to; empty when it applies to all",
+        description="The inputs, by their names in input, that this rate applies to; a media input is true when given and false when not; empty when it applies to all. A rate charged on the input itself carries `input`: the tokens of text or image, or true for an input file it charges for",
+    )
+    default: bool = Field(
+        ...,
+        description="Whether a generation that leaves these inputs at their defaults pays this rate",
     )
 
 
@@ -1674,8 +1677,8 @@ class LibraryAsset(BaseModel):
     name: str | None
     url: str | None
     content_type: str | None
-    width: float | None = None
-    height: float | None = None
+    width: int | None = None
+    height: int | None = None
     duration: float | None = None
     caption: str | None = Field(
         ..., description="What the image shows, when it has been described"
@@ -1694,8 +1697,8 @@ class Asset(BaseModel):
     name: str | None
     url: str | None
     content_type: str | None
-    width: float | None = None
-    height: float | None = None
+    width: int | None = None
+    height: int | None = None
     duration: float | None = None
 
 
@@ -1751,14 +1754,14 @@ class BrandLogo(BaseModel):
         description="icon for a small mark, light for dark backgrounds, dark for light ones",
     )
     format: str | None
-    width: float | None
-    height: float | None
+    width: int | None
+    height: int | None
     url: str | None
 
 
 class Brand(BaseModel):
     object: Literal["brand"]
-    id: UUID = Field(
+    id: str = Field(
         ...,
         description="Send it as `Sandstorm-Brand` to work on this brand with a key made on another",
     )
@@ -1797,8 +1800,8 @@ class OfferSummary(BaseModel):
 class OfferVariantPhoto(BaseModel):
     id: str = Field(..., description="An asset id, usable as a media input")
     url: str | None
-    width: float | None
-    height: float | None
+    width: int | None
+    height: int | None
     orientation: str | None
     shot_type: str | None
     caption: str | None
@@ -1819,8 +1822,8 @@ class OfferVariant(BaseModel):
 class OfferPhoto(BaseModel):
     id: str = Field(..., description="An asset id, usable as a media input")
     url: str | None
-    width: float | None
-    height: float | None
+    width: int | None
+    height: int | None
     orientation: str | None
     shot_type: str | None
     caption: str | None