텍스트 대화

POST /v1/chat/completions

텍스트 모델을 호출합니다. 이미지·영상과 달리 이 엔드포인트는 동기입니다. 한 번의 왕복으로 결과가 오며 폴링이 필요 없습니다. 요청과 응답은 스트리밍까지 포함해 OpenAI 의 chat/completions 형태를 따르므로 OpenAI SDK는 baseURL만 바꾸면 그대로 동작합니다.

요청 파라미터

파라미터	타입	설명
model	string	필수. /v1/models 에서 type=text 인 항목의 id
messages	object[]	필수. 각 항목은 {role, content}. role 은 system \| user \| assistant. 요청당 최대 64개
stream	boolean	선택. true 면 SSE 증분 응답으로 전환. 기본 false 는 한 번에 반환
temperature	number	선택. 상위 모델로 그대로 전달
top_p	number	선택. 그대로 전달
max_tokens	integer	선택. 그대로 전달
stop	string\|string[]	선택. 그대로 전달
presence_penalty / frequency_penalty	number	선택. 그대로 전달

model 은 필수이며 기본값이 없습니다. 텍스트 모델은 어투·길이·가격이 크게 달라, 조용히 하나를 골라 주는 것은 당신이 모르는 결정을 대신 내리는 셈이기 때문입니다.

요청 예시

bash

curl https://open.pikpikgo.com/v1/chat/completions \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-fast-1",
    "messages": [
      { "role": "system", "content": "당신은 숏드라마에 능한 각본가입니다." },
      { "role": "user", "content": "도시 미스터리 단편의 도입부를 세 문장 이내로 써 주세요." }
    ]
  }'

응답 예시

json

{
  "id": "chatcmpl-2608102214300000123456",
  "object": "chat.completion",
  "created": 1786372470,
  "model": "text-fast-1",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "한밤중 엘리베이터가 13층에 멈췄다. 이 건물은 12층까지밖에 없는데." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 38, "completion_tokens": 126, "total_tokens": 164 },
  "credits": 4
}

항목	설명
choices[0].message.content	모델 응답 본문
choices[0].finish_reason	stop 정상 종료 \| length max_tokens 도달
usage	토큰 수. 텍스트는 토큰 과금이므로 이것이 과금 근거
credits	실제로 차감된 크레딧 (OpenAI 표준 항목 아님)

텍스트는 호출 횟수가 아니라 토큰으로 과금합니다. 크레딧 = 입력 토큰 × 입력 단가 + 출력 토큰 × 출력 단가이며, 올림 처리하고 호출당 최소 1포인트입니다. 단가는 100만 토큰 기준으로 요금 페이지에 표기됩니다.

스트리밍 응답

stream: true 를 넣으면 응답이 text/event-stream 으로 바뀌고 chat.completion.chunk 가 차례로 내려옵니다. 첫 프레임은 role 만 선언하고, 본문은 한 프레임에 한 조각씩, 그다음 finish_reason 프레임, 마지막에 choices 가 빈 배열이고 usage 와 credits 를 담은 프레임이 오며 data: [DONE] 으로 끝납니다.

bash

curl -N https://open.pikpikgo.com/v1/chat/completions \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-fast-1",
    "messages": [
      { "role": "user", "content": "도시 미스터리 단편의 도입부를 세 문장 이내로 써 주세요." }
    ],
    "stream": true
  }'

text

data: {"id":"chatcmpl-2608102214300000123456","object":"chat.completion.chunk","created":1786372470,"model":"text-fast-1","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-2608102214300000123456","object":"chat.completion.chunk","created":1786372470,"model":"text-fast-1","choices":[{"index":0,"delta":{"content":"한밤중 엘리"},"finish_reason":null}]}

data: {"id":"chatcmpl-2608102214300000123456","object":"chat.completion.chunk","created":1786372470,"model":"text-fast-1","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-2608102214300000123456","object":"chat.completion.chunk","created":1786372470,"model":"text-fast-1","choices":[],"usage":{"prompt_tokens":38,"completion_tokens":126,"total_tokens":164},"credits":4}

data: [DONE]

OpenAI 공식 SDK를 쓰면 SSE 를 직접 파싱할 필요가 없습니다:

javascript

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.PIKPIK_API_KEY,
  baseURL: 'https://open.pikpikgo.com/v1',
})

// 스트리밍: 프레임 단위로 증분을 받고, 마지막 프레임에 usage 와 차감 크레딧이 담긴다
const stream = await client.chat.completions.create({
  model: 'text-fast-1',
  messages: [{ role: 'user', content: '도시 미스터리 단편의 도입부를 세 문장 이내로 써 주세요.' }],
  stream: true,
})

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '')
}

스트리밍 과금 근거는 마지막 프레임의 usage 입니다. 상위에서 usage 를 주지 않으면 최소 1포인트로 과금합니다. 또한 프레임이 흐르기 시작한 순간 HTTP 는 이미 200이므로 중간 실패가 4xx/5xx 로 바뀔 수 없습니다. 스트림 안의 {"error": {...}} 프레임으로 전달되고 이어서 평소처럼 [DONE] 으로 끝나니, 읽는 쪽에서 이 프레임도 함께 판별하세요.