使用编程智能体? 开始前请复制并粘贴此提示:
You are integrating this project with Phaseo Gateway. Read the Phaseo agent guidance at https://phaseo.app/docs/skill.md and the relevant API reference before editing anything. Inspect the existing provider configuration and identify the smallest safe change needed. Use https://api.phaseo.app with a server-side PHASEO_API_KEY, preserve the current provider/model behavior unless I explicitly ask for a migration, and never print or commit credentials. Explain the files you would change and the verification commands first. Do not deploy, rotate keys, send external messages, or make unrelated edits without my approval.
- 创建 API 密钥
- 发送文本请求或结构化决策请求
- 读取生成文本或带类型的答案
- 了解请求失败时应先检查什么
1. 创建 API 密钥
- 打开 Phaseo 控制台。
- 在 Gateway -> 密钥下创建密钥。
- 只复制一次,并安全保存。
Authorization: Bearer phaseo_v1_sk_<kid>_<secret>
请像保护密码一样保护 API 密钥。不要将其暴露在客户端代码中。
2. 发送文本请求
首次请求使用POST /v1/responses。这是新文本生成集成的推荐端点。
请求
curl https://api.phaseo.app/v1/responses \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-6-astra",
"input": "Reply with: quickstart works"
}'
const response = await fetch("https://api.phaseo.app/v1/responses", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "openai/gpt-6-astra",
input: "Reply with: quickstart works",
}),
});
const data = await response.json();
const assistantText = data.output
?.find((item) => item.type === "message")
?.content?.find((part) => part.type === "output_text")
?.text;
console.log(assistantText);
import Phaseo from "@phaseo/sdk";
const client = new Phaseo({ apiKey: process.env.PHASEO_API_KEY! });
const response = await client.generateResponse({
model: "openai/gpt-6-astra",
input: "Reply with: quickstart works",
});
const assistantText = response.output
?.find((item: any) => item.type === "message")
?.content?.find((part: any) => part.type === "output_text")
?.text;
console.log(assistantText);
from phaseo import Phaseo
client = Phaseo(api_key="YOUR_API_KEY")
response = client.generate_response(
{
"model": "openai/gpt-6-astra",
"input": "Reply with: quickstart works",
}
)
assistant_text = next(
(
part.get("text")
for item in response.get("output", [])
if item.get("type") == "message"
for part in item.get("content", [])
if part.get("type") == "output_text"
),
None,
)
print(assistant_text)
package main
import (
"context"
"fmt"
phaseo "github.com/phaseoteam/Phaseo/packages/sdk/sdk-go/v3"
)
func main() {
client := phaseo.New("YOUR_API_KEY", "https://api.phaseo.app/v1")
input := map[string]interface{}{
"role": "user",
"content": []map[string]interface{}{
{
"type": "input_text",
"text": "Reply with: quickstart works",
},
},
}
response, err := client.GenerateResponse(context.Background(), phaseo.ResponsesRequest{
Model: "openai/gpt-6-astra",
Input: &input,
})
if err != nil {
panic(err)
}
fmt.Println(response)
}
using PhaseoSdk;
using System.Collections.Generic;
var client = new Phaseo("YOUR_API_KEY");
var response = await client.GenerateResponse(new Dictionary<string, object>
{
["model"] = "openai/gpt-6-astra",
["input"] = "Reply with: quickstart works",
});
Console.WriteLine(response);
<?php
require 'vendor/autoload.php';
use Phaseo\Sdk\Phaseo;
$client = new Phaseo(getenv('PHASEO_API_KEY') ?: 'YOUR_API_KEY');
$response = $client->generateResponse([
'model' => 'openai/gpt-6-astra',
'input' => 'Reply with: quickstart works',
]);
print_r($response);
require 'phaseo_sdk'
client = PhaseoSdk::Phaseo.new(api_key: ENV.fetch('PHASEO_API_KEY', 'YOUR_API_KEY'))
response = client.generate_response(
model: 'openai/gpt-6-astra',
input: 'Reply with: quickstart works',
)
puts response
use phaseo::Phaseo;
use serde_json::{json, Value};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Phaseo::from_env()?;
let response = client.responses(&json!({
"model": "openai/gpt-6-astra",
"input": "Reply with: quickstart works"
}))?;
let assistant_text = response.body
.get("output")
.and_then(Value::as_array)
.into_iter()
.flatten()
.filter(|item| item.get("type").and_then(Value::as_str) == Some("message"))
.flat_map(|item| {
item.get("content")
.and_then(Value::as_array)
.into_iter()
.flatten()
})
.find_map(|part| {
(part.get("type").and_then(Value::as_str) == Some("output_text"))
.then(|| part.get("text").and_then(Value::as_str))
.flatten()
})
.unwrap_or("");
println!("{assistant_text}");
Ok(())
}
import { phaseo } from "@phaseo/ai-sdk-provider";
import { generateText } from "ai";
const result = await generateText({
model: phaseo("openai/gpt-6-astra"),
prompt: "Reply with: quickstart works",
});
console.log(result.text);
响应
{
"id": "resp_...",
"object": "response",
"created_at": 1730000000,
"status": "completed",
"completed_at": 1730000001,
"model": "openai/gpt-6-astra",
"output": [
{
"type": "message",
"id": "msg_...",
"status": "completed",
"role": "assistant",
"content": [{ "type": "output_text", "text": "quickstart works", "annotations": [] }]
}
],
"usage": {
"input_tokens": 9,
"output_tokens": 3,
"total_tokens": 12
},
"error": null,
"incomplete_details": null
}
output[].content[] 中 type 为 output_text 的内容读取助手回复。
如果使用 Vercel AI SDK,请从 result.text 读取回复。
3. 作出结构化决策
应用需要带类型的答案而非生成文本时,请使用POST /v1/decisions。Phaseo 提供 TypeSafe 的 Jev 1.13,模型 ID 为 typesafe/jev-1.13.0。发送 state 值和一个或多个具名问题;每个答案都以相同名称返回。
Decisions 是测试版功能,可能需要在工作区启用。Jev 1.13 按每百万输入令牌 $0.042 计费;输出令牌免费。
PHASEO_API_KEY 的服务器上运行这些示例。切勿在浏览器代码中暴露 Gateway API 密钥。
三种问题类型为:
choice从条件映射中选择一个选项,并返回概率和置信度。noul返回 0 到 1 之间的是/否概率。score评估有序条件数组,并返回概率加权分数。
请求
curl https://api.phaseo.app/v1/decisions \
-H "Authorization: Bearer $PHASEO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "typesafe/jev-1.13.0",
"state": {
"customer_message": "I was charged twice and need help with a refund.",
"account_tier": "pro",
"days_waiting": 3
},
"questions": {
"department": {
"type": "choice",
"instructions": "Which team should handle this request?",
"criteria": {
"billing": "Payments, invoices, refunds, and duplicate charges.",
"support": "Product usage questions and troubleshooting.",
"sales": "Upgrades and new accounts."
}
},
"is_urgent": {
"type": "noul",
"instructions": "Does this request require urgent handling?",
"criteria": {
"true": "The customer is blocked or the issue is time-sensitive.",
"false": "The request can follow the normal support queue."
}
},
"customer_impact": {
"type": "score",
"instructions": "How severe is the customer impact?",
"criteria": [
"No impact",
"Minor inconvenience",
"Significant impact",
"Service blocked"
]
}
}
}'
const response = await fetch("https://api.phaseo.app/v1/decisions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PHASEO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "typesafe/jev-1.13.0",
state: {
customer_message: "I was charged twice and need help with a refund.",
account_tier: "pro",
days_waiting: 3,
},
questions: {
department: {
type: "choice",
instructions: "Which team should handle this request?",
criteria: {
billing: "Payments, invoices, refunds, and duplicate charges.",
support: "Product usage questions and troubleshooting.",
sales: "Upgrades and new accounts.",
},
},
is_urgent: {
type: "noul",
instructions: "Does this request require urgent handling?",
criteria: {
true: "The customer is blocked or the issue is time-sensitive.",
false: "The request can follow the normal support queue.",
},
},
customer_impact: {
type: "score",
instructions: "How severe is the customer impact?",
criteria: [
"No impact",
"Minor inconvenience",
"Significant impact",
"Service blocked",
],
},
},
}),
});
if (!response.ok) throw new Error(await response.text());
const data = await response.json();
console.log(data.answers);
import Phaseo from "@phaseo/sdk";
const client = new Phaseo({ apiKey: process.env.PHASEO_API_KEY! });
const decision = await client.decisions.make({
model: "typesafe/jev-1.13.0",
state: {
customer_message: "I was charged twice and need help with a refund.",
account_tier: "pro",
days_waiting: 3,
},
questions: {
department: {
type: "choice",
instructions: "Which team should handle this request?",
criteria: {
billing: "Payments, invoices, refunds, and duplicate charges.",
support: "Product usage questions and troubleshooting.",
sales: "Upgrades and new accounts.",
},
},
is_urgent: {
type: "noul",
instructions: "Does this request require urgent handling?",
criteria: {
true: "The customer is blocked or the issue is time-sensitive.",
false: "The request can follow the normal support queue.",
},
},
customer_impact: {
type: "score",
instructions: "How severe is the customer impact?",
criteria: [
"No impact",
"Minor inconvenience",
"Significant impact",
"Service blocked",
],
},
},
});
console.log(decision.answers);
from phaseo import Phaseo
client = Phaseo() # Uses PHASEO_API_KEY from the environment
decision = client.decisions.make(
{
"model": "typesafe/jev-1.13.0",
"state": {
"customer_message": "I was charged twice and need help with a refund.",
"account_tier": "pro",
"days_waiting": 3,
},
"questions": {
"department": {
"type": "choice",
"instructions": "Which team should handle this request?",
"criteria": {
"billing": "Payments, invoices, refunds, and duplicate charges.",
"support": "Product usage questions and troubleshooting.",
"sales": "Upgrades and new accounts.",
},
},
"is_urgent": {
"type": "noul",
"instructions": "Does this request require urgent handling?",
"criteria": {
"true": "The customer is blocked or the issue is time-sensitive.",
"false": "The request can follow the normal support queue.",
},
},
"customer_impact": {
"type": "score",
"instructions": "How severe is the customer impact?",
"criteria": [
"No impact",
"Minor inconvenience",
"Significant impact",
"Service blocked",
],
},
},
}
)
print(decision["answers"])
响应
{
"model": "typesafe/jev-1.13.0",
"answers": {
"department": {
"type": "choice",
"choice": "billing",
"probabilities": { "billing": 0.91, "support": 0.06, "sales": 0.03 },
"confidence": 0.89
},
"is_urgent": {
"type": "noul",
"noul": 0.84
},
"customer_impact": {
"type": "score",
"score": 2.4,
"legend": {
"0": "No impact",
"1": "Minor inconvenience",
"2": "Significant impact",
"3": "Service blocked"
},
"probabilities": { "0": 0.02, "1": 0.12, "2": 0.61, "3": 0.25 },
"confidence": 0.76
}
},
"usage": {
"input_tokens": 42,
"output_tokens": 18,
"total_tokens": 60
}
}
answers.department.choice、answers.is_urgent.noul 或 answers.customer_impact.score。需要设置应用阈值时,使用 confidence 和 probabilities,不要仅根据值分支。
完整请求和响应约定请参阅 Decisions API 参考;模型行为和上游限制请参阅 TypeSafe 的 Jev 模型参考。
4. 排查第一个请求的问题
401:检查 API 密钥和Authorization请求头。400:检查请求正文和模型 ID。402:切换到:free模型,或在使用付费模型前充值。429或5xx:使用指数退避策略重试。
5. 如果你正在开发视频功能
视频生成是异步的。先创建任务,然后轮询状态或订阅结果。- 使用
POST /v1/videos创建任务。 - 使用
GET /v1/videos/{video_id}查询状态,直到任务完成。 - 使用
GET /v1/videos/{video_id}/content下载内容。
# Create
curl https://api.phaseo.app/v1/videos \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<video-model-id>",
"prompt": "A cinematic sunrise over a mountain lake"
}'
# Poll status
curl https://api.phaseo.app/v1/videos/VIDEO_ID \
-H "Authorization: Bearer YOUR_API_KEY"
6. 继续开发
集成 Gateway
生产环境集成模式和端点选择。
API 参考
所有端点的完整请求与响应文档。
示例
常见工作流的更多完整请求示例。
支持
获取有关调试、路由和模型行为的帮助。