AceDataCloud Python SDK
Official Python client for the AceDataCloud API.
Installation
pip install acedatacloud
Quick Start
from acedatacloud import AceDataCloud
client = AceDataCloud(api_token="your-token")
# OpenAI-compatible chat completions
response = client.openai.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello!"}],
)
print(response["choices"][0]["message"]["content"])
# Streaming
for chunk in client.openai.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Tell me a story"}],
stream=True,
):
print(chunk.get("choices", [{}])[0].get("delta", {}).get("content", ""), end="")
Async Usage
import asyncio
from acedatacloud import AsyncAceDataCloud
async def main():
client = AsyncAceDataCloud(api_token="your-token")
result = await client.search.google(query="Python SDK")
print(result)
await client.close()
asyncio.run(main())
Resources
| Resource | Description |
|---|---|
client.openai |
OpenAI-compatible chat completions and responses |
client.chat |
Native chat messages |
client.images |
Image generation (Flux, Seedream, Nano Banana, etc.) |
client.audio |
Music generation (Suno) |
client.video |
Video generation (Luma, Sora, Veo, etc.) |
client.search |
Web search (Google SERP) |
client.face |
Face analysis & transformation (swap, beautify, age, cartoon) |
client.shorturl |
Short URL creation |
client.tasks |
Cross-service async task polling |
client.files |
File uploads |
client.platform |
Applications, credentials, models management |
Native Claude Messages
Thinking and output configuration are passed through without SDK model-specific
enum or combination checks. The selected model determines which values it accepts.
For the beta display: "updates" mode, set the required header on a dedicated
client (client headers apply to every request):
with AceDataCloud(
api_token="your-token",
headers={"anthropic-beta": "thinking-display-updates-2026-08-18"},
) as client:
response = client.chat.messages.create(
model="claude-sonnet-5-5",
messages=[{"role": "user", "content": "Explain this code."}],
thinking={"type": "adaptive", "display": "updates"},
output_config={"effort": "high"},
)
AsyncAceDataCloud accepts the same header and fields. Streaming and
client.chat.messages.count_tokens(...) also preserve thinking configuration.
Parameter pass-through does not guarantee model support; API errors are returned
through the SDK's normal error handling.
OpenAI Embeddings
result = client.openai.embeddings.create(
model="text-embedding-3-small",
input="The food was delicious and the waiter...",
)
Supported models are text-embedding-3-small and text-embedding-3-large.
text-embedding-ada-002 is no longer available. When migrating an existing index,
regenerate its vectors and rebuild the index; do not mix old and new model vectors.
Image Generation (with Task Polling)
# Default provider (nano-banana)
task = client.images.generate(prompt="A sunset over mountains")
result = task.wait() # polls until complete
print(result["image_url"])
# Use a specific provider
flux_task = client.images.generate(prompt="A sunset over mountains", provider="flux")
Nano Banana 2.1
Select model="nano-banana-2.1" explicitly for generation or editing at
1K, 2K, or 4K. Omitting model still uses nano-banana; there is no
nano-banana-2.1:official variant.
task = client.nano_banana.generate(
action="generate",
model="nano-banana-2.1",
prompt="A blue ceramic vase on a cream background",
resolution="2K",
aspect_ratio="1:1",
)
task.wait()
image_urls = task.urls()
edit_task = client.nano_banana.generate(
action="edit",
model="nano-banana-2.1",
prompt="Change the vase to green; preserve the background",
image_urls=image_urls,
resolution="4K",
)
edit_task.wait()
AsyncAceDataCloud exposes the same parameters (await generate and wait).
The public model ID also works with client.openai.images.generate(...) and
client.openai.images.edit(...); those use the OpenAI-compatible fields
(image for editing) and return response dictionaries, not task handles.
Multi-Provider Support
Image, video, and audio resources support a provider parameter to switch between services:
# Video — default is 'sora'
client.video.generate(prompt="A cat playing piano", provider="kling")
client.video.generate(prompt="Ocean waves", provider="luma")
# Audio — default is 'suno'
client.audio.generate(prompt="A jazz song", provider="producer")
Available providers:
| Resource | Providers |
|---|---|
client.images |
nano-banana (default), flux, seedream |
client.video |
sora (default), luma, veo, kling, hailuo, seedance, wan, pika, pixverse |
client.audio |
suno (default), producer, fish |
Error Handling
from acedatacloud import AceDataCloud, AuthenticationError, RateLimitError
client = AceDataCloud(api_token="your-token")
try:
client.search.google(query="test")
except AuthenticationError:
print("Invalid or expired token")
except RateLimitError:
print("Too many requests, slow down")
Configuration
client = AceDataCloud(
api_token="your-token",
base_url="https://x402.acedata.cloud", # API gateway (default)
platform_base_url="https://platform.acedata.cloud", # Management plane
timeout=300.0, # Request timeout in seconds
max_retries=2, # Retry count for transient errors
)
The token can also be set via the ACEDATACLOUD_API_TOKEN environment variable.
Paying with X402 Instead of a Bearer Token
The SDK supports a pluggable payment_handler that is invoked when the
API returns 402 Payment Required. Any callable (or async callable)
that returns the required headers is accepted:
from acedatacloud import AceDataCloud, PaymentHandlerContext, PaymentHandlerResult
def my_payment_handler(ctx: PaymentHandlerContext) -> PaymentHandlerResult:
# ctx["accepts"] is the list of payment requirements returned by the server.
# Your job: sign the preferred one and return the retry header.
x_payment = sign_and_encode(ctx["accepts"]) # your implementation
return {"headers": {"X-Payment": x_payment}}
client = AceDataCloud(payment_handler=my_payment_handler)
# Normal SDK calls — the handler is only invoked when the server returns 402.
result = client.openai.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hi"}],
)
The AsyncAceDataCloud client accepts either a synchronous or asynchronous
handler. For a ready-made signer, install acedatacloud-x402 and pass its
handler directly:
from acedatacloud import AceDataCloud
from acedatacloud_x402 import EVMAccountSigner, create_x402_payment_handler
client = AceDataCloud(
payment_handler=create_x402_payment_handler(
network="base",
evm_signer=EVMAccountSigner.from_private_key("0x..."),
prefer_scheme="upto",
)
)
See AceDataCloud/X402Client for
Base, Solana, and SKALE setup details.
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for acedatacloud 2026.10.9.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| acedatacloud-2026.10.9.1.tar.gz | 50.0 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| acedatacloud-2026.10.9.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 110.4 kB
Release files / acedatacloud-2026.10.9.1.tar.gz
| Download URL | acedatacloud-2026.10.9.1.tar.gz |
|---|---|
| Size | 50.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6384fdb4adfe775760910cbd69d8ef138764fdd920dac260047c418d03cefd83
|
|
BLAKE2b-256 checksum How to use checksums |
eee6ebb3d9413b3de3c0bc9bd0d7c5140790947aec62b5ef60b770e18a91e93f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / acedatacloud-2026.10.9.1-py3-none-any.whl
| Download URL | acedatacloud-2026.10.9.1-py3-none-any.whl |
|---|---|
| Size | 60.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
52198fab8f2358a7fb65a6aa87460765fea4c6b18efeba401deb4df00eef0e14
|
|
BLAKE2b-256 checksum How to use checksums |
83dc63c42f0aa6c203bd6c6d022aebbf82e5db9750275208fee68e46fde54a86
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for acedatacloud 2026.10.9.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
