Nexevo.aiNexevo.ai

Kern-API

Dialogabschlüsse

POST an /v1/chat/completions unter Verwendung des OpenAI-Standardnachrichtenformats. Verwenden Sie model=nexevo/balanced und wir leiten basierend auf Ihrer Frage automatisch an den am besten geeigneten Upstream weiter. Standardparameter wie Temperature / max_tokens / top_p / stop werden ebenfalls unterstützt.

python
resp = client.chat.completions.create(
    model="nexevo/balanced",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user",   "content": "Explain quantum entanglement"},
    ],
    temperature=0.7,
    max_tokens=500,
)
print(resp.choices[0].message.content)
Parameters
modelstringRequiredAufzurufende Modell-ID, z. B. gpt-4o / claude-opus-4-7.<br/>Smart-Routing-Aliase: nexevo/fast / nexevo/balanced / nexevo/auto.Alle 121 Modelle ansehen →
messagesMessage[]RequiredOpenAI 标准对话历史。{role, content} 数组,role ∈ system/user/assistant/tool。
streambooleanDefault: false开启 SSE 流式;返回 ChatCompletionChunk 序列,需用 SSE 解析器消费。
temperaturenumberDefault: 1采样温度,0-2。低 = 确定性 / 代码;高 = 创意。
max_tokensintegerOptional单次响应最大 token。不设则用模型默认。
top_pnumberDefault: 1核采样阈值。一般 temperature OR top_p 二选一。
toolsTool[]OptionalOpenAI function calling 标准 tools 数组。详见 Function calling 节。
tool_choice"auto" | "none" | objectOptional工具选择策略;指定具体 tool 名可强制调用。
response_formatobjectOptionalJSON 模式或 Schema 严格模式: {type: "json_object"}{type: "json_schema", json_schema: {...}}
modelsstring[]OptionalNexevo 扩展:多模型 fallback 列表。主 model 失败按顺序尝试,大幅提升可用性。
providerProviderPreferenceOptionalNexevo 扩展:路由偏好,如 {order: ["groq"], allow_fallbacks: true}
max_priceMaxPriceOptionalNexevo 扩展:成本上限 USD,如 {prompt: 0.01, completion: 0.05}。超价直接拒绝。

Streaming-Antwort

Unter der Annahme „stream=true“ leiten wir das Upstream-SSE-Token für Token mit minimaler zusätzlicher Verzögerung weiter. Der Stream endet mit „Daten: [FERTIG]“. Tool-Aufrufe werden über das Tool_calls-Delta zurückgegeben – genau das gleiche wie das OpenAI-Format.

python
stream = client.chat.completions.create(
    model="nexevo/balanced",
    messages=[{"role": "user", "content": "Write a haiku."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)

Funktionsaufruf

Übergeben Sie das Array „tools“ (JSON-Schema-Beschreibungsfunktion). Wenn das Modell beschließt, das Tool aufzurufen, geben Sie „tool_calls“ zurück. Sie führen die Funktion lokal aus, hängen das Ergebnis als Tool-Rollennachricht an und rufen die API erneut auf – genau wie beim OpenAI-Standardprozess.

python
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the weather for a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

resp = client.chat.completions.create(
    model="nexevo/balanced",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=tools,
)
tool_call = resp.choices[0].message.tool_calls[0]
print(tool_call.function.name, tool_call.function.arguments)

Bild- / Video- / 3D-Generierung

Nexevos Generierungs-Gateway vereint 22 Modelle von 8 Anbietern — Bild, Video, 3D. Bild ist synchron (gibt URL oder base64 zurück); Video / 3D ist asynchron über job_id-Polling (SDK bietet generate_and_wait-Helper). Sora 2 / Veo 3 / Runway-Videos werden automatisch zu OSS gespiegelt für 24h signierte URLs. Siehe /cookbook Generation-Kategorie für lauffähige Beispiele.

python
# 1) 文生图(同步)— DALL-E 3 / Imagen 4 / FLUX
img = client.images.generate(
    model="nexevo/image-balanced",       # or "dall-e-3" / "imagen-4-ultra" / "flux-pro"
    prompt="a serene Japanese garden in cyberpunk style",
    n=1, size="1024x1024",
)
print(img["data"][0]["url"])

# 2) 文生视频(异步)— Sora 2 / Veo 3 / Wan 2.6
job = client.videos.generate_and_wait(
    model="sora-2",                          # or "veo-3" / "wan-2.6"
    prompt="a cat skating in neon Tokyo",
    duration_sec=5, aspect_ratio="16:9",
    poll_interval_sec=5, timeout_sec=600,
)
print(job["results"][0]["url"])              # OSS 24h signed URL

# 3) 3D 资产 — Hunyuan 3D 直连
asset = client.models3d.generate_and_wait(
    model="hunyuan-3d-2", prompt="a low-poly viking longboat",
    output_format="glb",
)
print(asset["results"][0]["url"])

# 4) 图生视频 — Runway Gen-4 需先上传参考图
with open("char.png", "rb") as f:
    up = client.generation.uploads.upload(
        f.read(), filename="char.png", content_type="image/png",
    )
job = client.videos.generate_and_wait(
    model="runway-gen4",
    prompt="zoom in slowly while waves crash",
    duration_sec=5,
    reference_image_url=up["url"],
)
POST /v1/images/generations · 同步
modelstringRequired模型 id,如 nexevo/image-balanced / dall-e-3 / imagen-4-ultra / flux-pro。完整 22 模型见 GET /generation/models
promptstringRequired文本描述,最多 4000 字符。
nintegerDefault: 1生成数量,1-10。Imagen 上限 4,DALL-E 3 仅 1。
sizestringDefault: 1024x1024尺寸,常见 1024x1024 / 1792x1024 / 1024x1792;Imagen 自动映射到 aspectRatio。
quality"standard" | "hd"Optional仅 DALL-E 3 / gpt-image-1 用。hd 价格×2,细节更好。
reference_image_b64stringOptional图生图用,base64 PNG / JPG。OpenAI gpt-image-1 / FLUX 支持;DALL-E 3 不支持。
negative_promptstringOptional不想要的元素描述。OpenAI 自动忽略,Replicate / Wan 用。
seedintegerOptional确定性种子,同 prompt + seed 出同图(部分 provider)。
POST /v1/videos/generations · 异步,返 {job_id, status}
modelstringRequiredsora-2 / sora-2-pro / veo-3 / veo-3-fast / wan-2.6 / wan-2.6-pro / runway-gen4 / nexevo/video-{fast|balanced|pro}
promptstringRequired视频文本描述。
duration_secnumberDefault: 5视频时长,1-30 秒。Sora 2 / Veo 3 推荐 5-10。
aspect_ratiostringDefault: "16:9"16:9 / 9:16 / 1:1 / 4:3 / 3:4
reference_image_urlstringOptional图生视频参考图(https URL)。Runway Gen-4 强制必传;Wan 2.6 用作首帧。先调 POST /v1/generation/upload 拿 OSS URL。
negative_promptstringOptionalWan / Replicate / Veo 用。
seedintegerOptional确定性种子(部分 provider)。
POST /v1/3d/generations · 异步
modelstringRequiredhunyuan-3d-2 / hunyuan-3d-2-pro / nexevo/3d-{fast|balanced}
promptstringOptional文本描述(prompt 或 reference_image_url 二选一)。
reference_image_urlstringOptional图生 3D 参考图(https URL)。
output_formatstringDefault: "glb"glb / obj / usdz / stl / fbx
POST /v1/generation/upload · multipart,返 OSS 签名 URL
filemultipart fileRequiredmultipart/form-data 字段名 file,PNG / JPG / WebP / GIF,≤ 10 MB。
GET /v1/generation/jobs/{job_id} · poll(SDK 自动)
idstringOptionalNexevo 内部 job_id(gen_xxxx)。
status"pending" | "running" | "succeeded" | "failed" | "canceled"Optional异步任务状态。
progressnumberOptional0-100,部分 provider(Replicate / Veo)实时报。
resultsGenResult[]Optional完成后含 { url, b64_json, mime_type, duration_ms, ... }。Sora 2 / Veo 3 / Runway 自动镜像到 OSS,URL 24h 有效。
charged_usdstringOptional扣费金额(完成时填入)。
errorobject | nullOptional失败时含 { code, message, retryable }
Tip
Verwende generate_and_wait des SDKs statt eigenem Polling: client.videos.generate_and_wait(model='sora-2', prompt='...', duration_sec=5) — Standard 5s Poll-Intervall, 10 min Timeout, wirft TimeoutError bei Fehler.

Embeddings · Text-Vektorisierung

Text in feste Vektoren komprimieren für RAG-Suche. OpenAI-kompatibles Schema. Abrechnung nach Eingabe-Tokens ($0.02-$0.13/1M).

# OpenAI 兼容 schema — 把 OpenAI client 的 base_url 改成我们的就能用
resp = client.embeddings.create(
    model="text-embedding-3-large",      # 也可写 voyage-3 / jina-embeddings-v3 / bge-m3
    input="Nexevo.ai 是一个 LLM 网关",         # 或 list[str] 批量
)
vec = resp["data"][0]["embedding"]       # 3072 个浮点数
print(len(vec), resp["usage"]["prompt_tokens"])

# 智能路由 — admin 可后台改路由目标,你的代码不用改
resp = client.embeddings.create(
    model="nexevo/embed-balanced",    # 智能路由 = voyage-3(默认)
    input=["doc 1...", "doc 2...", "doc 3..."],
)
for row in resp["data"]:
    print(row["index"], len(row["embedding"]))
POST /v1/embeddings
modelstringRequired客户面 model id。可填:text-embedding-3-large / text-embedding-3-small / voyage-3-large / voyage-3 / jina-embeddings-v3 / bge-m3 / embed-multilingual-v3.0;或智能路由 nexevo/embed-fast / nexevo/embed-balanced
inputstring | string[]Required单段文本或批量(批量上限取决于 provider,通常 100-2048)。
encoding_format"float" | "base64"Default: "float"返回向量的编码;base64 体积小但需要客户端 decode。
dimensionsintegerOptional降维向量维度。仅 text-embedding-3-* / jina-embeddings-v3 支持。
userstringOptionaltenant 标识,审计与速率限制用。
Welcher Anbieter?
Chinesisch: BGE-m3. Englisch: Voyage-3. Mehrsprachig: Jina-v3.

Rerank · RAG-Schritt 2

Top-50 aus Embedding-Suche auf Top-5 neu sortieren. Kritisch für RAG-Genauigkeit.

# RAG 第二段:把 embedding 召回的 top-50 候选重排,只留 top-5 最相关
ranked = client.rerank.create(
    model="rerank-v3.5",                 # 也可 jina-reranker-v2-base / bge-reranker-v2
    query="如何重置员工 VPN?",
    documents=top50_docs,                # list[str] 或 list[{"text": "..."}]
    top_n=5,
)
for r in ranked["results"]:
    print(r["relevance_score"], r["document"][:60])
POST /v1/rerank
modelstringRequired客户面 model id:rerank-v3.5(Cohere)/ rerank-multilingual-v3.0 / jina-reranker-v2-base / bge-reranker-v2 / nexevo/rerank-fast / nexevo/rerank-balanced
querystringRequired检索 query / 用户问题。
documentsstring[] | object[]Required候选文档列表,通常来自 embedding 检索 top-50。可以是 string 或 {"text": "..."}
top_nintegerOptional排序后保留前 N 条。不设则全返(已排序)。
return_documentsbooleanDefault: true返回时是否包含原文。设 false 只返 index + score 节流。
Welcher Reranker?
Englisch: Cohere v3.5. Chinesisch: BGE-reranker-v2. Bestes Preis-Leistung: Jina-v2.

Vollständige RAG-Pipeline

embeddings + rerank + chat. 10k Dokumente ~$0.06 vs ~$5+ direkter Prompt.

python
# 完整 RAG 三段:embedding 召回 → rerank 精排 → chat 答题
# 总成本 ~$0.06 vs 直接塞 1 万篇文档给 chat ~$5+(差 100x)

from nexevo_ai import Nexevo
client = Nexevo()

# ── 1. 离线索引(只跑一次)──
all_docs = ["...", "...", ...]   # 1 万篇文档
emb_resp = client.embeddings.create(model="bge-m3", input=all_docs)
vectors = [d["embedding"] for d in emb_resp["data"]]
# (省略向量库存取代码 — 用 Pinecone / Milvus / pgvector 都行)

# ── 2. 用户提问时(每次请求触发)──
question = "如何重置员工 VPN?"

# 2a) embed 问题 → 检索 top-50
q_emb = client.embeddings.create(model="bge-m3", input=question)
top50 = vector_db.query(q_emb["data"][0]["embedding"], k=50)

# 2b) rerank top-50 → top-5 最相关
ranked = client.rerank.create(
    model="rerank-v3.5",
    query=question,
    documents=[d.text for d in top50],
    top_n=5,
)["results"]
top5 = [top50[r["index"]] for r in ranked]

# 2c) chat 用 top-5 答题
context = "\n\n".join(d.text for d in top5)
ans = client.chat.completions.create(
    model="nexevo/balanced",
    messages=[
        {"role": "system",
         "content": f"基于以下材料答题(只能用这些材料,不要编):\n\n{context}"},
        {"role": "user", "content": question},
    ],
)
print(ans.choices[0].message.content)
Vektor-Datenbank?
Klein: pgvector. Mittel: Qdrant / Weaviate. Groß: Pinecone / Milvus.

Agents · Agent-as-a-Service

Übergeben Sie eine hochrangige Aufgabe an einen Agent — er zerlegt Schritte, ruft Tools auf und schleift bis zur Antwort. Integrierte Tools: rag_search + list_models.

from nexevo_ai import Nexevo
client = Nexevo()

# 1) 同步模式(默认 wait=True)— 阻塞等结果,deadline 默认 120s,可调到 3600s
job = client.agents.run(
    task="找一个最便宜的中文 RAG embedding 模型,告诉我维度和单价",
    model="nexevo/balanced",        # chat brain,可换 claude / gpt-5 等
    max_steps=10,
)
print(job["result"])
# Agent 内部会:
#   step 1: chat → tool_call list_models(kind=embedding, modality 多语言)
#   step 2: tool_result 返 BGE-m3 / Jina-v3 等候选
#   step 3: chat 综合 → final_answer "BGE-m3 1024 维,$0.07/1M"

# 2) 给 RAG 任务预加载文档
job = client.agents.run(
    task="基于这些资料答:如何重置员工 VPN?",
    rag_documents=[
        "VPN 服务器列表请联系 IT 支持...",
        "重置 VPN 密码需要登录员工门户...",
        # ... 上千条
    ],
    tools=["rag_search"],
)

# 3) 异步任务(长任务推荐)
submitted = client.agents.run(task="复杂调研任务...", wait=False)
job = client.agents.run_and_wait(submitted["id"], timeout_sec=300)

# 4) Memory tools(2026-04-29 P4 v2)— LLM 主动读写工作记忆 / 长期记忆
#    任务级 memory:节点之间共享中间事实(避免 prompt 拼接爆炸)
#    tenant 级 memory:跨任务的"上次客户做过 X" 让 agent 第二次更聪明
#    工具自动注入,LLM 调用 memory_read({level:"task", key:"..."}) 即可
POST /v1/agents/run · POST /v1/agents/run/stream(SSE)
taskstringRequired用户面任务描述。Agent 内部 LLM brain 拿这个当 user message 起循环。
modelstringDefault: "nexevo/balanced"Agent 大脑(chat completion 模型)。可换 claude-opus-4-7 / gpt-5 / nexevo/fast 等。
toolsstring[]Optional启用的内置 tool 名;不填 = 全部启用。内置:rag_search / list_models / web_search / generate_image / python_exec / spawn_agent / memory_read / memory_write
max_stepsintegerDefault: 10最多循环几步;防 LLM 死循环。上限 30。
rag_documentsstring[]Optionalrag_search tool 启动时预加载的文档,内部用 BGE-m3 embed + rerank-v3.5 精排。
system_promptstringOptional覆盖默认 agent 系统提示。
waitbooleanDefault: true同步阻塞等结果(true,默认 deadline 120s,可调上限 3600s)/ 异步立返 task_id 后客户走 GET /v1/tasks/{id} poll(false,长任务推荐)。
timeout_secintegerDefault: 120wait=true 时生效,超时返当前状态(可能仍 running),客户后续 poll。上限 3600s。
enable_verifierbooleanDefault: falsefinal_answer 出来后跑 cheap-model 多维度评估(factuality / relevance / completeness / safety),overall < threshold → verifier_passed=false
verifier_thresholdfloatDefault: 0.7verifier overall 分数低于此值标 failed。建议 0.6-0.8。
max_cost_usdfloatOptional软告警上限 — 估算累计花费超此值时 emit budget_warning step,**任务继续**;真正硬门 = 账户余额。避免估算误差导致误杀。

SSE-Streaming — Live-Schritt-Events

python
# 流式 — 实时拿每步事件,边跑边看
for ev in client.agents.run_stream(task="..."):
    if ev["type"] == "step":
        s = ev["step"]
        if s["type"] == "tool_call":
            print(f"→ 调用 {s['tool_name']}({s['tool_input']})")
        elif s["type"] == "tool_result":
            print(f"  ← {s['tool_output']}")
        elif s["type"] == "final_answer":
            print(f"\n答:{s['content']}")
    elif ev["type"] == "done":
        print(f"\n总 token: in={ev['job']['total_tokens_in']}, out={ev['job']['total_tokens_out']}")
Wann Agents verwenden?
Einfache Aufgaben: chat direkt. Mehrstufige / mit Tools / zerlegbare Aufgaben: Agents. 5 Schritte ≈ 5x Chat-Kosten.

/v1/tasks · Task-as-a-Service + Self-Healing v2

/v1/agents/run ist ein konversationeller Agent. /v1/tasks ist Task-as-a-Service — fügt Planner (auto DAG-Zerlegung), mehrdimensionalen Verifier, Auto-repair-Reflexionsschleife und Partial-Success-Marker hinzu. Vollständige Plan→Execute→Evaluate→Adjust→Loop-Architektur, erwartete Erfolgsrate +20-25 pp.

POST /v1/tasks(任务即服务,Self-Healing v2)
goalstringRequired高层任务目标(替代 task)。Planner 拆 DAG 时从这里读。
deliverablesobject[]Optional结构化交付物声明:[{type:"email", target:"x@y.com"}] 或 webhook。
budget_usdfloatOptional任务级软告警预算(同 max_cost_usd 语义)。
deadline_secintegerDefault: 120任务超时;wait=true 时是同步上限,wait=false 时是后台执行上限。≥10、≤3600。
enable_plannerbooleanDefault: false用便宜 model(nexevo/fast 默认)拆 NL goal → DAG plan,executor 按图并行调度。复杂任务质量提升明显。
planner_modelstringDefault: "nexevo/fast"Planner 用什么模型(便宜模型够,通常无需改)。
planner_n_candidatesintegerDefault: 1并行生成 N 个候选 plan + 启发评分选优(节点数 / aggregate 唯一性 / tool_call 存在 / 引用合法)。1 单跑 / 2-5 多样性。
auto_repair_max_roundsintegerDefault: 0**Self-Healing**:verifier 失败时 → cheap-LLM 反思根因 → 重新 plan + 局部 re-run(checkpoint 复用成功节点)。0 关 / 1-3 启用。期望成功率 +20-25 pp。
autonomy_level"L1" | "L2" | "L3"Default: "L3"L1 启动前一次性确认 / L2 副作用工具(email / webhook / mcp:slack:*)调用前确认 / L3 完全托管。
python
from nexevo_ai import Nexevo
client = Nexevo()

# Self-Healing v2 — 任务自我修复闭环(Plan → Execute → Evaluate → Adjust)
result = client.tasks.submit(
    goal="调研 2025 Q2 全球生成式视频生成 Top 5 厂商,输出对比表(ARR/客户/技术亮点)",
    enable_planner=True,
    planner_n_candidates=3,         # 并行生成 3 个候选 plan,启发选优
    auto_repair_max_rounds=2,       # verifier 失败 → 反思 + 重 plan 最多 2 轮
    deadline_sec=600,               # 长任务给充裕时间
    wait=True,                       # 阻塞拿结果(或 wait=False 异步 poll)
    deliverables=[{"type": "email", "target": "you@company.com"}],
)

# response 含:plan(实际跑的)+ deliverables + verifier 多维分 + partial 标记
print(result["plan"]["nodes"])                  # 看 agent 怎么拆的
print(result["deliverables"][0]["content"])     # 主答
print(result["deliverables"][0]["metadata"])    # verifier 多维分
if result["partial"]:
    print("部分成功节点:", result["succeeded_node_ids"])
    print("失败节点:",   result["failed_node_ids"])
💾 Memory-System (neu 2026-04-29)
Zweistufiger Memory automatisch injiziert: **Task-Level Working Memory** (Fakten zwischen Knoten geteilt, verhindert Prompt-Aufblähung) + **Tenant-Level Long-Term Memory** (übergreifendes Wissen). LLM nutzt eingebaute memory_read / memory_write Tools; Scope ist backend-seitig an api_key gebunden — kein Cross-Tenant-Leak.

Nächster Schritt

Kern-API — Nexevo Docs | Nexevo.ai