Sora 비디오 생성 스킬은(는) 무엇을 하나요?
현재 프로젝트(제품 데모, 마케팅 스팟, 시네마틱 샷, UI 모형)를 위한 짧은 비디오 클립을 생성하거나 관리합니다. 기본 모델은 sora-2이며 구조화된 프롬프트 증강 워크플로를 사용하고, 결정론적 실행을 위해 번들 CLI를 선호합니다. 참고: $sora는 프롬프트의 스킬 태그이지 셸 명령어가 아닙니다.
사용 시기
- 프롬프트에서 새 비디오 클립 생성
- ID로 기존 비디오 리믹스
- 상태 확인, 작업 목록 조회, 또는 자산(비디오/썸네일/스프라이트시트) 다운로드
- 배치 실행(여러 프롬프트 또는 변형)
결정 트리 (생성 vs 리믹스 vs 상태/다운로드 vs 배치)
- 사용자가 비디오 id를 가지고 있고 변경을 원하면 → 리믹스
- 사용자가 비디오 id를 가지고 있고 상태나 자산을 원하면 → 상태/폴링/다운로드
- 사용자가 많은 프롬프트/자산을 필요로 하면 → create-batch
- 사용자가 약간의 변경(동일한 샷, 다른 주제/세부 사항)으로 두 가지 버전을 요청하면 → 기본 생성 후 변형을 위해 리믹스
- 그 외 → 생성 (또는 한 번에 준비된 자산이 필요하면 create-and-poll)
워크플로
- 의도 결정: 생성 vs 리믹스 vs 상태/다운로드 vs 배치.
- 입력 수집: 프롬프트, 모델, 크기, 초, 그리고 입력 참조 이미지.
- 배치인 경우:
tmp/아래에 임시 JSONL을 작성(한 줄에 하나의 작업)하고, 한 번 실행한 후 JSONL을 삭제합니다. - 구조화된 프롬프트를 미리 작성하는 대신 CLI 증강 플래그(
--use-case,--scene,--camera등)를 선호합니다. 이미 구조화된 프롬프트 파일을 생성했다면 이중 래핑을 방지하기 위해--no-augment를 전달합니다. - 합리적인 기본값으로 번들 CLI(
scripts/sora.py)를 실행합니다(references/cli.md참조). 긴 프롬프트의 경우 셸 이스케이프 문제를 피하기 위해--prompt-file을 선호하며, 프롬프트가 이미 구조화된 경우--no-augment와 함께 사용합니다. - 비동기 작업의 경우 완료될 때까지 폴링합니다(또는 create-and-poll 사용).
- 자산(비디오/썸네일/스프라이트시트)을 다운로드하고 로컬에 저장합니다.
- 호출 중 생성된 중간 파일(예:
prompt.txt,remix_job.json, 임시 JSONL)을 제거합니다. 샌드박스가rm을 차단하면 정리를 건너뛰거나 오류를 표시하지 않고 파일을 자릅니다. - 프롬프트당 하나의 대상 변경으로 반복합니다.
인증
- 실시간 API 호출을 위해서는
OPENAI_API_KEY가 설정되어 있어야 합니다.
키가 없는 경우 사용자에게 다음 단계를 알려줍니다.
- OpenAI 플랫폼 UI에서 API 키 생성: https://platform.openai.com/api-keys
- 시스템의 환경 변수로
OPENAI_API_KEY를 설정합니다. - 필요한 경우 OS/셸에 맞는 환경 변수 설정을 안내해 드릴 수 있습니다.
- 사용자에게 채팅에서 전체 키를 붙여넣도록 요청하지 마십시오. 로컬에서 설정하고 준비가 되면 확인하도록 요청하십시오.
기본값 및 규칙
- 기본 모델:
sora-2(더 높은 충실도를 위해sora-2-pro사용). - 기본 크기:
1280x720. - 기본 초:
4(허용: 문자열로 "4", "8", "12"). - 크기와 초는 항상 API 매개변수를 통해 설정합니다. 일반 텍스트로는 변경되지 않습니다.
- OpenAI Python SDK(
openai패키지) 사용; 원시 HTTP를 사용하지 마십시오. - 실시간 API 호출 전에
OPENAI_API_KEY가 필요합니다. - uv 캐시 권한이 실패하면
UV_CACHE_DIR=/tmp/uv-cache를 설정합니다. - 입력 참조 이미지는 jpg/png/webp여야 하며 대상 크기와 일치해야 합니다.
- 다운로드 URL은 약 1시간 후에 만료됩니다. 자산을 자신의 스토리지에 복사하십시오.
- 번들 CLI를 선호하며 사용자가 요청하지 않는 한 절대
scripts/sora.py를 수정하지 마십시오. - Sora는 오디오를 생성할 수 있습니다. 사용자가 음성 해설/오디오를 요청하면 이를
Audio:및Dialogue:줄에 명시적으로 지정하고 짧게 유지하십시오.
API 제한 사항
- 모델은
sora-2및sora-2-pro로 제한됩니다. - Sora 모델에 대한 API 액세스는 조직 확인 계정이 필요합니다.
- 지속 시간은 4/8/12초로 제한되며
seconds매개변수를 통해 설정해야 합니다. - API는
seconds를 문자열 열거형("4", "8", "12")으로 예상합니다. - 출력 크기는 모델에 따라 제한됩니다(지원되는 크기는
references/video-api.md참조). - 비디오 생성은 비동기식입니다. 다운로드 전에 완료될 때까지 폴링해야 합니다.
- 사용량 계층에 따라 속도 제한이 적용됩니다(구체적인 제한을 나열하지 마십시오).
- 콘텐츠 제한은 API에 의해 적용됩니다(아래 가드레일 참조).
가드레일 (반드시 적용)
- 18세 미만의 시청자에게 적합한 콘텐츠만 허용합니다.
- 저작권이 있는 캐릭터나 저작권이 있는 음악은 허용되지 않습니다.
- 실제 인물(공인 포함)은 허용되지 않습니다.
- 사람 얼굴이 포함된 입력 이미지는 거부됩니다.
프롬프트 증강
프롬프트를 구조화된 프로덕션 지향 명세로 재구성합니다. 암시적인 세부 사항만 명시적으로 만들고, 새로운 창의적 요구 사항을 발명하지 마십시오.
템플릿(관련 줄만 포함):
Use case: <클립이 사용될 곳>
Primary request: <사용자의 주요 프롬프트>
Scene/background: <위치, 시간대, 분위기>
Subject: <주요 주제>
Action: <단일 명확한 동작>
Camera: <샷 유형, 각도, 움직임>
Lighting/mood: <조명 + 분위기>
Color palette: <3-5가지 색상 기준>
Style/format: <영화/애니메이션/포맷 단서>
Timing/beats: <카운트 또는 비트>
Audio: <주변 음악/음성 해설(요청된 경우)>
Text (verbatim): "<정확한 텍스트>"
Dialogue:
<대화>
- Speaker: "짧은 대사."
</대화>
Constraints: <유지해야 할 것 / 피해야 할 것>
Avoid: <부정적 제약>
증강 규칙:
- 짧게 유지하고 사용자가 이미 암시했거나 다른 곳에서 제공한 세부 사항만 추가합니다.
- 리믹스의 경우 불변 항목을 명시적으로 나열합니다("동일한 샷, X만 변경").
- 중요한 세부 사항이 누락되어 성공을 방해하는 경우 질문하고, 그렇지 않으면 진행합니다.
- 구조화된 프롬프트 파일을 CLI에 전달하는 경우 도구가 다시 래핑하지 않도록
--no-augment를 추가합니다.
예시
생성 예시 (단일 샷)
Use case: product teaser
Primary request: a close-up of a matte black camera on a pedestal
Action: slow 30-degree orbit over 4 seconds
Camera: 85mm, shallow depth of field, gentle handheld drift
Lighting/mood: soft key light, subtle rim, premium studio feel
Constraints: no logos, no text
리믹스 예시 (불변 항목)
Primary request: same shot and framing, switch palette to teal/sand/rust with warmer backlight
Constraints: keep the subject and camera move unchanged
프롬프트 모범 사례 (짧은 목록)
- 샷당 하나의 주요 동작 + 하나의 카메라 움직임.
- 타이밍을 위해 카운트나 비트 사용("두 걸음, 멈춤, 돌아서기").
- UI 또는 화면 텍스트의 경우 텍스트를 짧게 유지하고 카메라는 고정.
- 아티팩트(깜빡임, 떨림, 빠른 움직임)가 나타날 때 짧은 회피 줄을 추가.
- 짧은 프롬프트는 더 창의적이고, 긴 프롬프트는 더 통제됨.
- 대화는 전용 블록에 배치하고 4-8초 클립에 맞게 줄을 짧게 유지.
- 리믹스의 경우 불변 항목을 명시적으로 명시(동일한 샷, 동일한 카메라 움직임).
- 연속성을 유지하기 위해 단일 변경 후속 작업으로 반복.
자산 유형별 지침
특정 아티팩트에 대한 요청이 있을 때 다음 모듈을 사용하십시오. 대상 템플릿과 기본값을 제공합니다.
- 시네마틱 샷:
references/cinematic-shots.md - 소셜 광고:
references/social-ads.md
CLI + 환경 참고 사항
- CLI 명령어 및 예시:
references/cli.md - API 매개변수 퀵 레퍼런스:
references/video-api.md - 프롬프트 지침:
references/prompting.md - 샘플 프롬프트:
references/sample-prompts.md - 문제 해결:
references/troubleshooting.md - 네트워크/샌드박스 팁:
references/codex-network.md
참조 맵
references/cli.md:scripts/sora.py를 통해 create/poll/remix/download/batch를 실행하는 방법.references/video-api.md: API 수준 설정(모델, 크기, 지속 시간, 변형, 상태).references/prompting.md: 프롬프트 구조 및 반복 지침.references/sample-prompts.md: 복사/붙여넣기용 프롬프트 레시피(예시만 포함, 추가 이론 없음).references/cinematic-shots.md: 영화적 샷 템플릿.references/social-ads.md: 짧은 소셜 광고 비트 템플릿.references/troubleshooting.md: 일반적인 오류 및 해결 방법.references/codex-network.md: 네트워크/승인 문제 해결.