POST /v1/responses 发送一个请求,然后从 output_text 读取回复。
从编程智能体开始
将此提示词复制到你的编程智能体中。它会识别项目的语言、安装 SDK、让智能体参考 Phaseo 文档、确保密钥不会写进代码,并发送第一个请求。如果项目已经在使用 Phaseo,它会检查现有配置,而不是从头开始。phaseo/free 无需额度即可使用;也可以换成 模型 中的任意文本模型 ID。
适用于编程智能体的设置提示词。 复制它,或在 Cursor 中打开。
1. 创建 API 密钥
在控制台的 设置 -> API 密钥 下创建密钥,然后导出它:export PHASEO_API_KEY="phaseo_v1_sk_..."
Authorization: Bearer phaseo_v1_sk_<kid>_<secret>
请像对待密码一样对待 API 密钥。把它放在服务端代码中,永远不要把它发布到浏览器或移动应用中。
为付费模型充值额度
phaseo/free 无需额度即可使用。openai/gpt-6-astra 等付费模型需要钱包余额:
phaseo login --scopes billing:write # once; credit top-ups need this scope
phaseo credits add --amount 20
2. 发送文本请求
POST /v1/responses 是新文本工作的推荐端点。示例使用付费模型 openai/gpt-6-astra。如需在没有额度的情况下测试,请把它换成 phaseo/free,它会选择一个可用的免费模型;参见从免费路由器开始上线。
cURL 和 fetch 无需安装任何内容。如需使用 SDK,请先安装:
npm install @phaseo/sdk
pnpm add @phaseo/sdk
pip install phaseo
curl https://api.phaseo.app/v1/responses \
-H "Authorization: Bearer $PHASEO_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 ${process.env.PHASEO_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, { outputText } from "@phaseo/sdk";
const client = new Phaseo(); // reads PHASEO_API_KEY
const response = await client.generateResponse({
model: "openai/gpt-6-astra",
input: "Reply with: quickstart works",
});
console.log(outputText(response));
from phaseo import Phaseo
client = Phaseo() # reads PHASEO_API_KEY
response = client.responses.create(
{
"model": "openai/gpt-6-astra",
"input": "Reply with: quickstart works",
}
)
print(response.output_text)
package main
import (
"context"
"fmt"
phaseo "github.com/phaseoteam/Phaseo/packages/sdk/sdk-go/v3"
)
func main() {
client := phaseo.MustNewFromEnv() // reads PHASEO_API_KEY
response, err := client.GenerateResponse(context.Background(), phaseo.ResponsesRequest{
Model: "openai/gpt-6-astra",
Input: "Reply with: quickstart works",
})
if err != nil {
panic(err)
}
fmt.Println(response)
}
using PhaseoSdk;
using System.Collections.Generic;
var client = new Phaseo(); // reads PHASEO_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'));
$response = $client->generateResponse([
'model' => 'openai/gpt-6-astra',
'input' => 'Reply with: quickstart works',
]);
print_r($response);
require 'phaseo_sdk'
client = PhaseoSdk::Phaseo.new # reads PHASEO_API_KEY
response = client.generate_response(
model: 'openai/gpt-6-astra',
input: 'Reply with: quickstart works',
)
puts response
// Build from source: https://phaseo.app/docs/v1/sdk-reference/client/installation
import app.phaseo.sdk.Phaseo;
import java.util.Map;
public class Main {
public static void main(String[] args) throws Exception {
var client = new Phaseo(System.getenv("PHASEO_API_KEY"));
var response = client.createResponse(Map.of(
"model", "openai/gpt-6-astra",
"input", "Reply with: quickstart works"
));
for (var item : response.path("output")) {
for (var part : item.path("content")) {
if ("output_text".equals(part.path("type").asText())) {
System.out.println(part.path("text").asText());
}
}
}
}
}
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);
3. 读取回复
{
"id": "G-...",
"nativeResponseId": "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" 的项 | 回复文本。TypeScript 的 outputText() 辅助函数和 Python 的 response.output_text 会替你读取它;Vercel AI SDK 将它作为 result.text 返回。 |
id | Phaseo 请求 ID。该请求会出现在 设置 -> 使用情况 -> 日志 -> 请求 下。 |
nativeResponseId | 提供商为同一响应分配的 ID。 |
usage | 该请求计费的输入、输出和总 token 数。 |
流式输出回复
使用流式输出,可以在回复生成时就把它打印出来。每个response.output_text.delta 事件的 text 只包含新增文本,因此这个循环只会打印一次答案。response.output_text.done 等结束事件会重复已经流式输出过的文本。完整事件列表请参阅流式输出。
import Phaseo from "@phaseo/sdk";
const client = new Phaseo(); // reads PHASEO_API_KEY
for await (const chunk of client.streamResponses({
model: "openai/gpt-6-astra",
input: "Reply with: quickstart works",
})) {
if (chunk.type === "response.output_text.delta") process.stdout.write(chunk.text);
}
from phaseo import Phaseo
client = Phaseo() # reads PHASEO_API_KEY
for chunk in client.stream_responses(
{
"model": "openai/gpt-6-astra",
"input": "Reply with: quickstart works",
}
):
if chunk.get("type") == "response.output_text.delta":
print(chunk["text"], end="", flush=True)
print()
4. 排查第一个请求的问题
| 状态码 | 检查项 |
|---|---|
401 | API 密钥和 Authorization: Bearer 请求头。 |
400 | 请求正文和模型 ID。用 GET /v1/models 列出有效 ID。 |
402 | 你的额度余额。充值额度或改用 phaseo/free。 |
429 或 5xx | 使用指数退避重试。 |
获取带类型的答案而不是文本
当代码需要的是一个值而不是一段文字时,把问题发送到POST /v1/decisions(Beta)。每个答案都带类型和概率返回,顺序与问题相同。问题类型有 predicate(是/否)、choice(从你的选项中选一个)和 score(你的量表上的一个等级)。
curl https://api.phaseo.app/v1/decisions \
-H "Authorization: Bearer $PHASEO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-6-luna",
"input": "I was charged twice and need a refund. I cannot log in to pay my team.",
"questions": [
{
"type": "choice",
"name": "department",
"instructions": "Which team should handle this request?",
"choices": [
{ "value": "billing", "description": "Payments, invoices, refunds and duplicate charges" },
{ "value": "support", "description": "Product usage and troubleshooting" }
]
},
{
"type": "predicate",
"name": "is_urgent",
"instructions": "Is the customer blocked from using the product?"
}
]
}'
import Phaseo from "@phaseo/sdk";
const client = new Phaseo(); // reads PHASEO_API_KEY
const decision = await client.decisions.create({
model: "openai/gpt-6-luna",
input: "I was charged twice and need a refund. I cannot log in to pay my team.",
questions: [
{
type: "choice",
name: "department",
instructions: "Which team should handle this request?",
choices: [
{ value: "billing", description: "Payments, invoices, refunds and duplicate charges" },
{ value: "support", description: "Product usage and troubleshooting" },
],
},
{
type: "predicate",
name: "is_urgent",
instructions: "Is the customer blocked from using the product?",
},
],
});
console.log(decision.answers);
from phaseo import Phaseo
client = Phaseo() # reads PHASEO_API_KEY
decision = client.decisions.create(
{
"model": "openai/gpt-6-luna",
"input": "I was charged twice and need a refund. I cannot log in to pay my team.",
"questions": [
{
"type": "choice",
"name": "department",
"instructions": "Which team should handle this request?",
"choices": [
{"value": "billing", "description": "Payments, invoices, refunds and duplicate charges"},
{"value": "support", "description": "Product usage and troubleshooting"},
],
},
{
"type": "predicate",
"name": "is_urgent",
"instructions": "Is the customer blocked from using the product?",
},
],
}
)
print(decision["answers"])
{
"model": "openai/gpt-6-luna",
"answers": [
{
"type": "choice",
"name": "department",
"choice": "billing",
"confidence": 0.89,
"probabilities": [
{ "value": "billing", "probability": 0.91 },
{ "value": "support", "probability": 0.09 }
]
},
{ "type": "predicate", "name": "is_urgent", "probability": 0.84 }
],
"usage": { "input_tokens": 42, "output_tokens": 18, "total_tokens": 60 }
}
answers[0].choice 或 answers[1].probability,并用 confidence 或 probabilities 设置你自己的阈值。Decisions 参考列出了每个决策模型、它的限制和价格、图片输入,以及带命名问题映射(noul、criteria)的旧版 state 格式;旧格式仍然可用,某些模型也必须使用它。
生成视频
视频生成是异步的:先创建任务,再轮询它,然后下载文件。# 1. 创建任务
curl https://api.phaseo.app/v1/videos \
-H "Authorization: Bearer $PHASEO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "google/veo-3.1-fast",
"prompt": "A cinematic sunrise over a mountain lake"
}'
# 2. 轮询,直到状态变为 completed
curl https://api.phaseo.app/v1/videos/VIDEO_ID \
-H "Authorization: Bearer $PHASEO_API_KEY"
# 3. 下载视频
curl https://api.phaseo.app/v1/videos/VIDEO_ID/content \
-H "Authorization: Bearer $PHASEO_API_KEY" \
-o video.mp4
继续构建
集成 Gateway
选择端点并搭建生产环境集成。
API 参考
每个端点的全部请求和响应字段。
示例
常见工作流的入门应用。
支持
获取有关调试、路由和模型行为的帮助。