Beta

파일 생성

POSThttps://api.youvico.com/api/projects/:id/files/upload.generate
MCP 도구
미지원
요청 제한
Tier 2
API 권한
ai:generate
프로젝트 역할
소유자관리자멤버

선택한 생성 모드로 AI 파일을 생성합니다.

  • AUTO는 프롬프트와 첨부를 분석해 생성 방식을 자동으로 정합니다. configs에 지정한 출력 설정은 그대로 사용합니다.
  • ADVANCED는 보낸 프롬프트와 configs대로 생성합니다. 첨부는 모두 configs의 첨부 칸에 지정합니다.

ADVANCED에서 모델 규칙상 사용할 수 없는 첨부가 있으면, 에러 응답의 error.details.attachment.id에 그 첨부의 ID를, error.details.reason에 사유를 담아 반환합니다.

API 키나 연결이 속한 워크스페이스의 프로젝트에서만 사용할 수 있습니다. 다른 워크스페이스가 연결한 프로젝트에서는 사용할 수 없습니다.

참고

AI 생성 결과를 확인하려면 status가 UPLOADED(성공) 또는 FAILED(실패)가 될 때까지 파일 조회를 반복해서 호출합니다. 진행 상태와 실패 사유는 AI 작업 조회로 확인합니다.

예시

curl -X POST 'https://api.youvico.com/api/projects/bdbff5de-96d7-468f-9db0-85fe28bd6b62/files/upload.generate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "mode": "ADVANCED", "output": { "type": "VIDEO", "model": "kling-3.0" }, "prompt": "The camera slowly pushes in as the sneaker turns on a turntable.", "folder": { "id": "DX1234567890ABCD" }, "attachments": [{ "id": "GA1234567890ABCD" }], "configs": { "start": "GA1234567890ABCD", "durationSeconds": 10 } }'
{
  "data": {
    "id": "FXABCDEFGHIJKLMN"
  }
}
요청
curl -X POST 'https://api.youvico.com/api/projects/bdbff5de-96d7-468f-9db0-85fe28bd6b62/files/upload.generate' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"mode": "ADVANCED",
"output": {
"type": "VIDEO",
"model": "kling-3.0"
},
"prompt": "The camera slowly pushes in as the sneaker turns on a turntable.",
"folder": {
"id": "DX1234567890ABCD"
},
"attachments": [
{
"id": "GA1234567890ABCD"
}
],
"configs": {
"start": "GA1234567890ABCD",
"durationSeconds": 10
}
}'
응답202 Accepted
{
  "data": {
    "id": "FXABCDEFGHIJKLMN"
  }
}

요청

경로

idstringrequired
프로젝트 ID

본문

modestringrequired
생성 모드

가능한 값: AUTOADVANCED

예시: ADVANCED

outputobjectrequired
출력 형식과 모델
output.typestringrequired
출력 형식

가능한 값: PDFMARKDOWNIMAGEVIDEO3DMUSICTTSSTT

예시: VIDEO

output.modelstringrequired
output.type의 모델 ID. 아래 모델 참고

예시: kling-3.0

promptstringrequired

0-20000 characters

생성 프롬프트

예시: The camera slowly pushes in as the sneaker turns on a turntable.

folderobject?required
대상 폴더. null이면 프로젝트 루트
folder.idstringrequired
폴더 ID

예시: DX1234567890ABCD

attachmentsarrayrequired

0-50 items, unique IDs

참고 파일
attachments[].idstringrequired
프로젝트 파일 ID(FX) 또는 AI 생성 첨부 ID(GA)

예시: GA1234567890ABCD

configsobject
설정. 모델의 모드별 스키마를 따라야 함

참고

ADVANCED는 attachments의 ID를 모두 configs의 첨부 칸에 지정해야 하며, 첨부 칸에 다른 ID를 지정할 수 없습니다.

응답

202 Accepted를 반환합니다.

dataobject
생성 중인 파일
data.idstring
생성된 파일 ID

예시: FXABCDEFGHIJKLMN

모델

모델 목록이 모델별 설정 스키마를 반환합니다. 문서 모델(PDF, MARKDOWN)과 음성 모델(TTS, STT)은 ADVANCED만 지원합니다.

출력 형식모델
PDFclaude-fable-5-2, claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5, gpt-6.2-astra, gpt-6-astra, gpt-6.2-sol, gpt-6.1-sol, gpt-6.1-terra, gpt-6-luna, gemini-4-carbon, gemini-4-argon, gemini-4-neon, gemini-4-hydrogen, gemini-3.8-flash
MARKDOWNclaude-fable-5-2, claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5, gpt-6.2-astra, gpt-6-astra, gpt-6.2-sol, gpt-6.1-sol, gpt-6.1-terra, gpt-6-luna, gemini-4-carbon, gemini-4-argon, gemini-4-neon, gemini-4-hydrogen, gemini-3.8-flash
IMAGEgpt-image-2.6-flare, gpt-image-2.6-sunburst, gpt-image-2.5-flare, gpt-image-2.5-sunburst, gemini-nano-banana-2.1, gemini-3-pro-image, gemini-3.1-flash-image, gemini-3.1-flash-lite-image, seedream-5.5
VIDEOkling-4.0, kling-4.0-omni, seedance-2.5, seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, kling-3.0, kling-3.0-omni, kling-3.0-turbo, minimax-h3-max, minimax-h3, wan-3.0, wan-3.0-prime, gemini-omni-flash, veo-3.1-generate-preview, veo-3.1-lite-generate-preview
3Dmeshy-7.1, hunyuan3d-3.1
MUSIClyria-3.5
TTSeleven-v4, eleven-v4-turbo
STTmai-transcribe-2, nemotron-3.5-transcribe

설정

받는 값과 기본값은 모델별 스키마에 있습니다. AUTO에서 보내지 않은 설정은 YouViCo가 정하고, ADVANCED에서는 기본값을 사용합니다.

설정설명
effort생각 수준. 높을수록 오래 생각함
aspectRatio화면 비율. adaptive는 입력 이미지·동영상의 비율을 따름
resolution출력 해상도
quality이미지 품질
complexity이미지 구상 연산량. 품질과 별개
outputFormat이미지·오디오·텍스트 파일 형식
transparent투명 배경 여부. outputFormat이 jpeg이면 false만 가능
durationSeconds출력 길이(초)
generateAudio소리 생성 여부
shouldTexture텍스처 적용 여부
voiceTTS 목소리 ID. 추천 목록은 스키마의 x-voices
diarizeSTT 화자 구분 여부

MUSIC 모델의 설정은 outputFormat뿐입니다. ADVANCED에서는 가사, 길이, 템포, 조성을 프롬프트에 작성합니다.

TTS는 프롬프트를 읽은 음성을 생성합니다. STT는 audio 칸의 오디오를 받아 적으며, 프롬프트는 빈 문자열로 보냅니다.

첨부 칸

첨부 칸은 ADVANCED 스키마에만 있습니다. 모델별 칸과 칸 사이의 규칙은 각 모델의 스키마에서 확인할 수 있습니다.

칸설명
references참조 이미지·동영상·오디오·문서
start, end시작·끝 프레임 이미지
middle시작·끝 프레임 사이에 시간 순서대로 넣는 중간 프레임 이미지. start 필수
edit편집할 동영상. 출력 길이와 비율은 이 동영상을 따름
extenddurationSeconds만큼 연장할 동영상
motion모션 컨트롤. image와 video 필수
audioSTT로 받아 적을 오디오
images3D 입력 이미지. hunyuan3d-3.1은 시점을 키로 한 객체이며 front 필수

일부 동영상 모델은 결과에서 피할 내용인 negativePrompt와, 합계가 출력 길이와 같은 prompt·seconds 목록인 멀티 샷 shots도 받습니다.