TokenLab

텍스트

응답 생성

OpenAI Responses API 형식을 사용하여 응답을 생성합니다

POST
/v1/responses

모델의 accepted_request_formats에 openai_responses가 포함되어 있을 때 이 엔드포인트를 사용하세요. 요청과 응답은 Responses API 형식을 사용하며 변환되지 않습니다. 해당 형식을 지원하지 않는 모델은 여기서 400을 반환하므로 대신 Chat Completions을 사용하세요. 선택 필드 및 지원되는 값은 선택한 모델에 따라 다릅니다.

요청 본문

modelstring필수

사용할 모델의 ID입니다. 사용 가능한 옵션은 모델을 참조하세요.

inputstring | array

응답을 위한 입력입니다. 요청에서 재사용 가능한 prompt를 대신 사용하거나 previous_response_id로 저장된 응답을 이어가는 경우에는 선택 사항입니다.

각 항목은 type을 가진 객체입니다. 일반적인 유형은 다음과 같습니다:

  • message: role과 content를 포함하는 대화 메시지
  • function_call: 함수 호출 요청
  • function_call_output: 함수 호출의 출력
  • reasoning: 이전 응답의 생각(thinking) 항목입니다. 변경 없이 그대로 다시 전송하세요

기타 항목 유형은 선택한 모델에 따라 다릅니다.

멀티모달 입력의 경우 message.content는 일반 문자열 또는 콘텐츠 블록의 배열일 수 있습니다. 이미지를 지원하는 모델의 경우, URL 또는 Base64 문자열을 일반 텍스트에 직접 포함하는 대신 이미지를 input_image 블록으로 전달하세요.

콘텐츠 블록 예시:

  • { "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

모델을 위한 시스템 지침입니다(시스템 메시지와 동일).

max_output_tokensinteger

생성할 최대 토큰 수입니다.

temperaturenumber

샘플링 온도입니다. 지원되는 값과 기본값은 선택한 모델에 따라 다릅니다.

toolsarray

모델이 호출할 수 있는 도구 목록입니다. 지원되는 유형 및 조합은 선택한 모델에 따라 다릅니다.

streamboolean기본값: false

true인 경우 이벤트 스트림을 반환합니다. 스트리밍을 참조하세요.

previous_response_idstring

대화를 이어갈 이전 응답의 ID입니다. 해당 응답은 사용자 계정에 속해 있어야 하며 계속 저장되어 있어야 합니다. 그렇지 않으면 요청 시 response_not_found 코드와 함께 404가 반환됩니다. 해당 응답을 생성했던 모델로 계속 진행하세요. 응답을 생성했던 서비스를 일시적으로 사용할 수 없는 경우 요청 시 503이 반환될 수 있습니다.

storeboolean기본값: true

나중에 조회하거나 previous_response_id에 사용하기 위해 응답을 저장할지 여부입니다. false인 경우 TokenLab은 응답을 보관하지 않으며, GET /v1/responses/{id}로 이를 반환할 수 없습니다.

backgroundboolean기본값: false

비동기 실행을 요청합니다. 지원 여부는 선택한 모델에 따라 다릅니다. 생성 호출은 즉시 반환되며, 대개 status가 queued 또는 in_progress 상태입니다. status가 completed, incomplete, failed, cancelled 중 하나가 될 때까지 응답 조회를 폴링하세요. 백그라운드 처리를 일시적으로 사용할 수 없는 동안에는 백그라운드 요청 시 503이 반환될 수 있습니다.

tool_choicestring | object

auto, none, required 또는 단일 도구를 지정하는 객체와 같은 도구 선택 정책입니다. 지원되는 값은 선택한 모델에 따라 다릅니다.

includearray

선택한 모델이 지원할 때 반환할 추가 출력 섹션입니다.

stream_optionsobject

스트리밍 옵션입니다. 선택한 모델이 지원하는 경우 include_obfuscation이 전달됩니다.

truncationstring

선택한 모델이 지원할 때 긴 대화에 대한 잘라내기(truncation) 전략입니다.

service_tierstring

TokenLab은 Responses 요청을 표준 서비스 티어로 제공하고 청구합니다. auto 및 default가 허용됩니다. flex 또는 priority와 같은 기타 값은 요청에서 제거되며 표준 요금으로 청구됩니다.

promptobject

재사용 가능한 프롬프트 템플릿 및 변수에 대한 참조입니다.

metadataobject

응답과 함께 저장되는 커스텀 메타데이터입니다.

textobject

텍스트 출력 설정입니다. text.format 지원 여부는 선택한 모델에 따라 다릅니다.

parallel_tool_callsboolean

선택한 모델이 지원할 때 여러 도구 호출을 병렬로 허용할지 여부입니다.

top_pnumber

핵 샘플링(Nucleus sampling) 파라미터(0-1)입니다.

reasoningobject

effort를 포함한 추론(reasoning) 옵션은 선택한 모델에 따라 다릅니다.

응답

idstring

응답의 고유 식별자입니다.

objectstring

항상 response입니다.

created_atinteger

응답이 생성된 시점의 Unix 타임스탬프입니다.

statusstring

응답 상태: queued, in_progress, completed, incomplete, failed, cancelled 중 하나입니다. HTTP 요청이 성공하더라도 이 필드를 확인하세요.

outputarray

모델이 생성한 출력 항목 목록입니다.

usageobject

토큰 사용량 통계입니다.

관련 엔드포인트

  • GET /v1/responses/{id}: 저장된 응답을 조회합니다.
  • DELETE /v1/responses/{id}: 저장된 응답을 삭제합니다. 생성을 취소하지는 않습니다.
  • POST /v1/responses/compact: 대화를 압축하고 response.compaction 객체를 반환합니다.
  • wss://api.tokenlab.sh/v1/responses: WebSocket을 통해 응답을 생성합니다. 스트리밍을 참조하세요.
  • Cancel, input-items, input-tokens 엔드포인트는 현재 지원되지 않습니다.

요청

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']);

비전 입력 예시

이미지 지원 모델을 사용할 때는 message.content 내에 이미지를 input_image 블록으로 배치합니다. image_url 값은 공개 URL 또는 Base64 데이터 URL일 수 있습니다.

{
  "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..."
        }
      ]
    }
  ]
}

응답

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
  }
}

오류

오류는 OpenAI 스타일의 error 객체를 사용합니다. 일반적인 경우: 유효하지 않은 필드이거나 Responses 형식을 지원하지 않는 모델인 경우 400, 유효하지 않은 키인 경우 401, 잔액 부족인 경우 402, 알 수 없는 previous_response_id인 경우 404, 요청 속도 제한(rate limit) 초과인 경우 429, 모델이 현재 요청을 처리할 수 없는 경우 503이 반환됩니다. 자세한 내용은 API 오류 처리를 참조하세요.

인증

BearerAuth
AuthorizationBearer <token>

API 키 인증입니다. Dashboard > API > API Keys에서 API 키를 생성하거나 관리하십시오.

위치: header

헤더

X-TokenLab-Delivery-Policy?string

요청별 전송 정책입니다. API 키 및 Workspace 기본값을 재정의합니다. 자동으로 TokenLab Verified를 먼저 시도하며, 출력, 요청 수락 또는 영구 리소스 생성 전에 Official 전용으로 한 번 전환될 수 있습니다.

허용 값

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

동일한 요청이 두 번 실행되는 것을 방지하는 선택적 키입니다. 각 요청마다 UUID와 같은 새로운 고유 값을 전송하고, 타임아웃 후 재시도 시에도 동일한 값을 유지하십시오. 동일한 키로 재시도하면 다시 실행되지 않으며, 409 코드와 idempotency_replay_unavailable 또는 본문이 변경된 경우 일반적으로 idempotency_conflict를 반환합니다. 예외: 클라이언트 연결이 끊긴 후 스트리밍되지 않는 결과가 완료된 경우, 24시간 이내에 동일한 키와 본문으로 재시도하면 Idempotent-Replayed: true 헤더와 함께 해당 결과(최대 1MB)를 반환하며 추가 요금이 부과되지 않습니다. 255자를 초과하는 키는 무시되며, 해당 요청은 멱등성(idempotency) 보호를 받지 못합니다. background: true 설정 시, 동일한 키와 본문으로 재시도하면 원본 응답 객체를 반환하며 두 번째 응답을 생성하거나 과금하지 않습니다. 본문이 다르면 거부되며 상태 코드는 보장되지 않습니다. 멱등성 키를 사용한 안전한 재시도를 참조하십시오.

길이1 <= length <= 255

요청 본문

application/json

응답

application/json

application/json

application/json

application/json

application/json