Generación con IA

Lee los modelosCopy Anchor Link

GET /generations/models lista todos los modelos de imagen, video y voz, con los modos, resoluciones, duraciones, proporciones y voces que acepta cada uno, y su precio en créditos.

curl https://api.cut.pro/api/v1/generations/models \
  -H "X-Api-Key: $CUTPRO_API_KEY"

Cada modelo también dice qué esperar de él, para que elijas sin probar:

• maker, description, released_at y tags: lo que dice el fabricante sobre él. Quedan en null o vacíos cuando el fabricante no dice nada.
• typical_seconds: cuánto suele tardar una generación, desde el pedido hasta ready, en las últimas dos semanas.
• success_rate: la parte de las generaciones que salieron, de 0 a 1. Un pedido que el modelo rechaza por su contenido no cuenta en su contra.

Ambos quedan en null hasta que corran suficientes generaciones. Cuando el usuario no elige un modelo, usa presets: el modelo recomendado para cada nivel (fast, balanced, best) y tipo. prompt_max es el prompt más largo, max_running cuántas generaciones puede tener corriendo a la vez un workspace e improve_credits cuánto cuesta reescribir un prompt.

Los precios son en créditos: por segundo en un video, por imagen en una imagen y por 1.000 caracteres en una voz (sin redondear: el cobro es ese precio por los caracteres del prompt, dividido entre 1.000, redondeado hacia arriba). silent_credits es el precio del video sin sonido, cuando el modelo permite quitarlo.

Agrega imágenes, si el pedido las necesitaCopy Anchor Link

Primer fotograma, último fotograma o referencias van en image_ids. Sube un archivo con POST /generations/images (multipart/form-data) o reutiliza una imagen generada por CutPro: su output.image_id vale igual.

curl -X POST https://api.cut.pro/api/v1/generations/images \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -F "image=@producto.jpg"

El mode dice cómo se usan las imágenes: text no lleva ninguna, image lleva una (la anima), frames lleva dos (primero y último) y references hasta el max_images del modelo (tomar una persona, producto o estilo, o editarlas).

Reescribe un pedido corto (opcional)Copy Anchor Link

POST /generations/improve convierte un pedido corto en uno más claro y detallado, escrito como mejor lo lee el modelo elegido y en el idioma del pedido. No se genera nada. Cobra improve_credits y los devuelve si la reescritura falla. Muestra el resultado al usuario antes de generar con él.

curl -X POST https://api.cut.pro/api/v1/generations/improve \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "google/veo-3.1-lite", "mode": "text", "prompt": "un perro surfeando al atardecer", "seconds": 8 }'

GeneraCopy Anchor Link

curl -X POST https://api.cut.pro/api/v1/generations \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "video", "model": "google/veo-3.1-lite", "mode": "text", "resolution": "720p", "prompt": "un perro surfeando al atardecer", "seconds": 8, "aspect_ratio": "9:16", "credits": 96 }'

La llamada responde 201 con el id y cobra los créditos al instante. Algunas reglas por tipo:

• Un video necesita seconds, una de las duraciones del modelo. audio: false quita el sonido de un modelo con audio: optional, normalmente por menos.
• Una imagen no necesita seconds. Un modelo que dibuja en una sola resolución no la necesita en el pedido.
• Una voz (kind: speech, mode: text) lee el prompt palabra por palabra en una de las voices del modelo, enviada en voice. No acepta aspect_ratio y el resultado es un MP3. Cada voz tiene un preview_url (una frase de ejemplo) y un portrait_url, enlaces firmados válidos por 6 horas.

Errores que conviene manejar: INSUFFICIENT_CREDITS (402, con top_up_url), PRICE_CHANGED (409, con el nuevo total en extra.credits), TOO_MANY_RUNNING (429) y MODEL_UNAVAILABLE, MODE_UNSUPPORTED, RESOLUTION_INVALID, SECONDS_INVALID, RATIO_INVALID, IMAGES_INVALID o VOICE_INVALID (400).

SíguelaCopy Anchor Link

Consulta GET /generations/{id} cada 10 segundos mientras el status sea processing. expected_seconds dice cuánto suele tardar ese modelo. Termina ready, con output.url (enlace de vista previa firmado, válido por 6 horas, un MP3 en una voz) y output.thumbnail_url, o failed, con el motivo en error_code y los créditos ya devueltos.

curl https://api.cut.pro/api/v1/generations/GENERATION_ID \
  -H "X-Api-Key: $CUTPRO_API_KEY"

GET /generations?kind=video&page=1&limit=20 lista las generaciones del workspace, de la más nueva a la más antigua. Además del pedido (model, mode, resolution, seconds, aspect_ratio, voice, audio, prompt, image_ids), cada una muestra credits_charged, feedback, feedback_reason, refund_status, downloaded y removed (el archivo se borró de la biblioteca).

Usa el resultadoCopy Anchor Link

• Descárgalo con GET /generations/{id}/download: un enlace firmado al archivo en calidad total, válido por 6 horas. Una vez descargado, ya no se pueden pedir de vuelta sus créditos.
• Edítalo o publícalo si es un video listo, con POST /generations/{id}/edit. Crea el proyecto del editor en la primera llamada y devuelve el mismo edit_id después. Pásalo a POST /posts para publicar o programar el video, o a POST /renders.
• Bórralo con DELETE /generations/{id}. Sale de la lista y de la biblioteca. Una que sigue en processing no se puede borrar.

Califícala, o pide los créditos de vueltaCopy Anchor Link

Cuéntanos qué funcionó con POST /generations/{id}/feedback. Envía { "vote": "up" }, o { "vote": "down", "reason": "defects" }, o { "vote": null } para limpiarlo. Los motivos son prompt_ignored, defects, bad_motion, not_realistic, speech_wrong (una palabra, nombre o número dicho mal) y other. Un down también cancela las publicaciones del resultado que siguen programadas. Calificar es gratis.

curl -X POST https://api.cut.pro/api/v1/generations/GENERATION_ID/feedback \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "vote": "down", "reason": "bad_motion" }'

Si un resultado no sirve, pide sus créditos de vuelta con POST /generations/{id}/refund, con un reason (la misma lista) y una note de una o dos frases. El equipo la revisa. Vale una vez por generación, solo cuando está ready y no después de descargada o publicada (REFUND_AFTER_DOWNLOAD, REFUND_AFTER_POST; pedir de nuevo responde REFUND_ALREADY_REQUESTED). Síguela en refund_status de GET /generations/{id}: requested, luego approved o denied.

curl -X POST https://api.cut.pro/api/v1/generations/GENERATION_ID/refund \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "defects", "note": "Las manos salen deformadas en todos los planos." }'