공통 규약

이 페이지는 AGTCloud API 엔드포인트에서 공통으로 사용하는 호출 규칙을 설명합니다. 구체적인 필드, 상태 및 응답 구조는 해당 API 레퍼런스 페이지를 따릅니다.

API 주소 및 Base URL

이 페이지의 API 주소는 https://api.agtcloud.cn이며 OpenAI 호환 SDK의 Base URL은 https://api.agtcloud.cn/v1입니다.

인증

대부분의 보호된 API는 Bearer API 키를 사용합니다.

Authorization: Bearer your-api-key

Anthropic Messages는 전용 인증 Header를 사용하며 API 버전을 제공해야 합니다.

x-api-key: your-api-key
anthropic-version: 2023-06-01

anthropic-beta 등의 선택적 Header 및 기타 프로토콜의 인증 요구 사항은 해당 Endpoint 페이지를 따릅니다.

토큰을 생성하고 관리하려면 API Keys로 이동하세요. 호출할 때는 API 키만 전송하고 콘솔 비밀번호, Cookie, 관리자 토큰 또는 상위 공급업체의 키를 사용하지 마세요.

다음은 최소 Chat Completions 요청입니다.

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  --request POST \
  --header 'Authorization: Bearer your-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "안녕하세요"
      }
    ]
  }'

API 키 생성, 교체 및 운영 환경 저장 방법은 API 키, Base URL 및 인증을 참고하세요.

요청 매개변수 위치

엔드포인트 페이지는 매개변수 위치에 따라 필드를 구분하여 표시합니다.

Path 매개변수는 먼저 URL 인코딩해야 합니다. 사용하지 않는 선택적 매개변수는 생략하고 모든 선택값을 빈 문자열로 대체하지 마세요.

Content-Type 및 데이터 형식

Multipart를 사용할 때 boundary를 수동으로 고정하지 마세요. 브라우저, SDK 또는 HTTP 클라이언트가 폼 콘텐츠에 따라 전체 Content-Type을 생성하도록 해야 합니다.

모델 ID

레퍼런스 예시의 MODEL_ID는 자리표시자이며 현재 API 키로 사용할 수 있는 모델 ID로 바꿔야 합니다. 모델 목록에서 모델을 찾거나 Try It에 키를 입력한 후 해당 키가 반환하는 모델 목록을 가져올 수 있습니다.

모델, 프로토콜 및 상위 공급업체는 서로 다른 개념입니다.

• 모델 ID는 요청의 대상 모델을 결정합니다.
• Endpoint는 클라이언트가 사용할 프로토콜과 메시지 구조를 결정합니다.
• 하나의 모델이 여러 프로토콜 진입점을 제공하거나 일부 필드만 지원할 수도 있습니다.

응답 파싱

응답은 다음 순서로 처리하는 것이 좋습니다.

스트리밍 응답

SSE API는 하나의 HTTP 응답에서 여러 이벤트 또는 데이터 청크를 계속 전송합니다. 클라이언트는 연결이 닫힐 때까지 기다렸다가 전체 응답을 단일 JSON 객체로 파싱하는 대신 콘텐츠를 증분 방식으로 읽어야 합니다.

• 엔드포인트 설명에 따라 종료 이벤트 또는 종료 표시를 식별합니다.
• 콘텐츠 증분, 도구 호출, Usage 및 오류 이벤트를 각각 처리합니다.
• 네트워크가 끊기면 이미 받은 콘텐츠를 완전한 결과로 간주하지 마세요.
• 프로토콜마다 스트리밍 이벤트 구조가 다르므로 현재 엔드포인트의 이벤트 정의를 사용해야 합니다.

비동기 작업

비디오, Midjourney 등의 API는 일반적으로 작업 식별자를 먼저 반환하고 조회 API로 진행 상황과 최종 결과를 가져옵니다.

작업 제출 → 작업 ID 저장 → 상태 조회 → 종료 상태 판단 → 결과 읽기

작업 ID 필드 이름, 상태 열거값 및 조회 경로는 해당 프로토콜에서 결정합니다. 서로 다른 API 사이에서 id, task_id, video_id 또는 상태값을 혼용하지 마세요.

폴링 시 조회 간격과 전체 제한 시간을 설정하고 작업 성공, 실패 또는 취소 후에는 중지해야 합니다. 제출 요청이 시간 초과되었지만 작업이 이미 생성되었을 가능성이 있다면 먼저 작업 상태를 확인하여 유료 작업을 중복 생성하지 않도록 하세요.

HTTP 상태 및 재시도

다음은 일반적인 처리 방향입니다. 구체적인 오류 구조는 엔드포인트의 실제 응답을 따릅니다.

모든 오류에 무한 재시도하면 안 됩니다. 매개변수, 인증 및 권한 문제는 수정한 후에만 다시 전송하는 것이 적절합니다. 작업 생성처럼 부작용이 발생할 수 있는 요청은 성공적으로 제출되었는지 먼저 판단해야 합니다.

자세한 진단 단계는 오류 및 문제 해결을 참고하세요.

Usage, 시간 및 확장 필드

• Usage 필드의 존재 여부와 이름은 프로토콜과 모델에 따라 다르므로 클라이언트는 null 또는 누락을 허용해야 합니다.
• 시간 필드는 Unix 초, Unix 밀리초 또는 시간 문자열을 사용할 수 있으므로 엔드포인트 Schema에 따라 파싱해야 합니다.
• 공급업체 확장 필드는 보통 일부 모델에만 적용되므로 모든 모델의 공통 기능으로 간주하면 안 됩니다.
• 클라이언트는 응답에 새로운 비핵심 필드가 추가되는 것을 허용하여 플랫폼의 호환 필드 추가로 전체 파싱이 실패하지 않도록 해야 합니다.

보안 및 로그

• 장기간 사용하는 API 키는 신뢰할 수 있는 서버 또는 비밀 관리 시스템에 보관해야 하며 운영 프런트엔드, 데스크톱 및 모바일 클라이언트에 내장하면 안 됩니다.
• 문서의 Try It은 사용자가 직접 시작하는 임시 브라우저 테스트용입니다. 공유 기기에서는 장기간 사용하는 운영용 키를 사용하지 마세요.
• 공개 코드 저장소, 스크린샷, 로그 또는 지원 요청에 키를 기록하지 마세요.
• 문제 해결 자료에서 Prompt, 파일 주소, 계정 정보 및 요청과 응답의 민감 데이터를 제거해야 합니다.
• 사용하지 않거나 유출이 의심되는 키는 즉시 비활성화 또는 삭제하고 해당 키를 사용하는 서비스를 업데이트해야 합니다.

이어서 읽기: API 레퍼런스 · 빠른 시작 · 오류 및 문제 해결