견적과 프로토콜 호환

실시간 모델 Schema에 따라 model, input, 선택적인 callBackUrl을 request.json에 저장하세요. 견적은 작업을 생성하거나 잔액을 예약하지 않습니다. 사용자, 모델, 동일한 요청에 연결되며 5분간 유효합니다.

curl https://api.spicyapi.ai/api/v1/jobs/quote \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

estimatedCost, maxCharge, quantity는 십진수 문자열이고 currency는 USD입니다. 금액, 최대 요금, expiresAt을 표시한 뒤 사용자가 확인하면 같은 요청에 quoteId와 expectedCost를 추가하세요. 입력 변경, 만료 또는 가격 변경 시 신규 접수는 40901을 반환하므로 다시 견적과 확인을 받아야 합니다.

응답이 유실되면 원래 Idempotency-Key로 복구하세요. 새 키로 중복 작업을 만들면 안 됩니다. 이미 접수된 요청의 재실행은 견적 만료 후에도 유효합니다. 확정 요금은 recordInfo의 cost와 settled로 확인하세요. 견적이나 텍스트 종료 표시만으로 정산을 판단하지 마세요.

SDK, CLI, MCP

CLI tasks create는 견적 후 확인을 받습니다. 비대화형 실행은 명시적 --yes가 필요합니다. MCP spicyapi_task_quote는 견적만 조회합니다. spicyapi_task_create는 서명된 요청 상태에 견적을 저장하고 사용자에게 프로토콜 확인을 요청합니다. 에이전트가 대신 승인하면 안 됩니다.

spicyapi tasks quote --model "$SPICY_MODEL" --input-file input.json
spicyapi tasks create --model "$SPICY_MODEL" --input-file input.json \
  --idempotency-key "$SPICY_IDEMPOTENCY_KEY" --wait

텍스트·동영상 호환 API

OpenAI 형식의 베이스 URL은 https://api.spicyapi.ai/v1입니다. Anthropic과 Google GenAI SDK에는 베이스 URL로 https://api.spicyapi.ai를 지정하세요. /v1이나 /v1beta는 SDK가 알아서 붙입니다. 모든 호환 API는 같은 API 키를 사용하며 Authorization: Bearer 헤더에 넣습니다. Anthropic SDK가 쓰는 x-api-key와 Google GenAI SDK가 쓰는 x-goog-api-key도 받지만, URL의 ?key=는 받지 않습니다. 실시간 카탈로그에서 chat을 지원하는 정확한 모델을 선택하세요. 도구 호출, 이미지 메시지, 생성 파라미터는 모델 Schema에 따라 달라집니다. 응답은 해당 프로토콜 형식을 따르며 플랫폼 JSON 외피가 없습니다. 프로토콜별 파라미터 대응, 스트림 종료 방식, 오류 형식은 텍스트와 스트리밍을 참고하세요.

추론 텍스트를 공개하는 Chat 모델은 선택적 문자열 message.reasoning_content를 반환할 수 있으며, 스트리밍에서는 delta.reasoning_content로 전달됩니다. 도구 호출 후 대화를 이어갈 때는 실시간 모델 Schema에서 지원하는 경우 해당 assistant 메시지에 이 값을 그대로 유지할 수 있습니다. usage.completion_tokens_details.reasoning_tokens는 이미 completion_tokens에 포함된 내역이므로 다시 더하지 마세요. 모든 모델이 추론 텍스트나 token 내역을 반환하는 것은 아닙니다.

Responses의 input에는 전체 대화가 필요하며 previous_response_id는 지원하지 않습니다. Videos는 JSON의 model, prompt, input_reference, seconds, size를 변환합니다. content 엔드포인트는 단기 서명 URL로 302 리디렉션합니다. 전체 필드와 상태는 OpenAPI를 참고하세요.

견적 증빙인 quoteId와 expectedCost는 jobs/createTask와 jobs/stream에 적용됩니다. /v1과 /v1beta 호환 API는 접수 시점의 가격으로 실행합니다. 요금 상한 확인이 필요한 흐름에는 네이티브 작업 API를 사용하세요.

OpenAPI · API

공식 OpenAI 클라이언트로 스트리밍

Chat Completions는 공식 openai 클라이언트를 직접 사용합니다. @spicyapi/sdk는 네이티브 작업, 견적, 업로드를 담당합니다. openai를 별도로 설치하고 자체 서버에서 실행하세요. 현재 호출 가능한 정확한 채팅 모델 ID와 사용자 동작마다 저장한 멱등 키를 사용합니다.

npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SPICY_API_KEY,
  baseURL: "https://api.spicyapi.ai/v1",
  maxRetries: 0,
});
const signal = AbortSignal.timeout(120_000);
const stream = await client.chat.completions.create({
  model: process.env.SPICY_MODEL,
  messages: [{ role: "user", content: "Explain a rainbow in one sentence." }],
  stream: true,
  stream_options: { include_usage: true },
}, {
  signal,
  headers: { "Idempotency-Key": process.env.SPICY_IDEMPOTENCY_KEY },
});
try {
  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta.content ?? "");
    if (chunk.usage) process.stderr.write(JSON.stringify(chunk.usage) + "\n");
  }
} finally {
  stream.controller.abort();
}

중단 신호는 연결과 스트림 전체 읽기에 적용됩니다. 중단은 로컬 수신만 멈추며 접수된 작업의 취소나 환불을 보장하지 않습니다. 비스트리밍 요청은 stream: false로 설정하고 choices[0].message.content를 읽습니다. 도구 호출 조각은 index별로 합치고 전체 assistant 메시지를 보존한 뒤 해당 tool_call_id 결과를 추가하세요. 도구와 추론 필드는 모델 schema가 지원할 때만 사용합니다.

CLI와 MCP는 현재 네이티브 작업 제출과 추적을 지원하며 실시간 채팅 토큰 스트리밍은 제공하지 않습니다. 토큰별 UI에는 이 클라이언트를, 견적 확인이 필요하면 jobs/stream을 사용하세요.