cli-302ai 1.0.2b1__py3-none-any.whl

ai302/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.7"

ai302/__main__.py

@@ -0,0 +1,14 @@
+import os
+import sys
+
+os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+if hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8")
+
+from .cli.app import app
+
+
+if __name__ == "__main__":
+    app(prog_name="302ai")

ai302/api/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+__all__ = ["upload_file"]
+
+from .file import upload_file

ai302/api/file.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import mimetypes
+import sys
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from .http_client import AI302ApiError
+
+
+def upload_file(
+    *,
+    url: str,
+    file_path: str,
+    prefix: str = "img",
+    timeout_s: float = 60.0,
+    retries: int = 2,
+) -> dict[str, Any]:
+    path = Path(file_path)
+    content_type, _enc = mimetypes.guess_type(str(path))
+
+    return _upload_bytes(
+        url=url,
+        filename=path.name,
+        content=path.read_bytes(),
+        content_type=content_type or "application/octet-stream",
+        prefix=prefix,
+        timeout_s=timeout_s,
+        retries=retries,
+    )
+
+
+def delete_uploaded_file(
+    *,
+    url: str,
+    file_path: str,
+    timeout_s: float = 60.0,
+    retries: int = 2,
+) -> dict[str, Any]:
+    for attempt in range(retries + 1):
+        try:
+            with httpx.Client(timeout=timeout_s) as client:
+                resp = client.request("DELETE", url, json={"file_path": file_path})
+                if 200 <= resp.status_code < 300:
+                    payload = resp.json()
+                    if not isinstance(payload, dict):
+                        raise AI302ApiError("delete failed: invalid response", status_code=resp.status_code)
+                    return payload
+
+                payload: Any = None
+                try:
+                    payload = resp.json()
+                except Exception:
+                    payload = None
+
+                msg = "unknown error"
+                if isinstance(payload, dict) and isinstance(payload.get("msg"), str) and payload.get("msg").strip():
+                    msg = payload.get("msg").strip()
+
+                retryable = resp.status_code >= 500
+                if attempt < retries and retryable:
+                    continue
+                raise AI302ApiError(msg, status_code=resp.status_code, retryable=retryable)
+
+        except Exception as e:  # noqa: BLE001
+            if attempt < retries and isinstance(e, (httpx.TimeoutException, httpx.NetworkError)):
+                continue
+            if isinstance(e, AI302ApiError):
+                raise
+            if isinstance(e, httpx.TimeoutException):
+                raise AI302ApiError("request timeout", retryable=True) from e
+            if isinstance(e, httpx.NetworkError):
+                raise AI302ApiError("network error", retryable=True) from e
+            raise AI302ApiError("unknown error") from e
+
+    raise AI302ApiError("unknown error")
+
+
+def upload_file_from_url(
+    *,
+    url: str,
+    file_url: str,
+    prefix: str = "img",
+    timeout_s: float = 60.0,
+    retries: int = 2,
+    debug: bool = False,
+    debug_download_to: str | None = None,
+) -> dict[str, Any]:
+    import sys
+    for attempt in range(retries + 1):
+        try:
+            if debug:
+                print(f"[ai302:file:upload-url] attempt={attempt} downloading {file_url}", file=sys.stderr)
+            with httpx.Client(timeout=timeout_s, follow_redirects=True) as client:
+                resp = client.get(file_url, headers={"Accept-Encoding": "identity"})
+                if debug:
+                    size = int(resp.headers.get("content-length") or 0)
+                    print(
+                        f"[ai302:file:upload-url] download status={resp.status_code} content_type={resp.headers.get('content-type')} content_length={size}",
+                        file=__import__("sys").stderr,
+                    )
+                if 200 <= resp.status_code < 300:
+                    content_type = resp.headers.get("content-type")
+                    orig = Path(httpx.URL(file_url).path).name
+                    suffix = Path(orig).suffix
+                    filename = f"{__import__('uuid').uuid4().hex}{suffix}" if suffix else __import__('uuid').uuid4().hex
+                    if debug:
+                        print(
+                            f"[ai302:file:upload-url] uploading filename={filename} bytes={len(resp.content)}",
+                            file=__import__("sys").stderr,
+                        )
+
+                    if debug_download_to is not None:
+                        Path(debug_download_to).write_bytes(resp.content)
+                        if debug:
+                            print(
+                                f"[ai302:file:upload-url] saved download to {debug_download_to}",
+                                file=__import__("sys").stderr,
+                            )
+                    return _upload_bytes(
+                        url=url,
+                        filename=filename,
+                        content=resp.content,
+                        content_type=content_type or "application/octet-stream",
+                        prefix=prefix,
+                        timeout_s=timeout_s,
+                        retries=retries,
+                        debug=debug,
+                    )
+
+                payload: Any = None
+                try:
+                    payload = resp.json()
+                except Exception:
+                    payload = None
+
+                msg = "download failed"
+                if isinstance(payload, dict) and isinstance(payload.get("msg"), str) and payload.get("msg").strip():
+                    msg = payload.get("msg").strip()
+
+                retryable = resp.status_code >= 500
+                if attempt < retries and retryable:
+                    continue
+                raise AI302ApiError(msg, status_code=resp.status_code, retryable=retryable)
+
+        except Exception as e:  # noqa: BLE001
+            if debug:
+                print(f"[ai302:file:upload-url] exception: {type(e).__name__}: {e}", file=sys.stderr)
+            if attempt < retries and isinstance(e, (httpx.TimeoutException, httpx.NetworkError)):
+                continue
+            if isinstance(e, AI302ApiError):
+                raise
+            if isinstance(e, httpx.TimeoutException):
+                raise AI302ApiError("request timeout", retryable=True) from e
+            if isinstance(e, httpx.NetworkError):
+                raise AI302ApiError("network error", retryable=True) from e
+            raise AI302ApiError(f"unknown error: {type(e).__name__}: {e}") from e
+
+    raise AI302ApiError("unknown error")
+
+
+def _upload_bytes(
+    *,
+    url: str,
+    filename: str,
+    content: bytes,
+    content_type: str,
+    prefix: str,
+    timeout_s: float,
+    retries: int,
+    debug: bool = False,
+) -> dict[str, Any]:
+
+    data: dict[str, str] = {"prefix": prefix, "file_name": filename, "url": "", "base64_data": ""}
+
+    for attempt in range(retries + 1):
+        try:
+            with httpx.Client(timeout=timeout_s) as client:
+                files = {"file": (filename, content, content_type)}
+
+                resp = client.post(url, files=files, data=data, timeout=60)
+                if debug:
+                    print(
+                        f"[ai302:file:upload-url] upload status={resp.status_code}",
+                        file=__import__("sys").stderr,
+                    )
+                if 200 <= resp.status_code < 300:
+                    payload = resp.json()
+                    if not isinstance(payload, dict):
+                        raise AI302ApiError("upload failed: invalid response", status_code=resp.status_code)
+
+                    if payload.get("code") != 0:
+                        msg = payload.get("msg") if isinstance(payload.get("msg"), str) else "upload failed"
+                        raise AI302ApiError(msg, status_code=resp.status_code, retryable=False)
+
+                    data = payload.get("data")
+                    uploaded_url = data.get("url") if isinstance(data, dict) else None
+                    if not isinstance(uploaded_url, str) or not uploaded_url.strip():
+                        raise AI302ApiError("upload failed: missing url", status_code=resp.status_code)
+
+                    return payload
+
+                payload: Any = None
+                try:
+                    payload = resp.json()
+                except Exception:
+                    payload = None
+
+                msg = "unknown error"
+                if isinstance(payload, dict) and isinstance(payload.get("msg"), str) and payload.get("msg").strip():
+                    msg = payload.get("msg").strip()
+
+                retryable = resp.status_code >= 500
+                if attempt < retries and retryable:
+                    continue
+                raise AI302ApiError(msg, status_code=resp.status_code, retryable=retryable)
+
+        except Exception as e:  # noqa: BLE001
+            if attempt < retries and isinstance(e, (httpx.TimeoutException, httpx.NetworkError)):
+                continue
+            if isinstance(e, AI302ApiError):
+                raise
+            if isinstance(e, httpx.TimeoutException):
+                raise AI302ApiError("request timeout", retryable=True) from e
+            if isinstance(e, httpx.NetworkError):
+                raise AI302ApiError("network error", retryable=True) from e
+            raise AI302ApiError("unknown error") from e
+
+    raise AI302ApiError("unknown error")

ai302/api/http_client.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from ..core.errors import extract_error_message
+
+
+DEFAULT_BASE_URL = os.environ.get("AI302_BASE_URL", "https://api.302ai.com")
+
+
+class AI302ApiError(RuntimeError):
+    def __init__(self, message: str, *, status_code: int | None = None, retryable: bool = False):
+        super().__init__(message)
+        self.status_code = status_code
+        self.retryable = retryable
+
+
+def _auth_header(api_key: str) -> dict[str, str]:
+    return {"Authorization": f"Bearer {api_key}"}
+
+
+def _should_retry(resp: httpx.Response | None, exc: Exception | None) -> bool:
+    if resp is not None:
+        if resp.status_code == 401:
+            return False
+        return resp.status_code >= 500 or resp.status_code in (408, 409, 429)
+    return isinstance(exc, (httpx.TimeoutException, httpx.NetworkError))
+
+
+def request_json(
+    *,
+    method: str,
+    url: str,
+    api_key: str,
+    params: dict[str, Any] | list[tuple[str, str]] | None = None,
+    json_body: dict[str, Any] | None = None,
+    timeout_s: float = 60.0,
+    retries: int = 2,
+) -> tuple[dict[str, Any], httpx.Headers]:
+    with httpx.Client(timeout=timeout_s, headers=_auth_header(api_key)) as client:
+        for attempt in range(retries + 1):
+            try:
+                resp = client.request(method, url, params=params, json=json_body)
+                if 200 <= resp.status_code < 300:
+                    data = resp.json()
+                    if isinstance(data, dict):
+                        return data, resp.headers
+                    raise AI302ApiError("unknown error", status_code=resp.status_code)
+
+                payload: Any = None
+                try:
+                    payload = resp.json()
+                except Exception:
+                    payload = None
+
+                msg = extract_error_message(payload)
+                if attempt < retries and _should_retry(resp, None):
+                    continue
+                raise AI302ApiError(msg, status_code=resp.status_code, retryable=_should_retry(resp, None))
+
+            except Exception as e:  # noqa: BLE001
+                if attempt < retries and _should_retry(None, e):
+                    continue
+                if isinstance(e, AI302ApiError):
+                    raise
+                if isinstance(e, httpx.TimeoutException):
+                    raise AI302ApiError("request timeout", retryable=True) from e
+                if isinstance(e, httpx.NetworkError):
+                    raise AI302ApiError("network error", retryable=True) from e
+                raise AI302ApiError("unknown error") from e
+
+    raise AI302ApiError("unknown error")

ai302/api/image.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .http_client import DEFAULT_BASE_URL, request_json
+
+
+def generate_image_sync(
+    *,
+    api_key: str,
+    model: str,
+    prompt: str,
+    height: int | None = None,
+    width: int | None = None,
+    negative_prompt: str | None = None,
+    aspect_ratio: str | None = None,
+    output_format: str | None = None,
+    image: str | list[str] | None = None,
+    mask_image: str | None = None,
+    extra: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {"model": model, "prompt": prompt}
+    if height is not None:
+        body["height"] = height
+    if width is not None:
+        body["width"] = width
+    if negative_prompt is not None:
+        body["negative_prompt"] = negative_prompt
+    if aspect_ratio is not None:
+        body["aspect_ratio"] = aspect_ratio
+    if output_format is not None:
+        body["output_format"] = output_format
+    if image is not None:
+        body["image"] = image
+    if mask_image is not None:
+        body["mask_image"] = mask_image
+    if extra:
+        body.update(extra)
+
+    data, headers = request_json(
+        method="POST",
+        url=f"{DEFAULT_BASE_URL}/302/v2/image/generate",
+        api_key=api_key,
+        json_body=body,
+        timeout_s=180.0,
+        retries=1,
+    )
+    request_id = headers.get("request-id")
+    if request_id:
+        data["request_id"] = request_id
+    return data
+
+
+def create_image_task(
+    *,
+    api_key: str,
+    model: str,
+    prompt: str,
+    height: int | None = None,
+    width: int | None = None,
+    negative_prompt: str | None = None,
+    aspect_ratio: str | None = None,
+    output_format: str | None = None,
+    image: str | list[str] | None = None,
+    mask_image: str | None = None,
+    run_async: bool | None = None,
+    webhook: str | None = None,
+    extra: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {"model": model, "prompt": prompt}
+    if height is not None:
+        body["height"] = height
+    if width is not None:
+        body["width"] = width
+    if negative_prompt is not None:
+        body["negative_prompt"] = negative_prompt
+    if aspect_ratio is not None:
+        body["aspect_ratio"] = aspect_ratio
+    if output_format is not None:
+        body["output_format"] = output_format
+    if image is not None:
+        body["image"] = image
+    if mask_image is not None:
+        body["mask_image"] = mask_image
+    if extra:
+        body.update(extra)
+
+    params: dict[str, Any] = {}
+    if run_async is not None:
+        params["run_async"] = run_async
+    if webhook:
+        params["webhook"] = webhook
+
+    data, headers = request_json(
+        method="POST",
+        url=f"{DEFAULT_BASE_URL}/302/v2/image/generate",
+        api_key=api_key,
+        params=params or None,
+        json_body=body,
+        timeout_s=180.0,
+        retries=1,
+    )
+    request_id = headers.get("request-id")
+    if request_id:
+        data["request_id"] = request_id
+    return data
+
+
+def fetch_image_task(*, api_key: str, task_id: str) -> dict[str, Any]:
+    data, _headers = request_json(
+        method="GET",
+        url=f"{DEFAULT_BASE_URL}/302/v2/image/fetch/{task_id}",
+        api_key=api_key,
+        timeout_s=60.0,
+        retries=2,
+    )
+    return data

ai302/api/record.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .http_client import DEFAULT_BASE_URL, request_json
+
+
+def get_record(*, api_key: str, request_id: str) -> dict[str, Any]:
+    data, _headers = request_json(
+        method="GET",
+        url=f"{DEFAULT_BASE_URL}/dashboard/record/{request_id}",
+        api_key=api_key,
+        timeout_s=60.0,
+        retries=2,
+    )
+    return data

ai302/api/search.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .http_client import DEFAULT_BASE_URL, request_json
+
+API_PATH = "/302/general/search"
+
+
+def search(
+    *,
+    api_key: str,
+    query: str,
+    provider: str,
+    max_results: int = 5,
+    category: str | None = None,
+    time_range: str | None = None,
+    include_images: bool = True,
+    include_domains: list[str] | None = None,
+    exclude_domains: list[str] | None = None,
+    start_crawl_date: str | None = None,
+    end_crawl_date: str | None = None,
+    start_published_date: str | None = None,
+    end_published_date: str | None = None,
+    crawl_results: int | None = None,
+    include_row_content: bool | None = None,
+    page: int | None = None,
+    max_tokens_per_page: int | None = None,
+    country: str | None = None,
+) -> tuple[dict[str, Any], str | None]:
+    body: dict[str, Any] = {
+        "query": query,
+        "provider": provider,
+        "max_results": max_results,
+        "include_images": include_images,
+    }
+    if category is not None:
+        body["category"] = category
+    if time_range is not None:
+        body["time_range"] = time_range
+    if include_domains is not None:
+        body["include_domains"] = include_domains
+    if exclude_domains is not None:
+        body["exclude_domains"] = exclude_domains
+    if start_crawl_date is not None:
+        body["startCrawlDate"] = start_crawl_date
+    if end_crawl_date is not None:
+        body["endCrawlDate"] = end_crawl_date
+    if start_published_date is not None:
+        body["startPublishedDate"] = start_published_date
+    if end_published_date is not None:
+        body["endPublishedDate"] = end_published_date
+    if crawl_results is not None:
+        body["crawl_results"] = crawl_results
+    if include_row_content is not None:
+        body["includeRowContent"] = include_row_content
+    if page is not None:
+        body["page"] = page
+    if max_tokens_per_page is not None:
+        body["max_tokens_per_page"] = max_tokens_per_page
+    if country is not None:
+        body["country"] = country
+
+    data, headers = request_json(
+        method="POST",
+        url=f"{DEFAULT_BASE_URL}{API_PATH}",
+        api_key=api_key,
+        json_body=body,
+        timeout_s=30.0,
+        retries=2,
+    )
+    request_id = headers.get("request-id")
+    return data, request_id

ai302/api/sfx.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .http_client import DEFAULT_BASE_URL, request_json
+
+
+def create_sfx_task(
+    *,
+    api_key: str,
+    prompt: str,
+    duration: float,
+    external_task_id: str | None = None,
+    callback: str | None = None,
+) -> tuple[dict[str, Any], str | None]:
+    body: dict[str, Any] = {"prompt": prompt, "duration": duration, "type": "text-to-audio"}
+    if external_task_id is not None:
+        body["external_task_id"] = external_task_id
+    if callback is not None:
+        body["callback"] = callback
+
+    data, headers = request_json(
+        method="POST",
+        url=f"{DEFAULT_BASE_URL}/klingai/v1/audio/text-to-audio",
+        api_key=api_key,
+        json_body=body,
+        timeout_s=60.0,
+        retries=2,
+    )
+    request_id = headers.get("request-id")
+    return data, request_id
+
+
+def fetch_sfx_task(*, api_key: str, task_id: str) -> dict[str, Any]:
+    data, _headers = request_json(
+        method="GET",
+        url=f"{DEFAULT_BASE_URL}/klingai/v1/audio/video-to-audio/{task_id}",
+        api_key=api_key,
+        timeout_s=60.0,
+        retries=2,
+    )
+    return data