첫 API 호출

시작 전 준비

• AI 게이트웨이 API 키

  현재 사용할 수 있는 AI 게이트웨이 API 키를 준비합니다.

• 모델 코드와 지원 엔드포인트

  에셋에 접근해 호출할 모델의 정확한 코드와 지원 API를 확인합니다.

• 실행 환경

  아래 환경 변수 설정 예제를 실행할 Bash와 cURL을 준비합니다. SDK 예제를 실행하려면 Python 또는 Node.js도 필요합니다.

키를 사용할 스페이스가 맞는지 확인하세요. 유효한 키가 있어도 보유 유닛과 호출 차단 상태, 키와 구성원의 월 한도가 요청을 제한할 수 있습니다.

API 형식 선택

OpenAI 호환 API를 사용하는 기존 코드는 base URL, API 키와 모델 코드를 게이트웨이 설정으로 바꿉니다. 요청 필드와 사용하는 기능도 선택한 모델의 지원 범위에 맞아야 합니다. 아래 예제는 Chat Completions로 텍스트 응답을 한 번에 받는 비스트리밍 호출이며, 지원 모델과 엔드포인트는 에셋에서 확인합니다.

첫 API 요청 보내기

1. 모델 코드 확인하기

   AI 게이트웨이 > 에셋에서 Chat Completions를 지원하는 모델 코드를 고릅니다. 표시된 코드를 그대로 사용하며, 공급사 접두사를 임의로 붙이거나 코드 일부를 제거하지 않습니다.

2. 키와 모델 코드를 현재 셸에 설정하기

   사용할 키가 없다면 AI 게이트웨이 > API 키에서 자신의 키를 만들고 안전한 시크릿 저장소에 보관합니다. 준비한 키와 모델 코드를 아래 Bash 명령으로 현재 셸 세션에 설정합니다. 키 입력은 화면과 셸 히스토리에 남지 않습니다. 새 터미널을 열면 다시 설정해야 합니다.

   키 값을 코드, 명령어 인수, 셸 히스토리, 브라우저 또는 모바일 앱에 직접 넣지 마세요. 아래 예제는 현재 셸의 LETSUR_API_KEY와 LETSUR_MODEL_CODE를 읽습니다.

   read -rsp "AI 게이트웨이 API 키: " LETSUR_API_KEY && printf '\n'
   read -rp "에셋의 모델 코드: " LETSUR_MODEL_CODE
   export LETSUR_API_KEY LETSUR_MODEL_CODE

3. 요청 보내기

   curl --config -는 인증 헤더를 프로세스 명령어 인수에 넣지 않고 표준 입력으로 전달합니다.

   (
     test -n "${LETSUR_API_KEY:-}" || { echo "LETSUR_API_KEY가 필요합니다." >&2; exit 1; }
     test -n "${LETSUR_MODEL_CODE:-}" || { echo "LETSUR_MODEL_CODE가 필요합니다." >&2; exit 1; }
    
     env -u LETSUR_API_KEY -u LETSUR_MODEL_CODE curl --config - <<EOF
   url = "https://gw.letsur.ai/v1/chat/completions"
   header = "Authorization: Bearer ${LETSUR_API_KEY}"
   header = "Content-Type: application/json"
   data = "{\"model\":\"${LETSUR_MODEL_CODE}\",\"messages\":[{\"role\":\"user\",\"content\":\"안녕하세요\"}]}"
   EOF
   )

성공 응답 확인

응답 본문과 usage가 보이면 첫 호출에 성공한 것입니다. 이 Chat Completions 비스트리밍 응답에서 estimated_cost는 usage 내부 필드가 아니며, 이름에는 estimated가 남아 있지만 호출별 비용 추적에 사용하는 값입니다.

SDK로 같은 요청을 보내려면 위에서 설정한 API 키와 모델 코드를 그대로 사용합니다. 서버에서 사용하는 언어에 맞는 예제를 선택해 개발 환경에서 실행하세요.

import os
 
from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ["LETSUR_API_KEY"],
    base_url="https://gw.letsur.ai/v1",
)
 
response = client.chat.completions.create(
    model=os.environ["LETSUR_MODEL_CODE"],
    messages=[{"role": "user", "content": "안녕하세요"}],
)
 
print(response.choices[0].message.content)
print(response.usage)

import OpenAI from "openai";
 
const apiKey = process.env.LETSUR_API_KEY;
const modelCode = process.env.LETSUR_MODEL_CODE;
if (!apiKey || !modelCode) {
  throw new Error("LETSUR_API_KEY와 LETSUR_MODEL_CODE가 필요합니다.");
}
 
const client = new OpenAI({
  apiKey,
  baseURL: "https://gw.letsur.ai/v1",
});
 
const response = await client.chat.completions.create({
  model: modelCode,
  messages: [{ role: "user", content: "안녕하세요" }],
});
 
console.log(response.choices[0].message.content);
console.log(response.usage);

응답 본문과 usage가 출력되면 선택한 SDK에서도 첫 호출에 성공한 것입니다.

문제 해결

표에 없는 오류이거나 같은 오류가 계속되면 오류 처리에서 type별 대응, 재시도 기준과 문의 시 전달할 정보를 확인합니다.

첫 호출 이후

선택한 모델로 실제 기능을 구현할 때는 지원 엔드포인트의 해당 명세에서 요청 필드, 스트리밍, 응답과 오류를 확인하세요. 이미 쓰는 도구에 연결하려면 외부 도구별 설정을 선택합니다. 호출 한 건의 비용을 고객 작업과 연결해 저장하려면 요청별 비용을 확인하세요.

영상 생성으로 이어가기

Seedance 모델을 사용할 수 있는 스페이스라면 영상 생성하고 파일 받기에서 작업 ID로 진행 상태를 조회하고 파일을 다운로드합니다.