همهٔ مدل‌ها و ابزارهای ساتاوس، با یک کلید API

# OpenAI style (all endpoints)
Authorization: Bearer sk-sat-...

# Anthropic style (also accepted everywhere)
x-api-key: sk-sat-...

client.chat.completions.create(
    model="anthropic/claude-sonnet-4.5",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "What is in this picture?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}},
    ]}],
)

# pip install openai
reply = client.responses.create(
    model="anthropic/claude-sonnet-4.5",
    store=False,
    instructions="You are a concise assistant.",
    input="Explain what a motion graphic is.",
)
print(reply.output_text)
# For tool loops, send the full input history plus output items and function_call_output.
# Stored conversations, previous_response_id and hosted tools are unavailable.

# 1) Ask for a price quote (nothing is charged)
curl https://sataveslabs.com/api/ai/generation/quote -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" -d '{
  "service": "ai:image", "model": "openai/gpt-image-1",
  "prompt": "A lighthouse at dawn, watercolor", "size": "1024x1024", "output_count": 1
}'
# -> {"ok": true, "data": {"quote_id": "...", "estimated_usd_micros": ..., "maximum_authorized_usd_micros": ...}}

# 2) Confirm it (add "accept_cost_estimate": true when the quote says requires_cost_estimate_acceptance)
curl -X POST https://sataveslabs.com/api/ai/generation/quotes/QUOTE_ID/confirm -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" -d '{}'

# 3) Generate with the same parameters and the quote id
curl https://sataveslabs.com/api/ai/image -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" -d '{
  "model": "openai/gpt-image-1", "prompt": "A lighthouse at dawn, watercolor",
  "size": "1024x1024", "output_count": 1, "quote_id": "QUOTE_ID"
}'
# -> {"ok": true, "data": {"image_url": "/api/ai/images/.../file", "billing": {...}}}

# Quote and confirm exactly like images, with "service": "ai:video"
curl https://sataveslabs.com/api/ai/generation/quote -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" -d '{
  "service": "ai:video", "model": "google/veo-3.1-fast", "prompt": "Drone shot over a desert at sunset",
  "size": "1280x720", "aspect_ratio": "16:9", "duration_seconds": 8
}'
curl -X POST https://sataveslabs.com/api/ai/generation/quotes/QUOTE_ID/confirm -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" -d '{}'

curl https://sataveslabs.com/api/ai/video -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" -d '{
  "model": "google/veo-3.1-fast", "prompt": "Drone shot over a desert at sunset",
  "size": "1280x720", "aspect_ratio": "16:9", "duration_seconds": 8, "quote_id": "QUOTE_ID"
}'
# -> {"data": {"task_id": "...", "status": "processing"}}

# Poll, then download
curl https://sataveslabs.com/api/ai/video/status/TASK_ID -H "Authorization: Bearer $SATAVES_API_KEY"
curl -o video.mp4 https://sataveslabs.com/api/ai/video/content/TASK_ID -H "Authorization: Bearer $SATAVES_API_KEY"

# Text to speech: list voices, then synthesize
curl "https://sataveslabs.com/api/ai/tts/model-voices?model=gemini-2.5-flash-tts" -H "Authorization: Bearer $SATAVES_API_KEY"
curl https://sataveslabs.com/api/ai/tts -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "gemini-2.5-flash-tts", "text": "Hello from Sataves!", "voice": "Kore"}'
# -> {"data": {"audio_b64": "...", "format": "audio/wav", "audio_url": "/api/ai/audio/..."}}

# Speech to text (multipart upload)
curl https://sataveslabs.com/api/ai/transcribe -H "Authorization: Bearer $SATAVES_API_KEY" \
  -F "file=@meeting.mp3" -F "model=whisper-1"
# -> {"ok": true, "data": {"text": "...", "billing": {...}}}

# OCR on an image or PDF (any vision-capable model)
curl https://sataveslabs.com/api/ai/ocr -H "Authorization: Bearer $SATAVES_API_KEY" -F "file=@invoice.pdf" -F "model=anthropic/claude-sonnet-4.5"

curl https://sataveslabs.com/api/ai/summarize -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" \
  -d '{"text": "...long text...", "model": "openai/gpt-4.1-mini", "format": "key_points"}'

curl https://sataveslabs.com/api/ai/translate -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" \
  -d '{"text": "Good morning", "target": "Persian"}'

curl https://sataveslabs.com/api/ai/rewrite -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" \
  -d '{"text": "...", "model": "openai/gpt-4.1-mini"}'

# Music is generated into a private studio project
curl https://sataveslabs.com/api/studio/projects -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" \
  -d '{"title": "API music", "manifest": {"schema_version": 1, "assets": []}}'
# -> {"ok": true, "project": {"id": "PROJECT_ID", ...}}

curl https://sataveslabs.com/api/studio/projects/PROJECT_ID/creative/music -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "google/lyria-3-clip-preview", "prompt": "Calm lo-fi beat with soft piano", "instrumental": true}'

# The new track appears in the project's media bin
curl https://sataveslabs.com/api/studio/projects/PROJECT_ID/assets -H "Authorization: Bearer $SATAVES_API_KEY"

# Optional for text services, TTS, OCR and studio generation: lock the price first
curl https://sataveslabs.com/api/credits/studio/quote -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" \
  -d '{"path": "/ai/tts", "payload": {"model": "gemini-2.5-flash-tts", "text": "Hello", "voice": "Kore"}}'
curl -X POST https://sataveslabs.com/api/credits/studio/quotes/QUOTE_ID/confirm -H "Authorization: Bearer $SATAVES_API_KEY"

# Send the identical request with the quote headers
curl https://sataveslabs.com/api/ai/tts -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" \
  -H "X-Studio-Request: 1" -H "X-Studio-Quote-Id: QUOTE_ID" \
  -d '{"model": "gemini-2.5-flash-tts", "text": "Hello", "voice": "Kore"}'

import os, time, requests
root = "https://sataveslabs.com"
headers = {"Authorization": "Bearer " + os.environ["SATAVES_API_KEY"]}
def call(method, path, **kwargs):
    response = requests.request(method, root + path, headers=headers, timeout=300, **kwargs)
    response.raise_for_status()
    return response.json()["data"]
spec = {
    "mode": "template", "title": "Ideas in motion", "subtitle": "Your brand, animated",
    "primary": "#8b5cf6", "secondary": "#f472b6", "aspect": "16:9",
    "seconds": 4, "position": "bottom"
}
quote = call("POST", "/api/ai/motion/quote", json=spec)
# Local template is free. For mode=ai, review the returned quote then explicitly confirm it:
# call("POST", "/api/ai/generation/quotes/" + quote["quote"]["quote_id"] + "/confirm",
#      json={"accept_cost_estimate": True})
run = call("POST", "/api/ai/motion/generate", json={"id": quote["id"]})
while run["state"] not in ("completed", "failed", "render_failed", "uncertain"):
    time.sleep(5)
    run = call("GET", "/api/ai/motion/runs/" + run["id"])
if run["state"] == "completed":
    gif = requests.get(root + run["outputs"]["gif"], headers=headers, timeout=60)
    gif.raise_for_status()
    open("motion.gif", "wb").write(gif.content)
# An uncertain submission must never be blindly retried. Retry only local rendering when appropriate.

# Long tasks (video translation, subtitles, downloads, conversions) run as jobs
curl https://sataveslabs.com/api/jobs -H "Authorization: Bearer $SATAVES_API_KEY"                      # your jobs
curl https://sataveslabs.com/api/jobs/JOB_ID -H "Authorization: Bearer $SATAVES_API_KEY"               # status and progress
curl -o result.zip https://sataveslabs.com/api/jobs/JOB_ID/file -H "Authorization: Bearer $SATAVES_API_KEY"

# Download from a link
curl https://sataveslabs.com/api/downloads/formats -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" -d '{"url": "https://www.youtube.com/watch?v=..."}'
curl https://sataveslabs.com/api/downloads/jobs -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" -d '{"url": "https://www.youtube.com/watch?v=...", "fmt": "best"}'
curl https://sataveslabs.com/api/downloads/jobs/JOB_ID -H "Authorization: Bearer $SATAVES_API_KEY"
curl -o video.mp4 https://sataveslabs.com/api/downloads/jobs/JOB_ID/file -H "Authorization: Bearer $SATAVES_API_KEY"

# Discover featured resources; this does not run inference
curl https://sataveslabs.com/v1/hub/catalog

# Resolve a supported resource and review availability first
curl https://sataveslabs.com/api/ai/hub/resolve -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" -d '{"url":"https://civitai.com/models/4201"}'

# Save the exact Civitai inputs you intend to submit
printf '%s' '{"model_name":"MODEL_NAME","model_urn":"VERIFIED_AIR_URN","prompt":"portrait, soft light"}' > civitai-input.json
curl https://sataveslabs.com/api/ai/hub/civitai/estimate -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" -d @civitai-input.json
# Review quote_id, estimated_micros, maximum_micros, expires_at and can_start.
# Amounts are micro-USD: 1000000 = $1. A quote reserves nothing yet.
# After approving the displayed price, set SATAVES_HUB_QUOTE_ID to that quote_id.
# jq is required. Keep the quoted inputs unchanged; reuse the retry key after a timeout.
jq --arg q "$SATAVES_HUB_QUOTE_ID" '. + {quote_id:$q,accept_cost_estimate:true,idempotency_key:"civitai-001"}' civitai-input.json > civitai-run.json
curl https://sataveslabs.com/api/ai/hub/civitai/runs -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" -d @civitai-run.json

# Hugging Face: discover the real endpoint, parameter names and schema hash
curl https://sataveslabs.com/api/ai/hub/research/discover -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" -d '{"kind":"space","repo_id":"SPACE_OWNER/SPACE_NAME"}'
printf '%s' '{"kind":"space","repo_id":"SPACE_OWNER/SPACE_NAME","endpoint":"ENDPOINT_FROM_DISCOVER","values":{"INPUT_NAME_FROM_DISCOVER":"a red fox"},"options":{},"schema_hash":"SCHEMA_HASH_FROM_DISCOVER","consent":true}' > space-input.json
curl https://sataveslabs.com/api/ai/hub/research/quote -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" -d @space-input.json
# Review this quote, then set SATAVES_HUB_QUOTE_ID to its quote_id.
jq --arg q "$SATAVES_HUB_QUOTE_ID" '. + {quote_id:$q,accept_cost_estimate:true,idempotency_key:"space-001"}' space-input.json > space-run.json
curl https://sataveslabs.com/api/ai/hub/research/runs -H "Authorization: Bearer $SATAVES_API_KEY" -H "Content-Type: application/json" -d @space-run.json

# Poll and download using the same account/key
curl https://sataveslabs.com/api/jobs/JOB_ID -H "Authorization: Bearer $SATAVES_API_KEY"
curl -O https://sataveslabs.com/api/ai/hub/runs/JOB_ID/files/FILE_NAME -H "Authorization: Bearer $SATAVES_API_KEY"
# Final result.billing reports charged_micros, refunded_micros,
# price_estimated and cost_basis. Async API usage updates after settlement.

import os, time, requests
root = "https://sataveslabs.com"
headers = {"Authorization": "Bearer " + os.environ["SATAVES_API_KEY"]}
def call(method, path, **kwargs):
    request_headers = kwargs.pop("headers", headers)
    r = requests.request(method, root + path, headers=request_headers, timeout=60, **kwargs)
    r.raise_for_status()
    result = r.json()
    if not result["ok"]:
        raise RuntimeError(result["data"].get("error", "request_failed"))
    return result["data"]

offers = call("GET", "/api/numbers/offers", params={"platform": "telegram"})
if offers.get("partial") or not offers["items"]:
    raise RuntimeError("Catalog warming or out of stock; retry browsing later")
offer = offers["items"][0]  # Select the country/operator you actually want.
assert offer["billing_currency"] == "USD_CREDIT"
price = offer["price_usd_micros"]
# Set a deliberate budget before running. This example buys a real number.
assert price <= int(os.environ["MAX_NUMBER_PRICE_MICROS"])
# Save this unique purchase id; reuse it and the SAME body on network retries.
purchase_id = os.environ["NUMBER_PURCHASE_ID"]  # e.g. telegram-order-20261025-001
body = {"pid": offer["pid"], "sid": offer["sid"], "platform": "telegram", "price": price}
purchase = call("POST", "/api/numbers/purchase", json=body,
                headers={**headers, "Idempotency-Key": purchase_id})
key = purchase["order"]["key"]
for _ in range(60):
    status = call("GET", "/api/numbers/orders/" + key + "/status")
    if status.get("code") or status["state"] in ("completed", "canceled", "banned"):
        print(status)  # code, sms text/sender, expiry and state when available
        break
    time.sleep(5)
# Actions, when appropriate (each can be refused by the provider):
# call("POST", "/api/numbers/orders/" + key + "/finish")
# call("POST", "/api/numbers/orders/" + key + "/cancel")
# call("POST", "/api/numbers/orders/" + key + "/ban")

curl https://sataveslabs.com/v1/account -H "Authorization: Bearer $SATAVES_API_KEY"     # balance, this key, rate limits
curl "https://sataveslabs.com/v1/usage?days=7&key=current" -H "Authorization: Bearer $SATAVES_API_KEY"   # requests and charges
curl https://sataveslabs.com/v1/pricing                     # price list (public)
curl https://sataveslabs.com/v1/status                      # API status and model counts (public)

// /v1/chat/completions, /v1/embeddings and other /v1 endpoints (OpenAI shape)
{"error": {"message": "Your balance is too low for this request.", "type": "insufficient_quota", "code": "insufficient_balance"}}

// /v1/messages (Anthropic shape)
{"type": "error", "error": {"type": "billing_error", "message": "Your balance is too low for this request."}}

// /api/... website endpoints
{"ok": false, "error": "generation_quote_required", "detail": "generation_quote_required"}