API Key 환경변수 설정

이 문서는 Wiki의 TC3 호출 스크립트에 맞춘 설정입니다. TENCENT_SECRET_ID와 TENCENT_SECRET_KEY는 Tencent Cloud 계정 키이며, 텍스트 게이트웨이의 API_TOKEN과 다릅니다.

계정 키와 리전

macOS·Linux 터미널에서 실행합니다. 각 export는 별도 줄에 입력합니다.

export TENCENT_SECRET_ID='<SecretId>'
export TENCENT_SECRET_KEY='<SecretKey>'
export TENCENT_REGION='ap-singapore'

SDK나 tccli의 환경변수 이름은 다를 수 있습니다. 이 스크립트는 위 세 이름을 읽습니다. API 경로와 리전은 사용할 서비스의 API Reference를 기준으로 선택합니다.

호출 스크립트 준비

Python 3를 설치한 뒤 tencent-api.py를 작업 폴더에 저장합니다. 추가 패키지는 필요하지 않습니다. 모델 페이지의 요청 예시를 request.json으로 저장합니다.

python3 --version
python3 -m json.tool request.json > /dev/null

첫 요청 실행

MPS 이미지 요청 예시입니다. 영상은 CreateAigcVideoTask, 음악은 CreateAigcAudioTask를 사용합니다.

python3 tencent-api.py mps CreateAigcImageTask request.json > accepted.json

VOD를 사용한다면 VOD 모델 페이지의 JSON을 사용하고 SubAppId를 실제 Application ID로 지정합니다.

python3 tencent-api.py vod CreateAigcImageTask request.json > accepted.json

두 명령은 각각 새 생성 작업을 접수합니다. 사용할 경로 하나만 실행하세요. 서명은 실행 시점의 시각과 본문으로 자동 계산됩니다.

TaskId로 결과 조회

접수 응답의 Response.TaskId로 조회 JSON을 만듭니다.

python3 - <<'PYTHON'
import json
with open('accepted.json') as f:
    response = json.load(f)['Response']
if 'Error' in response:
    raise SystemExit(response['Error'])
with open('query.json', 'w') as f:
    json.dump({'TaskId': response['TaskId']}, f)
PYTHON
python3 tencent-api.py mps DescribeAigcImageTask query.json

MPS 영상은 DescribeAigcVideoTask, 음악은 DescribeAigcAudioTask를 사용합니다. VOD는 query.json에 생성 요청과 같은 SubAppId를 추가한 뒤 vod DescribeTaskDetail로 조회합니다.

완료 판정과 파일 보관

경로	완료 판정	결과 보관
MPS AIGC	DONE이면 결과 확인, FAIL이면 실패 원인 확인	임시 URL 만료 전에 다운로드하거나 StoreCosParam으로 COS 저장
VOD AIGC	FINISH와 ErrCode=0을 함께 확인	Temporary는 임시 URL, Permanent는 VOD FileId

아직 처리 중이면 잠시 후 같은 TaskId로 조회합니다. 조회가 늦다고 생성 요청을 다시 보내면 별도 작업이 생길 수 있습니다. 실제 결과 필드는 MPS·VOD 응답 예시를 확인하세요.

텍스트 모델 인증

VOD Text에서 발급한 토큰을 별도로 설정합니다.

export API_TOKEN='<VOD API Token>'
curl https://mmu.vod-qcloud.com/v1/models \
  -H "Authorization: Bearer ${API_TOKEN}"

오류 확인

현상	확인할 항목
AuthFailure	키, CAM 권한, 로컬 시각, API 경로
InvalidParameter	모델·버전별 필드, JSON 타입, 입력 URL
RequestLimitExceeded	호출 속도를 낮추고 대기 후 재시도
생성 응답을 받기 전 timeout	중복 생성을 피하도록 접수 여부와 로그 확인