Cookbook · UltraGPT API

Cookbook

Task-oriented recipes that combine several features. Each one runs as-is with the official OpenAI Python SDK.

Reliable requests: fallbacks, retries, no double billing

Python
# Never lose a request and never pay twice: fallbacks + retries +
# an Idempotency-Key that makes a retry replay the first answer.
import os, uuid
from openai import OpenAI

client = OpenAI(base_url="https://api.ultragpt.pro/v1", api_key=os.environ["ULTRAGPT_API_KEY"],
                max_retries=4)  # SDK backs off on 429/5xx, honors retry-after

def ask(messages):
    return client.chat.completions.create(
        model="grok-4.7",
        messages=messages,
        extra_body={"models": ["gpt-6-astra"]},  # routed here if the first fails
        extra_headers={"Idempotency-Key": str(uuid.uuid4())},
    )

Structured extraction with a JSON schema

Python
# Extract typed data: strict JSON schema in, validated object out.
schema = {
    "name": "invoice",
    "strict": True,
    "schema": {
        "type": "object",
        "properties": {
            "vendor": {"type": "string"},
            "total": {"type": "number"},
            "due_date": {"type": "string"},
        },
        "required": ["vendor", "total", "due_date"],
        "additionalProperties": False,
    },
}
r = client.chat.completions.create(
    model="grok-4.7",
    messages=[{"role": "user", "content": invoice_text}],
    response_format={"type": "json_schema", "json_schema": schema},
    extra_body={"plugins": [{"id": "response-healing"}]},  # repairs broken JSON
)
data = json.loads(r.choices[0].message.content)

Charge your customers the exact cost

Python
# Bill your own customers: tag each request, then read the exact cost.
r = client.chat.completions.with_raw_response.create(
    model="grok-4.7",
    messages=messages,
    extra_body={"safety_identifier": hashed_customer_id},
)
generation_id = r.headers["x-ultragpt-generation-id"]

# Later (or in bulk, up to 1000 ids):
import httpx
costs = httpx.post("https://api.ultragpt.pro/v1/generations/lookup",
    headers={"Authorization": f"Bearer {os.environ['ULTRAGPT_API_KEY']}"},
    json={"ids": [generation_id]}).json()
print(costs["summary"]["total_cost"])  # USD actually billed

Retrieval: embeddings + rerank

Python
# Retrieval: embed, shortlist by cosine similarity, rerank, answer.
import numpy as np

def embed(texts):
    r = client.embeddings.create(model="qwen3-embedding-8b", input=texts)
    return np.array([d.embedding for d in r.data])

doc_vectors = embed(documents)                       # once, then store
q = embed([question])[0]
scores = doc_vectors @ q / (np.linalg.norm(doc_vectors, axis=1) * np.linalg.norm(q))
shortlist = [documents[i] for i in scores.argsort()[::-1][:20]]

ranked = httpx.post("https://api.ultragpt.pro/v1/rerank",
    headers={"Authorization": f"Bearer {os.environ['ULTRAGPT_API_KEY']}"},
    json={"model": "cohere-rerank-v3.5", "query": question,
          "documents": shortlist, "top_n": 4}).json()["results"]
context = "\n\n".join(shortlist[r["index"]] for r in ranked)

Large offline jobs with the Batch API

Python
# Thousands of prompts overnight at the batch discount.
import json
with open("requests.jsonl", "w") as f:
    for i, text in enumerate(texts):
        f.write(json.dumps({"custom_id": f"row-{i}", "method": "POST",
            "url": "/v1/chat/completions",
            "body": {"model": "grok-4.7",
                     "messages": [{"role": "user", "content": text}]}}) + "\n")

file = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch")
batch = client.batches.create(input_file_id=file.id,
    endpoint="/v1/chat/completions", completion_window="24h")
# Poll client.batches.retrieve(batch.id) (or use the batch webhook), then:
results = client.files.content(batch.output_file_id).text