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 billedRetrieval: 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