API 레퍼런스

연동 기본 사항

#기본 URL

모든 엔드포인트는 이 배포의 자체 도메인 /v1 아래에 있습니다. 리전 선택은 없습니다 — 업스트림 제공업체로의 라우팅은 게이트웨이 뒤에서 이루어집니다.

#인증 헤더

Authorization: Bearer 헤더 하나면 인증이 끝납니다. 서명, 타임스탬프, 사용자별 헤더가 필요 없습니다 — 다른 게이트웨이가 Bearer 토큰 외에 요구하는 것들은 여기에 없습니다.

#오류 구조

게이트웨이 측 거부는 type이 "xiaoxiang_error"인 OpenAI 형식 오류 구조를 사용합니다. 업스트림 오류는 그대로 전달되고, 비동기 작업 엔드포인트는 평면 본문으로 응답하며, 두 가지 경우에는 본문이 아예 없습니다 — 파서를 작성하기 전에 오류 페이지를 읽어 보세요.

error.json

HTTP/1.1 402 Payment Required
X-Oneapi-Request-Id: 2026091023...

{
  "error": {
    "message": "insufficient account balance, please top up to continue (request id: 2026091023...)",
    "type": "xiaoxiang_error",
    "code": "insufficient_user_quota"
  }
}

다섯 가지 오류 구조와 오류 코드 표 →

#재시도 정책

429와 5xx는 지수 백오프로 재시도하고, Retry-After가 있으면 그 값을 따르세요. 4xx 검증 오류는 재시도하지 마세요 — 같은 본문은 다시 실패합니다. 과금되는 제출에는 Idempotency-Key를 보내세요. 그러면 타임아웃 후 재시도할 때 두 번째 작업을 시작하지 않고 첫 결과를 재전송합니다.

backoff.py

import time, requests

def call_with_backoff(url, headers, body, tries=5):
    for i in range(tries):
        r = requests.post(url, headers=headers, json=body)
        if r.status_code not in (429, 500, 502, 503, 504):
            return r
        # 429 and 413 have no JSON body — never parse before checking status.
        wait = int(r.headers.get("Retry-After", 2 ** i))
        time.sleep(wait)
    r.raise_for_status()

멱등 키 작동 방식 →

#기계 판독용 사양

같은 규약을 두 가지 형식으로 생성합니다. 클라이언트 생성, Postman 및 API 도구용 OpenAPI와, 코딩 에이전트에 붙여 넣을 단일 markdown 파일입니다. 둘 다 이 페이지들에서 다시 생성되므로 지금 읽고 있는 내용과 어긋나지 않습니다.

openapi.json

OpenAPI 3.1 — 문서화된 모든 경로와 파라미터, 오류 응답.

llms-full.txt

전체 전송 규약을 담은 markdown 파일 하나. 에이전트 컨텍스트 창에 맞는 크기입니다.

llms.txt

모든 문서 페이지의 간단한 색인. 이 파일을 먼저 가져오는 AI 클라이언트용입니다.

서버 URL이 이 도메인으로 바뀌어 있으므로, 생성한 클라이언트에 추가 설정이 필요 없습니다.

generate-a-client.sh

# Any OpenAPI generator works; this is the common one.
npx @openapitools/openapi-generator-cli generate \
  -i https://www.aisplice.store/openapi.json \
  -g python \
  -o ./gateway-client

#엔드포인트 개요

모든 경로는 OpenAI 요청 본문을 받습니다 — 제공업체별 파라미터(anthropic tool_use, gemini thinking_config)는 그대로 전달됩니다. 제공업체 네이티브 경로와 동결된 레거시 경로는 호환성 페이지에 따로 나열되어 있습니다.

텍스트
POST	/v1/chat/completions	멀티턴 채팅, 도구 호출, 스트리밍, JSON 모드.
POST	/v1/responses	구조화된 출력과 추론을 지원하는 단발성 텍스트 호출.
POST	/v1/messages	Anthropic 네이티브 형식 — 같은 인증, 어댑터 불필요.
POST	/v1/responses/compact	압축(compaction)을 지원하는 모델에서 긴 대화를 압축합니다 — 스트리밍 형식은 없습니다.
벡터
POST	/v1/moderations	같은 전송 형식의 콘텐츠 검수.
음악
POST	/v1/music/generations	비동기 음악 생성 — task_id를 반환하며 웹훅을 선택적으로 지원합니다.
GET	/v1/music/tasks/:task_id	비동기 음악 작업의 상태와 진행률을 폴링합니다.
GET	/v1/music/tasks/:task_id/content	완성된 오디오를 게이트웨이를 통해 가져옵니다.
이미지
POST	/v1/images/tasks	비동기 이미지 생성. 이미지 모델이 사용하는 경로입니다 — task_id를 반환하며 웹훅을 선택적으로 지원합니다.
GET	/v1/images/tasks/:task_id	비동기 이미지 작업의 상태와 진행률을 폴링합니다.
GET	/v1/images/tasks/:task_id/content	최종 이미지 URL 조회 — 영구 링크이므로 저장해도 안전합니다.
동영상
POST	/v1/videos	OpenAI 형식의 동영상 생성(Sora, Doubao) — 웹훅을 선택적으로 지원합니다.
GET	/v1/videos/:task_id	비동기 작업 상태를 폴링합니다. 결과물은 /content에 있습니다.
GET	/v1/videos/:task_id/content	완성된 동영상을 게이트웨이를 통해 다운로드합니다.
DELETE	/v1/videos/:task_id	아직 최종 상태에 도달하지 않은 작업을 취소합니다.
POST	/v1/videos/:video_id/remix	지원하는 모델에서 새 프롬프트로 기존 동영상을 다시 생성합니다.
3D
POST	/v1/model3d/tasks	비동기 3D 에셋 생성 및 후처리 — task_id를 반환합니다.
GET	/v1/model3d/tasks/:task_id	3D 작업을 폴링합니다. 결과 URL은 작업 본문에 담겨 오며, /content 경로는 없습니다.
미디어
POST	/v1/media/upload-policy	설정된 한도 이내의 이미지, 동영상, 오디오 또는 일반 파일용 단기 업로드 정책을 생성합니다.
앱 구독
POST	/v1/google-play/verify	이 키에 설정된 서비스 계정으로 내 앱의 Google Play 구매 토큰을 확인합니다 — 무료이며 모델을 호출하지 않습니다.
POST	/v1/xsolla/verify	이 키에 설정한 Xsolla API 키로 Xsolla 사용자에게 활성 구독이 있는지 확인합니다 — 무료, 모델 호출 없음.
계정
GET	/v1/balance	계정 잔액과 이 키로 아직 쓸 수 있는 금액 — 무료이며 모델을 호출하지 않습니다.
메타데이터
GET	/v1/models	이 키로 호출할 수 있는 모든 모델을 나열합니다.
GET	/v1/models/:model	모델 하나를 조회합니다 — Anthropic과 OpenAI 클라이언트가 시작할 때 확인하는 형식입니다.

아직 해결되지 않았나요?

요청 ID나 오류 메시지를 보내 주시면 확인해 드리겠습니다.

이전파일 업로드 다음비동기 작업