IT ▾
Ottieni la chiave API

API LLM per prompt: scrivili e affinali nel codice

Questa guida mostra come usare un'API testuale per scrivere, espandere e riscrivere prompt per altri strumenti, da una singola chiamata a un batch di migliaia.

Aggiornato

Terminale che alimenta schede prompt luminose lungo un nastro trasportatore verso una macchina a forma di fotocamera

Punti chiave

  • Una singola chiamata chat trasforma un'idea grezza in un prompt completo; l'ID del modello è uncensored.
  • La modalità JSON restituisce campi che il tuo script può memorizzare e cercare.
  • Una chiave completa esegue 8 richieste simultanee e 300 al minuto; gestisci gli errori 429 usando Retry-After.
  • L'API scrive solo testo; incolla il prompt nel tuo strumento video o immagine.

Cosa fa un'API LLM per il lavoro sui prompt

Un'API LLM per i prompt è ottima nella parte del lavoro sui prompt che stanca di più: trasformare un'idea di tre parole in una descrizione completa, scrivere dieci varianti della stessa scena o riscrivere un prompt per seguire un formato specifico. Invii l'idea grezza e un insieme di regole, e ricevi il testo del prompt finito. Poiché l'endpoint è compatibile con OpenAI, il codice è la stessa chiamata di conversazione che scriveresti per qualsiasi altro modello.

Un limite prima di tutto. Questo servizio restituisce solo testo. Non renderizza video, immagini o audio. Se il tuo obiettivo finale è un clip da un tool da testo a video, l'API scrive il prompt e tu incolli o instradi quel prompt nel generatore che preferisci. Questa separazione è utile di per sé, perché la scrittura dei prompt è il passaggio lento e ripetitivo e i token di testo sono economici.

Il modello è un modello a pesi aperti ottimizzato per rispondere senza rifiuti di contenuto per uso adulto legale, quindi un lavoro di scrittura di prompt su una scena thriller oscura o una battaglia fantasy violenta non viene respinto con una lezione. L'unico limite rigido è che non verrà prodotto nulla che coinvolga minorenni in contenuti sessuali.

Una prima chiamata per scrivere prompt in Python

Installa l'SDK con pip install openai e puntalo all'URL di base. L'ID del modello è uncensored, e la chiave va inserita come token Bearer, che l'SDK gestisce per te.

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

Tre dettagli rendono questo lavoro meglio di un primo tentativo. Il messaggio di sistema definisce la lunghezza e gli elementi che ogni prompt deve nominare, così le uscite rimangono confrontabili. Impostare temperature intorno a 0.8 dà varietà tra le esecuzioni senza allontanarsi dall'idea. E max_tokens è opzionale qui, ma un limite di 300 impedisce a una risposta prolissa di costare più del dovuto. Se lo lasci fuori, il completamento può usare tutto ciò che rimane della finestra da 100.000 token.

Se vuoi dieci varianti di un'idea, non fare dieci loop con le stesse impostazioni e spera. Aumenta la temperatura e passa un seed diverso per chiamata, oppure chiedi dieci prompt numerati in una sola risposta e dividili nel codice. La seconda opzione è più economica perché le istruzioni vengono inviate una volta sola.

Restituisci prompt strutturati con la modalità JSON

Il testo libero va bene per un umano. Una volta che uno script consuma l'output, vuoi dei campi. La modalità JSON rende la risposta un oggetto JSON valido, così puoi leggere il prompt, gli elementi che vuoi escludere e alcuni tag senza scrivere un parser fragile. Menziona la parola JSON e le chiavi che ti aspetti nel messaggio di sistema e imposta 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"])

Memorizza l'oggetto, non solo il testo. Una tabella con colonne per l'idea, il prompt finale, i tag e la data ti permette di cercare la tua cronologia in seguito e rende facile vedere quali istruzioni hanno prodotto i prompt che hai mantenuto.

Quando l'output deve seguire un formato che JSON non cattura, come un ordine fisso di righe etichettate, dillo con un esempio concreto all'interno del messaggio di sistema. I modelli copiano gli esempi in modo più affidabile di quanto seguano descrizioni astratte.

Attiva lo streaming del risultato per strumenti interattivi

Se una persona sta aspettando il risultato, ad esempio in un tool interno per prompt o in un pannello chat, attiva lo streaming della risposta così le prime parole appaiono subito. Imposta stream: true; la risposta arriva come eventi server-sent e l'utilizzo viene segnalato alla fine dello streaming.

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

Ricorda che una richiesta in streaming mantiene il suo slot di concorrenza fino alla fine dello streaming. Una chiave completa permette 8 richieste simultanee, quindi otto utenti che leggono streaming lenti nello stesso momento bloccheranno un nono. Per un piccolo tool interno è sufficiente. Per qualsiasi cosa pubblica, accoda le richieste dal tuo lato.

Esegui un batch rispettando i limiti di richieste

I lavori di scrittura di prompt che fanno risparmiare più tempo sono i batch: 500 foto di prodotto, 200 idee di scena da un copione, un intero foglio di calcolo di righe grezze. Una chiave completa permette 8 richieste parallele e 300 richieste al minuto, mentre una chiave di prova ne permette 2 e 60. Un pool di thread dimensionato in base alla chiave è il modo più semplice per restare entro entrambi i limiti.

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

Un 429 può significare due cose. Il codice di errore rate_limited significa che hai superato le richieste al minuto; concurrency significa che erano troppe richieste in esecuzione simultanea. Anche un sovraccarico temporaneo restituisce 429 con un'intestazione Retry-After: 5. Il loop sopra attende quanto dice l'intestazione e riprova. Le richieste fallite o rifiutate non vengono addebitate, quindi un retry non raddoppia il costo.

Scrivi i risultati su disco mentre procedi, una riga per prompt finito. Un file JSON-lines funziona bene: un oggetto per riga contenente l'idea, il prompt e l'ora, così un'esecuzione interrotta può saltare ciò che è già stato fatto quando lo riavvii. Un batch di qualche migliaio di chiamate colpirà eventualmente un momento di rete difettoso e non vuoi ricominciare dall'inizio.

Inserisci la tua guida di stile nella finestra di contesto da 100k

I prompt migliorano quando il modello conosce le tue regole. Con una finestra da 100.000 token, prompt più completamento, puoi inserire molto nel messaggio di sistema: una guida di stile, un elenco di frasi vietate, venti prompt di esempio approvati e un glossario su come il tuo team nomina i movimenti di macchina.

Usa quello spazio con scopo e tieni a mente una regola: il modello segue ciò che è scritto, quindi scrivi le regole nel modo in cui faresti il briefing a un nuovo collega. Una breve lista di cinque esempi eccellenti batte cinquanta misti, perché il modello fa la media di ciò che vede. Metti gli esempi nello stesso formato che vuoi ricevere. Se un progetto ha un personaggio ricorrente, scrivi la scheda del personaggio una volta sola, con capelli, abbigliamento ed età (solo personaggi adulti) descritti con parole fisse, e dì al modello di copiare quelle parole letteralmente in ogni prompt. Questo è il trucco di coerenza più economico disponibile: la stessa frase appare in ogni prompt, quindi il generatore downstream vede la stessa descrizione ogni volta.

Le istruzioni lunghe vengono inviate di nuovo con ogni chiamata, quindi vengono fatturate ad ogni chiamata. A $0.15 per milione di token di input, una guida di stile da 3.000 token costa $0.00045 per richiesta solo per l'input. È una cifra piccola, ma su 10.000 richieste fa $4.50, quindi riduci la guida una volta che funziona. La pagina prezzi ha i tassi completi se vuoi calcolare i tuoi numeri.

Problemi comuni e come risolverli

Alcuni errori si presentano di nuovo e di nuovo nelle pipeline di scrittura dei prompt.

  • Introduzione nell'output. Le risposte che iniziano con "Ecco il tuo prompt:" finiscono dentro il generatore. Termina il messaggio di sistema con "Rispondi solo con il prompt" e ripulisci il risultato dagli spazi.
  • Prompt troppo lunghi. Più parole non danno sempre video o immagini migliori. Imposta un intervallo di parole nelle istruzioni e controllalo nel codice.
  • Stessa idea, stesso output. Se passi seed con un valore fisso, le esecuzioni si ripetono. Cambia il seed per ogni elemento, oppure omettilo quando vuoi varietà.
  • Mescolamento dei ruoli. Tieni le regole nel messaggio di sistema e l'idea nel messaggio utente. Mettere entrambi in un unico blocco fa trattare al modello le tue regole come contenuto da riscrivere.
  • Deriva in un batch lungo. La qualità può scivolare quando le stesse istruzioni vengono eseguite migliaia di volte. Controlla a campione gli elementi all'inizio, nel mezzo e alla fine dell'esecuzione, e tieni il messaggio di sistema sotto controllo versione così puoi dire quale formulazione ha prodotto quale batch.
  • Nessun passaggio di revisione. Leggi un campione di ogni batch prima di inviare i prompt a un tool downstream costoso. Dieci minuti di lettura risparmiano molte generazioni sprecate.

Per iniziare, crea un account, richiedi il credito di prova da $0.50 nella pagina chiave API, ed esegui lo script sopra. Il credito di prova è una richiesta per persona, dura 7 giorni e non richiede carta. La documentazione elenca ogni parametro che viene passato, inclusi top_p, stop e le penalità.

01

Domande e risposte

Questa API può generare il video stesso?

No. Genera solo testo. Usala per scrivere il prompt, poi fornisci quel prompt allo strumento video che preferisci.

Quanti prompt posso scrivere al minuto?

Una chiave completa permette 300 richieste al minuto e 8 simultanee. Una chiave di prova ne permette 60 al minuto e 2 simultanee.

Cosa succede se invio troppe richieste?

Ottieni HTTP 429 con il codice rate_limited o concurrency. Attendi il valore di Retry-After, poi invia di nuovo la richiesta.

I miei prompt vengono utilizzati per l'addestramento?

No. I prompt non vengono utilizzati per l'addestramento.

Ti manca solo un modulo per la tua chiave

Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.

Ottieni la chiave APILeggi la documentazione