PT ▾
Obter chave de API

API LLM para prompts: escreva e refine-os no código

Este guia mostra como usar uma API de texto para escrever, expandir e reescrever prompts para outras ferramentas, de uma única chamada a um lote de milhares.

Atualizado

Terminal alimentando cartões de prompt brilhantes ao longo de uma esteira para uma máquina em forma de câmera

Pontos principais

  • Uma chamada de chat transforma uma ideia rascunho em um prompt completo; o ID do modelo é uncensored.
  • O modo JSON retorna campos que seu script pode armazenar e pesquisar.
  • Uma chave completa executa 8 requisições simultâneas e 300 por minuto; tente novamente os erros 429 usando Retry-After.
  • A API escreve apenas texto; você cola o prompt na sua ferramenta de vídeo ou imagem.

O que uma API LLM faz para o trabalho de prompts

Uma API LLM para prompts é excelente na parte do trabalho com prompts que cansa as pessoas: transformar uma ideia de três palavras em uma descrição completa, escrever dez variações da mesma cena ou reescrever um prompt para seguir um formato de casa. Você envia a ideia inicial e um conjunto de regras, e recebe o texto do prompt pronto de volta. Como o endpoint é compatível com OpenAI, o código é a mesma chamada de chat que você escreveria para qualquer outro modelo.

Uma restrição primeiro. Este serviço retorna apenas texto. Ele não renderiza vídeo, imagens ou áudio. Se seu objetivo final for um clipe de uma ferramenta de texto para vídeo, a API escreve o prompt e você cola ou canaliza esse prompt no gerador que usar. Essa separação é útil por si só, porque a escrita de prompts é a etapa lenta e repetitiva, e os tokens de texto são baratos.

O modelo é um modelo de pesos abertos ajustado para responder sem recusas de conteúdo para uso adulto legal, então um trabalho de escrita de prompt sobre uma cena de thriller sombrio ou uma batalha de fantasia violenta não é rejeitado com uma palestra. A única restrição rígida é que nada envolvendo menores de idade em conteúdo sexual será produzido.

Uma primeira chamada de escritor de prompts em Python

Instale o SDK com pip install openai e aponte-o para a URL base. O ID do modelo é uncensored e a chave é inserida como um token Bearer, que o SDK trata para você.

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"))

Três detalhes fazem isso funcionar melhor do que uma primeira tentativa geralmente faz. A mensagem do sistema define o comprimento e os elementos que todo prompt deve nomear, para que as saídas permaneçam comparáveis. Definir temperature em torno de 0.8 dá variedade entre execuções sem se desviar da ideia. E max_tokens é opcional aqui, mas um limite de 300 impede que uma resposta verbosa custe mais do que deveria. Se você omitir isso, a conclusão pode usar o que sobrar da janela de 100.000 tokens.

Se você quer dez versões de uma ideia, não faça dez loops com as mesmas configurações e espere. Aumente a temperatura e passe um seed diferente por chamada, ou peça dez prompts numerados em uma única resposta e divida-os no código. A segunda opção é mais barata porque as instruções são enviadas uma vez.

Retorne prompts estruturados com o modo JSON

Texto livre é suficiente para um humano. Uma vez que um script consome a saída, você quer campos. O modo JSON torna a resposta um objeto JSON válido, para que você possa ler o prompt, os elementos que deseja excluir e algumas tags sem escrever um analisador frágil. Mencione a palavra JSON e as chaves que você espera na mensagem do sistema, e defina 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"])

Armazene o objeto, não apenas o texto. Uma tabela com colunas para a ideia, o prompt final, as tags e a data permite pesquisar seu próprio histórico mais tarde e torna fácil ver quais instruções produziram os prompts que você manteve.

Quando a saída deve seguir um formato que o JSON não captura, como uma ordem fixa de linhas rotuladas, diga isso com um exemplo concreto dentro da mensagem do sistema. Modelos copiam exemplos com mais confiabilidade do que seguem descrições abstratas.

Faça streaming do resultado para ferramentas interativas

Se uma pessoa está esperando pelo resultado, por exemplo, em uma ferramenta interna de prompts ou em um painel de chat, faça streaming da resposta para que as primeiras palavras apareçam imediatamente. Defina stream: true; a resposta chega como Eventos Enviados pelo Servidor, e o uso é relatado no final do stream.

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()

Lembre-se de que uma requisição em streaming mantém seu slot de concorrência até o fim do streaming. Uma chave completa permite 8 requisições simultâneas, então oito usuários lendo streams lentos ao mesmo tempo bloquearão uma nona. Para uma ferramenta interna pequena, isso é suficiente. Para qualquer coisa pública, faça fila de requisições do seu lado.

Execute um lote dentro dos limites de requisições

As tarefas de escrita de prompts que economizam mais tempo são lotes: 500 fotos de produtos, 200 ideias de cena a partir de um roteiro, uma planilha inteira de linhas rascunho. Uma chave completa permite 8 requisições simultâneas e 300 requisições por minuto, e uma chave de teste permite 2 e 60. Um pool de threads dimensionado para a chave é a maneira mais simples de permanecer dentro de ambos os números.

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])

Um 429 pode significar duas coisas. O código de erro rate_limited significa que você excedeu as requisições por minuto; concurrency significa que muitas requisições estavam sendo executadas ao mesmo tempo. Sobrecarga temporária também retorna 429 com um cabeçalho HTTP Retry-After: 5. O loop acima espera o tempo indicado pelo cabeçalho e tenta novamente. Requisições falhas ou recusadas não são cobradas, então uma nova tentativa não dobra o custo.

Escreva os resultados no disco conforme avança, uma linha por prompt finalizado. Um arquivo JSON-lines funciona bem: um objeto por linha contendo a ideia, o prompt e a hora, para que uma execução interrompida possa pular o que já foi feito quando você o iniciar novamente. Um lote de algumas milhares de chamadas eventualmente atingirá um momento de rede ruim, e você não quer começar novamente do topo.

Coloque seu guia de estilo na janela de contexto de 100k

Os prompts ficam melhores quando o modelo conhece suas regras. Com uma janela de 100.000 tokens, prompt mais a conclusão, você pode colocar muito na mensagem do sistema: um guia de estilo, uma lista de frases proibidas, vinte prompts de exemplo aprovados e um glossário de como sua equipe nomeia movimentos de câmera.

Use esse espaço com propósito e tenha uma regra em mente: o modelo segue o que está escrito, então escreva regras como se estivesse orientando um novo colega. Uma lista curta com cinco exemplos excelentes supera cinquenta misturados, porque o modelo faz a média do que vê. Coloque os exemplos no mesmo formato que você quer receber. Se um projeto tem um personagem recorrente, escreva a ficha do personagem uma vez, descrevendo cabelo, roupa e idade (apenas personagens adultos) com palavras fixas, e diga ao modelo para copiar essas palavras literalmente em todos os prompts. Este é o truque de consistência mais barato: a mesma frase aparece em cada prompt, então o gerador na etapa seguinte vê a mesma descrição cada vez.

Instruções longas são reenviadas com cada chamada, então elas são cobradas a cada chamada. A $0.15 por milhão de tokens de entrada, um guia de estilo de 3.000 tokens custa $0.00045 por requisição apenas em entrada. Isso é pouco, mas em 10.000 requisições isso dá $4.50, então reduza o guia assim que ele funcionar. A página de preços tem as tarifas completas se você quiser calcular seus próprios números.

Problemas comuns e como resolvê-los

Alguns erros aparecem repetidamente em pipelines de escrita de prompts.

  • Preambulo na saída. Respostas que começam com "Aqui está o seu prompt:" acabam dentro do gerador. Termine a mensagem do sistema com "Responda apenas com o prompt" e remova os espaços do resultado.
  • Prompts muito longos. Mais palavras nem sempre dão melhor vídeo ou imagens. Defina uma faixa de palavras nas instruções e verifique no código.
  • Mesma ideia, mesma saída. Se você passar seed com um valor fixo, as execuções se repetem. Altere a seed por item ou omita-a quando quiser variedade.
  • Misturando papéis. Mantenha as regras na mensagem do sistema e a ideia na mensagem do usuário. Colocar ambos em um único bloco faz o modelo tratar suas regras como conteúdo a ser reescrito.
  • Desvio em um lote longo. A qualidade pode cair quando as mesmas instruções são executadas milhares de vezes. Verifique itens do início, meio e fim da execução, e mantenha a mensagem do sistema sob controle de versão para que você possa dizer qual redação fez qual lote.
  • Sem etapa de revisão. Leia uma amostra de cada lote antes de enviar prompts para uma ferramenta downstream cara. Dez minutos de leitura economizam muitos renders desperdiçados.

Para começar, crie uma conta, resgate o crédito de teste de $0.50 na página da chave de API e execute o primeiro script acima. O teste é um resgate por pessoa, dura 7 dias e não precisa de cartão. A documentação lista todos os parâmetros que são passados, incluindo top_p, stop e as penalidades.

01

Perguntas e respostas

Esta API pode gerar o vídeo em si?

Não. Ele gera apenas texto. Use-o para escrever o prompt, depois dê esse prompt para a ferramenta de vídeo de sua escolha.

Quantos prompts posso escrever por minuto?

Uma chave completa permite 300 requisições por minuto e 8 simultâneas. Uma chave de teste permite 60 por minuto e 2 simultâneas.

O que acontece se eu enviar muitas requisições?

Você recebe HTTP 429 com o código rate_limited ou concurrency. Aguarde o valor Retry-After, então envie a requisição novamente.

Meus prompts são usados para treinamento?

Não. Os prompts não são usados para treinamento.

Sua chave está a um formulário de distância

Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.

Obter chave de APILer a documentação