TokenLab

Văn bản

Tạo Response

Tạo một phản hồi bằng định dạng OpenAI Responses API

POST
/v1/responses

Sử dụng endpoint này khi accepted_request_formats của một mô hình bao gồm openai_responses. Các request và response sử dụng định dạng Responses API và không được chuyển đổi: mô hình không có định dạng đó sẽ trả về 400 tại đây, vì vậy hãy sử dụng Chat Completions cho mô hình đó. Các trường tùy chọn và các giá trị được hỗ trợ phụ thuộc vào mô hình đã chọn.

Phần thân yêu cầu (Request Body)

modelstringbắt buộc

ID của mô hình cần sử dụng. Xem Models để biết các tùy chọn khả dụng.

inputstring | array

Đầu vào cho response. Trường này là tùy chọn khi request sử dụng một prompt có thể tái sử dụng thay thế hoặc tiếp tục một response đã lưu trữ bằng previous_response_id.

Mỗi mục là một object có type. Các loại phổ biến là:

  • message: Một tin nhắn hội thoại có role và content
  • function_call: Một yêu cầu gọi hàm (function call)
  • function_call_output: Kết quả đầu ra từ một function call
  • reasoning: Một mục suy luận (thinking) từ response trước đó. Hãy gửi lại nguyên vẹn không thay đổi

Các loại mục khác phụ thuộc vào mô hình đã chọn.

Đối với đầu vào đa phương thức (multimodal), message.content có thể là một chuỗi văn bản thuần túy hoặc một mảng các khối nội dung. Đối với các mô hình hỗ trợ hình ảnh, hãy truyền hình ảnh dưới dạng các khối input_image thay vì nhúng trực tiếp URL hoặc chuỗi Base64 vào văn bản thuần túy.

Ví dụ về các khối nội dung:

  • { "type": "input_text", "text": "Describe this image" }
  • { "type": "input_image", "image_url": "https://example.com/image.jpg" }
  • { "type": "input_image", "image_url": "data:image/png;base64,..." }
instructionsstring

Hướng dẫn hệ thống cho mô hình (tương đương với system message).

max_output_tokensinteger

Số lượng token tối đa cần tạo.

temperaturenumber

Nhiệt độ lấy mẫu (sampling temperature). Các giá trị được hỗ trợ và giá trị mặc định phụ thuộc vào mô hình đã chọn.

toolsarray

Các công cụ mà mô hình có thể gọi. Các loại và tổ hợp được hỗ trợ phụ thuộc vào mô hình đã chọn.

streambooleanmặc định: false

Nếu là true, trả về một luồng (stream) sự kiện. Xem Streaming.

previous_response_idstring

ID của một response trước đó để tiếp tục cuộc trò chuyện. Response này phải thuộc về tài khoản của bạn và vẫn còn được lưu trữ; nếu không, request sẽ trả về 404 với mã response_not_found. Hãy tiếp tục với mô hình đã tạo ra nó. Nếu dịch vụ tạo ra response tạm thời không khả dụng, request có thể trả về 503.

storebooleanmặc định: true

Có lưu trữ response để truy xuất sau này và sử dụng cho previous_response_id hay không. Với false, TokenLab không giữ lại response và GET /v1/responses/{id} sẽ không thể trả về response đó.

backgroundbooleanmặc định: false

Yêu cầu thực thi bất đồng bộ. Khả năng hỗ trợ phụ thuộc vào mô hình đã chọn. Lời gọi tạo sẽ trả về ngay lập tức, thường với status là queued hoặc in_progress. Hãy thăm dò (poll) Retrieve a response cho đến khi status chuyển thành completed, incomplete, failed, hoặc cancelled. Một background request có thể trả về 503 khi quá trình xử lý nền tạm thời không khả dụng.

tool_choicestring | object

Chính sách lựa chọn công cụ, chẳng hạn như auto, none, required, hoặc một object chỉ định một công cụ. Các giá trị được hỗ trợ phụ thuộc vào mô hình đã chọn.

includearray

Các phần đầu ra bổ sung cần trả về, khi mô hình đã chọn hỗ trợ chúng.

stream_optionsobject

Các tùy chọn streaming. include_obfuscation được chuyển tiếp ở những nơi mô hình đã chọn hỗ trợ.

truncationstring

Chiến lược cắt bớt (truncation strategy) cho các cuộc trò chuyện dài, khi mô hình đã chọn hỗ trợ.

service_tierstring

TokenLab phục vụ và tính phí các request Responses ở tầng dịch vụ tiêu chuẩn. auto và default được chấp nhận. Các giá trị khác, chẳng hạn như flex hoặc priority, sẽ bị xóa khỏi request và request sẽ được tính theo giá tiêu chuẩn.

promptobject

Tham chiếu đến một mẫu prompt có thể tái sử dụng và các biến.

metadataobject

Metadata tùy chỉnh được lưu trữ cùng với response.

textobject

Cài đặt đầu ra văn bản. Khả năng hỗ trợ text.format phụ thuộc vào mô hình đã chọn.

parallel_tool_callsboolean

Cho phép thực hiện nhiều lệnh gọi công cụ song song hay không, khi được mô hình đã chọn hỗ trợ.

top_pnumber

Tham số nucleus sampling (0-1).

reasoningobject

Các tùy chọn suy luận (reasoning), bao gồm effort, phụ thuộc vào mô hình đã chọn.

Phản hồi

idstring

Mã định danh duy nhất cho response.

objectstring

Luôn là response.

created_atinteger

Unix timestamp xác định thời điểm response được tạo.

statusstring

Trạng thái của response: queued, in_progress, completed, incomplete, failed, hoặc cancelled. Hãy kiểm tra trường này ngay cả khi HTTP request thành công.

outputarray

Danh sách các mục đầu ra do mô hình tạo.

usageobject

Thống kê lượng token sử dụng.

Các Endpoint liên quan

  • GET /v1/responses/{id} truy xuất một response đã lưu trữ.
  • DELETE /v1/responses/{id} xóa một response đã lưu trữ. Thao tác này không hủy quá trình tạo.
  • POST /v1/responses/compact thu gọn một cuộc trò chuyện và trả về một object response.compaction.
  • wss://api.tokenlab.sh/v1/responses tạo các response qua WebSocket. Xem Streaming.
  • Các endpoint Cancel, input-items và input-tokens hiện chưa khả dụng.

Yêu cầu

cURL
curl -X POST "https://api.tokenlab.sh/v1/responses" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": [
      {"type": "message", "role": "user", "content": "Hello!"}
    ],
    "max_output_tokens": 1000
  }'
Python
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh/v1"
)

response = client.responses.create(
    model="gpt-5.6-terra",
    input=[
        {"type": "message", "role": "user", "content": "Hello!"}
    ],
    max_output_tokens=1000
)

print(response.output)
JavaScript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.tokenlab.sh/v1'
});

const response = await client.responses.create({
  model: 'gpt-5.6-terra',
  input: [
    { type: 'message', role: 'user', content: 'Hello!' }
  ],
  max_output_tokens: 1000
});

console.log(response.output);
Go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    payload := map[string]interface{}{
        "model": "gpt-5.6-terra",
        "input": []map[string]interface{}{
            {"type": "message", "role": "user", "content": "Hello!"},
        },
        "max_output_tokens": 1000,
    }
    body, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", "https://api.tokenlab.sh/v1/responses", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer sk-your-api-key")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result["output"])
}
PHP
<?php
$ch = curl_init('https://api.tokenlab.sh/v1/responses');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer sk-your-api-key'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'gpt-5.6-terra',
        'input' => [
            ['type' => 'message', 'role' => 'user', 'content' => 'Hello!']
        ],
        'max_output_tokens' => 1000
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data['output']);

Ví dụ Vision Input

Sử dụng các mô hình hỗ trợ hình ảnh bằng cách đặt hình ảnh vào bên trong message.content dưới dạng các khối input_image. Giá trị image_url có thể là một URL công khai hoặc một URL dữ liệu Base64.

{
  "model": "gpt-5.6-terra",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Please describe this image."
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/demo.jpg"
        }
      ]
    }
  ]
}
{
  "model": "gpt-5.6-terra",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Please describe this image."
        },
        {
          "type": "input_image",
          "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
        }
      ]
    }
  ]
}

Phản hồi

Response
{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1706000000,
  "status": "completed",
  "model": "gpt-5.6-terra",
  "output": [
    {
      "id": "msg_abc123",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "Hello! How can I help you today?", "annotations": []}
      ]
    }
  ],
  "usage": {
    "input_tokens": 10,
    "output_tokens": 12,
    "total_tokens": 22
  }
}

Lỗi

Các lỗi sử dụng object error theo phong cách OpenAI. Các trường hợp phổ biến: 400 cho trường không hợp lệ hoặc mô hình không có định dạng Responses, 401 cho khóa không hợp lệ, 402 cho số dư không đủ, 404 cho previous_response_id không xác định, 429 cho giới hạn tốc độ (rate limit), và 503 khi mô hình hiện không thể phục vụ request. Xem Xử lý lỗi API.

Xác thực

BearerAuth
AuthorizationBearer <token>

Xác thực bằng Khóa API. Tạo hoặc quản lý khóa API trong Dashboard > API > API Keys.

Vị trí: header

Header

X-TokenLab-Delivery-Policy?string

Chính sách phân phối theo yêu cầu. Ghi đè các mặc định của API key và Workspace. Tự động thử TokenLab Verified trước và có thể chuyển đổi một lần sang Official chỉ trước khi xuất, chấp nhận yêu cầu hoặc tạo tài nguyên cố định.

Giá trị hợp lệ

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Khóa tùy chọn giúp ngăn chặn việc chạy lần thứ hai cho cùng một request. Gửi một giá trị duy nhất mới, chẳng hạn như UUID, cho mỗi request và giữ lại để thử lại sau khi hết thời gian chờ. Việc thử lại với cùng một khóa sẽ không chạy lại: nó trả về 409 với idempotency_replay_unavailable, hoặc thường là idempotency_conflict khi phần thân (body) thay đổi. Ngoại lệ: khi một kết quả không stream hoàn tất sau khi client ngắt kết nối, việc thử lại với cùng khóa và body trong vòng 24 giờ sẽ trả về kết quả đó (lên đến 1 MB) với header Idempotent-Replayed: true và không tính phí lần thứ hai. Khóa dài hơn 255 ký tự sẽ bị bỏ qua và request đó sẽ không có bảo vệ tính lũy đẳng (idempotency). Với background: true, việc thử lại với cùng khóa và body sẽ trả về đối tượng phản hồi gốc thay vì tạo hoặc tính phí phản hồi thứ hai; một body khác sẽ bị từ chối và mã trạng thái của nó không được đảm bảo. Xem Retry safely with an idempotency key.

Độ dài1 <= length <= 255

Nội dung yêu cầu

application/json

Phản hồi

application/json

application/json

application/json

application/json

application/json