Geração com IA

Leia os modelosCopy Anchor Link

GET /generations/models lista todos os modelos de imagem, vídeo e voz, com os modos, resoluções, durações, proporções e vozes que cada um aceita, e o preço em créditos.

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

Cada modelo também diz o que esperar dele, para você escolher sem tentar:

• maker, description, released_at e tags: o que o fabricante diz sobre ele. Ficam null ou vazios quando o fabricante não diz nada.
• typical_seconds: quanto uma geração costuma levar, do pedido até ready, nas últimas duas semanas.
• success_rate: a parcela das gerações que saíram, de 0 a 1. Um pedido que o modelo recusa pelo conteúdo não conta contra ele.

Os dois ficam null até rodarem gerações suficientes. Quando o usuário não escolhe um modelo, use presets: o modelo recomendado para cada nível (fast, balanced, best) e tipo. prompt_max é o maior prompt, max_running quantas gerações um workspace pode ter rodando ao mesmo tempo e improve_credits quanto custa reescrever um prompt.

Os preços são em créditos: por segundo num vídeo, por imagem numa imagem e por 1.000 caracteres numa voz (sem arredondar: a cobrança é esse preço vezes os caracteres do prompt, dividido por 1.000, arredondado para cima). silent_credits é o preço do vídeo sem som, quando o modelo permite tirar o som.

Adicione imagens, se o pedido precisarCopy Anchor Link

Primeiro quadro, último quadro ou referências vão em image_ids. Envie um arquivo com POST /generations/images (multipart/form-data) ou reaproveite uma imagem gerada pela CutPro: o output.image_id dela vale igual.

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

O mode diz como as imagens são usadas: text não leva nenhuma, image leva uma (anima ela), frames leva duas (primeiro e último) e references até o max_images do modelo (pegar uma pessoa, produto ou estilo, ou editá-las).

Reescreva um pedido curto (opcional)Copy Anchor Link

POST /generations/improve transforma um pedido curto em um mais claro e detalhado, escrito do jeito que o modelo escolhido lê melhor e no idioma do pedido. Nada é gerado. Cobra improve_credits e devolve se a reescrita falhar. Mostre o resultado ao usuário antes de gerar com ele.

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": "um cachorro surfando ao pôr do sol", "seconds": 8 }'

GereCopy 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": "um cachorro surfando ao pôr do sol", "seconds": 8, "aspect_ratio": "9:16", "credits": 96 }'

A chamada responde 201 com o id e cobra os créditos na hora. Algumas regras por tipo:

• Um vídeo precisa de seconds, uma das durações do modelo. audio: false tira o som de um modelo com audio: optional, em geral por menos.
• Uma imagem não precisa de seconds. Um modelo que desenha numa só resolução não precisa dela no pedido.
• Uma voz (kind: speech, mode: text) lê o prompt palavra por palavra numa das voices do modelo, enviada em voice. Não aceita aspect_ratio e o resultado é um MP3. Cada voz tem um preview_url (uma frase de exemplo) e um portrait_url, links assinados válidos por 6 horas.

Erros que valem tratar: INSUFFICIENT_CREDITS (402, com top_up_url), PRICE_CHANGED (409, com o novo total em extra.credits), TOO_MANY_RUNNING (429) e MODEL_UNAVAILABLE, MODE_UNSUPPORTED, RESOLUTION_INVALID, SECONDS_INVALID, RATIO_INVALID, IMAGES_INVALID ou VOICE_INVALID (400).

AcompanheCopy Anchor Link

Consulte GET /generations/{id} a cada 10 segundos enquanto o status for processing. expected_seconds diz quanto esse modelo costuma levar. Ela termina ready, com output.url (link de prévia assinado, válido por 6 horas, um MP3 numa voz) e output.thumbnail_url, ou failed, com o motivo em error_code e os créditos já devolvidos.

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 as gerações do workspace, da mais nova para a mais antiga. Além do pedido (model, mode, resolution, seconds, aspect_ratio, voice, audio, prompt, image_ids), cada uma mostra credits_charged, feedback, feedback_reason, refund_status, downloaded e removed (o arquivo foi apagado da biblioteca).

Use o resultadoCopy Anchor Link

• Baixe com GET /generations/{id}/download: um link assinado para o arquivo em qualidade total, válido por 6 horas. Depois de baixado, os créditos não podem mais ser pedidos de volta.
• Edite ou poste um vídeo pronto com POST /generations/{id}/edit. Ele cria o projeto do editor na primeira chamada e devolve o mesmo edit_id depois. Passe-o para POST /posts para publicar ou agendar o vídeo, ou para POST /renders.
• Apague com DELETE /generations/{id}. Ela sai da lista e da biblioteca. Uma que ainda está em processing não pode ser apagada.

Avalie, ou peça os créditos de voltaCopy Anchor Link

Conte o que funcionou com POST /generations/{id}/feedback. Envie { "vote": "up" }, ou { "vote": "down", "reason": "defects" }, ou { "vote": null } para limpar. Os motivos são prompt_ignored, defects, bad_motion, not_realistic, speech_wrong (uma palavra, nome ou número dito errado) e other. Um down também cancela as postagens do resultado que ainda estão agendadas. Avaliar é grátis.

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" }'

Se um resultado não serve, peça os créditos de volta com POST /generations/{id}/refund, com um reason (a mesma lista) e uma note de uma ou duas frases. A equipe analisa. Vale uma vez por geração, só quando ela está ready e não depois de baixada ou postada (REFUND_AFTER_DOWNLOAD, REFUND_AFTER_POST; pedir de novo responde REFUND_ALREADY_REQUESTED). Acompanhe em refund_status de GET /generations/{id}: requested, depois approved ou 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": "As mãos saem deformadas em todos os planos." }'