프롬프트용 LLM API: 코드에서 작성하고 다듬기
이 가이드는 하나의 호출에서 수천 개의 배치에 이르기까지 다른 도구를 위한 프롬프트를 작성, 확장 및 다시 작성하는 방법을 보여줍니다.
업데이트

주요 포인트
- 하나의 채팅 호출이 거친 아이디어를 완성된 프롬프트로 바꿉니다. 모델 ID는 uncensored입니다.
- JSON 모드는 스크립트가 저장하고 검색할 수 있는 필드를 반환합니다.
- 전용 키는 동시에 8개의 요청을 처리하며 분당 300개의 요청을 처리합니다. 429 오류 발생 시 Retry-After 헤더를 사용하여 재시도합니다.
- API는 텍스트만 작성합니다. 프롬프트를 비디오 또는 이미지 도구에 붙여넣으세요.
프롬프트 작업에서 LLM API의 역할
프롬프트용 LLM API는 프롬프트 작업에서 사람을 지치게 하는 부분, 즉 세 단어의 아이디어를 완전한 설명으로 바꾸거나, 같은 장면에 대한 10가지 변형을 작성하거나, 프롬프트를 하우스 형식에 맞게 다시 작성하는 작업에 뛰어납니다. 거친 아이디어와 규칙 세트를 보내면 완성된 프롬프트 텍스트를 받습니다. 엔드포인트가 OpenAI 호환이므로 코드는 다른 모델에 대해 작성할 채팅 호출과 동일합니다.
먼저 한계부터 말씀드립니다. 이 서비스는 텍스트만 반환합니다. 비디오, 이미지 또는 오디오를 렌더링하지 않습니다. 텍스트-비디오 도구의 클립을 만드는 것이 최종 목표라면 API가 프롬프트를 작성하고, 해당 프롬프트를 사용하는 생성기로 붙여넣거나 파이프하세요. 프롬프트 작성은 느리고 반복적인 단계이며 텍스트 토큰이 저렴하므로 이 분리 자체만으로도 유용합니다.
이 모델은 합법적인 성인 용도를 위해 콘텐츠 거부 없이 답변하도록 튜닝된 오픈 웨이트 모델로, 어두운 스릴러 장면이나 폭력적인 판타지 전투에 대한 프롬프트 작성 작업이 강의식 거부로 돌아가지 않습니다. 유일한 하드 제한은 성 콘텐츠에 미성년자가 포함된 것이 생성되지 않는다는 것입니다.
Python으로 첫 프롬프트 작성 호출하기
pip install openai로 SDK를 설치하고 base URL을 가리키게 하세요. 모델 ID는 uncensored이며, 키는 SDK가 처리하는 Bearer 토큰으로 입력됩니다.
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
SYSTEM = (
"You write prompts for a text-to-video tool. "
"Given a rough idea, reply with one prompt of 60 to 90 words. "
"Name the subject, the camera movement, the lighting and the mood. "
"Reply with the prompt only, no preamble."
)
def expand(idea: str) -> str:
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": SYSTEM},
{"role": "user", "content": idea},
],
temperature=0.8,
max_tokens=300,
)
return resp.choices[0].message.content.strip()
print(expand("a lighthouse during a storm, seen from a drone"))
세 가지 세부 사항이 첫 시도보다 더 잘 작동하게 합니다. 시스템 메시지는 길이와 모든 프롬프트가 명시해야 하는 요소를 정의하므로 출력이 비교 가능하게 유지됩니다. temperature을 약 0.8로 설정하면 아이디어에서 벗어나지 않으면서 실행 간 다양성을 제공합니다. 그리고 max_tokens은 여기서는 선택 사항이지만 300의 제한은 말이 많은 응답이 불필요하게 비싸지는 것을 막습니다. 생략하면 완성이 100,000토큰 창에 남은 모든 것을 사용할 수 있습니다.
하나의 아이디어로 10번 시도하려면 같은 설정으로 반복하지 마세요. 호출마다 seed를 다르게 하거나, 한 번의 응답으로 10개 프롬프트를 요청한 뒤 코드에서 분할하세요. 지시문이 한 번만 전송되므로 후자가 더 저렴합니다.
JSON 모드로 구조화된 프롬프트 반환하기
자유 텍스트는 인간에게는 괜찮습니다. 스크립트가 출력을 소비할 때는 필드가 필요합니다. JSON 모드는 응답을 유효한 JSON 객체로 만들어, 깨지기 쉬운 파서를 작성하지 않고도 프롬프트, 제외하려는 요소 및 일부 태그를 읽을 수 있습니다. 시스템 메시지에 JSON 단어와 기대하는 키를 언급하고 response_format을 설정하세요.
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
import json
resp = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{
"role": "system",
"content": (
"Return a JSON object with the keys prompt (string), "
"avoid (string) and tags (list of at most five short strings)."
),
},
{"role": "user", "content": "a night market in the rain, handheld camera"},
],
)
data = json.loads(resp.choices[0].message.content)
print(data["prompt"])
print(data["tags"])
텍스트뿐만 아니라 객체를 저장하세요. 아이디어, 최종 프롬프트, 태그 및 날짜에 대한 열이 있는 테이블은 나중에 자신의 기록을 검색할 수 있게 하며, 어떤 지시사항이 유지한 프롬프트를 생성했는지 쉽게 확인할 수 있습니다.
JSON이 포착하지 못하는 형식을 따라야 할 때(예: 레이블이 붙은 줄의 고정 순서)에는 시스템 메시지에 구체적인 예시 하나를 포함해 명시하세요. 모델은 추상적인 설명보다 예시를 더 안정적으로 따릅니다.
인터랙티브 도구를 위해 결과 스트리밍하기
사람이 결과를 기다리는 경우(예: 내부 프롬프트 도구 또는 채팅 패널), 첫 단어가 즉시 나타나도록 답변을 스트리밍하세요. stream: true을 설정하면 응답이 서버 전송 이벤트로 도착하고 스트림 끝에 사용량이 보고됩니다.
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
stream = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "Rewrite the user's prompt to be more specific about camera and light."},
{"role": "user", "content": "a man walking through a foggy forest"},
],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
print()
스트리밍된 요청은 스트림이 끝날 때까지 동시성 슬롯을 유지한다는 점을 기억하세요. 전용 키는 동시에 8개 요청을 허용하므로, 동시에 느린 스트림을 읽는 8명의 사용자가 아홉 번째 사용자를 차단할 수 있습니다. 작은 내부 도구에는 충분하지만, 공개적인 서비스의 경우 서버 측에서 요청을 큐에 넣으세요.
속도 제한 내에서 배치 실행하기
가장 많은 시간을 절약해주는 프롬프트 작성 작업은 배치입니다: 500개의 제품 샷, 스크립트에서 200개의 장면 아이디어, 거친 줄의 전체 스프레드시트 등. 전체 키는 동시에 8개 요청과 분당 300개 요청을 허용하며, 체험 키는 각각 2개와 60개를 허용합니다. 키에 맞춰 조정된 스레드 풀이 두 제한치 내에 머무르는 가장 간단한 방법입니다.
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
import time
from concurrent.futures import ThreadPoolExecutor
from openai import RateLimitError
SYSTEM = "Turn the idea into one 60 to 90 word video prompt. Reply with the prompt only."
def expand(idea: str) -> str:
for attempt in range(4):
try:
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": SYSTEM},
{"role": "user", "content": idea},
],
max_tokens=300,
)
return resp.choices[0].message.content.strip()
except RateLimitError as err:
wait = int(err.response.headers.get("Retry-After", "5"))
time.sleep(wait)
raise RuntimeError("gave up on: " + idea)
ideas = ["a paper boat in a gutter", "a train crossing a salt flat", "a chef plating dessert"]
with ThreadPoolExecutor(max_workers=8) as pool:
prompts = list(pool.map(expand, ideas))
for idea, prompt in zip(ideas, prompts):
print(idea, "->", prompt[:80])
429는 두 가지 의미를 가질 수 있습니다. 오류 코드 rate_limited은 분당 요청 수를 초과했음을 의미하며, concurrency은 동시에 실행된 요청이 너무 많음을 의미합니다. 일시적인 과부하도 Retry-After: 5 헤더와 함께 429를 반환합니다. 위의 루프는 헤더가 가리키는 시간만큼 기다렸다가 다시 시도합니다. 실패하거나 거부된 요청은 요금이 부과되지 않으므로 재시도로 비용이 두 배가 되지 않습니다.
완료된 프롬프트마다 한 줄씩 작성하며 진행 중인 결과를 디스크에 기록하세요. JSON-lines 파일이 적합합니다: 각 줄에 아이디어, 프롬프트 및 시간이 포함된 객체를 저장하면, 다시 시작할 때 이미 완료된 작업을 건너뛸 수 있습니다. 수천 건의 호출로 이루어진 배치는 결국 일시적인 네트워크 문제를 겪게 되며, 처음부터 다시 시작하고 싶지 않을 것입니다.
스타일 가이드를 100k 컨텍스트 창에 넣기
모델이 규칙을 알면 프롬프트가 더 좋아집니다. 100,000토큰 창(프롬프트 + 완성)으로 시스템 메시지에 많은 것을 넣을 수 있습니다: 스타일 가이드, 금지된 구문 목록, 20개의 승인된 예시 프롬프트 및 팀이 카메라 움직임을 명명하는 방식의 어휘집.
그 공간을 의도적으로 사용하고, 모델은 작성된 내용을 따르므로 새로운 동료에게 지시하듯 규칙을 작성한다는 점을 명심하세요. 50개의 혼합된 예시보다 5개의 훌륭한 예시가 더 나은 이유는 모델이 본 것의 평균을 내기 때문입니다. 원하는 형식과 동일한 형식으로 예시를 배치하세요. 프로젝트에 반복되는 캐릭터가 있다면, 머리카락, 의상 및 나이(성인 캐릭터만)가 고정된 어조로 기술된 캐릭터 시트를 한 번 작성하고, 모델이 해당 단어를 모든 프롬프트에 그대로 복사하도록 지시하세요. 이는 가장 저렴한 일관성 트릭입니다: 동일한 구문이 모든 프롬프트에 나타나므로 하류의 생성기가 매번 동일한 설명을 보게 됩니다.
긴 지시문은 각 호출마다 다시 전송되므로 각 호출마다 요금이 부과됩니다. 백만 입력 토큰당 $0.15의 가격으로 3,000 토큰의 스타일 가이드는 입력만으로도 요청당 $0.00045의 비용이 발생합니다. 이는 작은 금액이지만 10,000건의 요청에 걸쳐서는 $4.50이 되므로, 작동이 확인되면 가이드를 줄이세요. 가격 책정 페이지에서 자체 계산을 위한 전체 요금표를 확인할 수 있습니다.
일반적인 문제 및 해결 방법
프롬프트 작성 파이프라인에서는 몇 가지 실수가 다시 나타납니다.
- 출력물의 머리말. "Here is your prompt:"로 시작하는 응답은 생성기 내부에 포함됩니다. 시스템 메시지의 끝을 "Reply with the prompt only"로 설정하고 결과를 정리하세요.
- 너무 긴 프롬프트. 단어 수가 많다고 항상 더 나은 비디오나 이미지를 제공하지는 않습니다. 지시사항에 단어 범위를 설정하고 코드에서 확인하세요.
- 같은 아이디어, 같은 출력. 고정된 값으로
seed을 전달하면 실행이 반복됩니다. 다양성을 원할 때는 항목마다 시드를 변경하거나 생략하세요. - 역할 혼합. 규칙은 시스템 메시지에 넣고 아이디어는 사용자 메시지에 넣으세요. 둘을 하나의 블록에 넣으면 모델이 규칙을 다시 쓸 콘텐츠로 취급합니다.
- 긴 배치 전반의 드리프트. 동일한 지시사항이 수천 번 실행되면 품질이 하락할 수 있습니다. 실행의 시작, 중간, 끝에서 항목을 표본 검사하고 시스템 메시지를 버전 관리에 보관하여 어떤 어조가 어떤 배치를 생성했는지 알 수 있게 하세요.
- 검토 단계 없음. 비싼 하류 도구에 프롬프트를 보내기 전에 각 배치의 샘플을 읽으세요. 10분의 읽기 시간으로 많은 낭비된 렌더링을 절약할 수 있습니다.
시작하려면 계정을 생성하고 API 키 페이지에서 $0.50 체험 크레딧을 청구하고 위의 첫 스크립트를 실행하세요. 체험은 사람당 한 번 청구할 수 있으며, 7일 동안 유효하고 카드가 필요하지 않습니다. 문서에는 top_p, stop 및 패널티를 포함하여 전달되는 모든 매개변수를 나열합니다.
더 많은 가이드
질문과 답변
이 API가 비디오 자체를 생성할 수 있나요?
아니요. 텍스트만 생성합니다. 프롬프트를 작성한 후, 원하는 비디오 도구에 해당 프롬프트를 전달하세요.
분당 몇 개의 프롬프트를 작성할 수 있나요?
일반 키는 분당 300개, 동시 8개의 요청을 허용합니다. 체험 키는 분당 60개, 동시 2개의 요청을 허용합니다.
요청이 너무 많으면 어떻게 되나요?
에러 코드 rate_limited 또는 concurrency가 반환되는 HTTP 429를 받습니다. Retry-After 값만큼 기다린 후 요청을 다시 보내세요.
프롬프트가 학습에 사용되나요?
아니요. 프롬프트는 학습에 사용되지 않습니다.