Cut.ProDocs

Generate image, video and voice

Choose a model, confirm the price, generate from text or images and use the result in the editor or in a post.

View MarkdownChatGPTClaude

One route generates image, video or voice with models from several makers (Veo, Kling, Seedance, Wan, Nano Banana, GPT Image, ElevenLabs voices and others). You create the generation, poll until it is ready and use the result.

Generating always charges, even on unlimited usage. Show the person the model and the price and wait for a yes before calling POST /generations. If it fails, the credits come back on their own.

Choose the model

curl https://api.cut.pro/api/v1/generations/models \
  -H "X-Api-Key: $CUTPRO_API_KEY"
200 OK (abridged example)
{
  "models": [
    {
      "id": "google/veo-3.1-lite",
      "name": "Veo 3.1 Lite",
      "kind": "video",
      "modes": ["text", "image", "frames"],
      "resolutions": ["720p", "1080p"],
      "seconds": [4, 6, 8],
      "aspect_ratios": ["16:9", "9:16"],
      "audio": "always",
      "max_images": 2,
      "typical_seconds": 74,
      "success_rate": 0.97,
      "prices": [{ "mode": "text", "resolution": "720p", "credits": 12, "silent_credits": null }]
    }
  ],
  "presets": { "video": [{ "id": "balanced", "model": "google/veo-3.1-lite", "resolution": "720p" }] },
  "prompt_max": 4000,
  "max_running": 4,
  "improve_credits": 1
}

Prices follow each model's cost and change without notice: read this route right before generating.

FieldWhat it is for
modestext (prompt only), image (animates an image), frames (from the first to the last frame), references (takes a person, product or style from the images, or edits them).
prices[].creditsPer second of video, per image or per 1,000 characters of voice. silent_credits is the price of the video without sound.
audioalways always has sound; optional accepts audio: false, usually cheaper; null is silent.
refusesWhat the model refuses to show: real_faces, minors, public_figures.
typical_seconds, success_rateTypical time and success rate over the last weeks. null until enough generations have run.
presetsThe recommended model per type and tier (fast, balanced, best). Use it when the person does not choose.
max_runningHow many generations the workspace runs at the same time.

Upload the images, if the mode requires them

curl -X POST https://api.cut.pro/api/v1/generations/images \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -F "image=@produto.jpg"
201 Created
{ "id": "7412960011002233" }
modeimage_ids
textnone
imageone, the first frame
framestwo: first and last frame
referencesup to the model's max_images

An image generated by Cut.Pro does not need an upload: its output.image_id works just as well.

Generate

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": "a dog surfing at sunset",
    "seconds": 8,
    "aspect_ratio": "9:16",
    "credits": 96
  }'
201 Created
{ "id": "7412960099887766", "status": "processing", "credits_charged": 96 }

credits is the total the person accepted: the price's credits times seconds on a video (12 × 8 = 96). If the price changed, nothing is charged and the response is 409 PRICE_CHANGED with the new total in extra.credits. Show the new amount and ask for a yes again.

  • Video: seconds is required and must be one of the model's seconds.
  • Image: no seconds.
  • Voice (kind: "speech", mode: "text"): reads the prompt word for word in the voice chosen from the model's voices. No aspect_ratio. Outputs an MP3. Costs credits times the prompt characters divided by 1,000, rounded up.

Follow along

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

Poll every 10 seconds while status is processing. expected_seconds says how long the model usually takes.

  • ready: output.url is the preview (a 6-hour link, MP3 for a voice) and output.thumbnail_url is the thumbnail.
  • failed: the reason is in error_code and the credits have already come back.

Improve the prompt

POST /generations/improve rewrites a short request the way the chosen model understands best, in the language of the request. It generates nothing. It charges improve_credits and refunds if it fails. Show the new text to the person before generating with it.

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": "a dog surfing at sunset", "seconds": 8 }'

Use the result

RouteWhat it does
GET /generations/{id}/downloadLink to the file in full quality, valid for 6 hours. After downloading, you can no longer ask for the credits back.
POST /generations/{id}/editOpens a finished video in the editor and returns the edit_id. Use it in POST /posts or POST /renders. Calling again returns the same one.
GET /generationsLists the generations, from newest to oldest. Filter with kind.
DELETE /generations/{id}Removes it from the list and deletes the file from the library. Does not work for one in processing.

Rate or ask for the credits back

Rating is free and helps choose models:

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

vote is up, down or null (clears). With down, reason is one of prompt_ignored, defects, bad_motion, not_realistic, speech_wrong (a word, name or number spoken wrong) or other. A down cancels the posts of that result that are still scheduled.

If the result is no good, ask for a refund with the same reason and a short note:

curl -X POST https://api.cut.pro/api/v1/generations/7412960099887766/refund \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "defects", "note": "The hands come out deformed in every shot." }'

The team reviews it. refund_status goes from requested to approved or denied.

A refund is valid once per generation, only in ready, and never after downloading or posting: 409 REFUND_AFTER_DOWNLOAD and 409 REFUND_AFTER_POST.

Errors

CodeWhen
INSUFFICIENT_CREDITSInsufficient balance. extra.top_up_url leads to the top-up; extra.is_owner says whether the caller can top up.
PRICE_CHANGEDThe price changed. The new total is in extra.credits.
TOO_MANY_RUNNINGThe workspace already has max_running generations running. Wait for one to finish.
MODEL_UNAVAILABLE, MODE_UNSUPPORTED, RESOLUTION_INVALID, SECONDS_INVALID, RATIO_INVALID, IMAGES_INVALID, VOICE_INVALIDThe request does not match what the model accepts. Check GET /generations/models.
IMAGE_NOT_FOUNDAn image_ids entry is not from this workspace.

When the generation ends in failed, error_code says why: SAFETY_BLOCKED, COPYRIGHT_BLOCKED and REAL_FACES_BLOCKED are model refusals over the content (change the request or the model); TIMEOUT and MEDIA_FAILED are worth another attempt.

Transcribe audio and video

Upload an audio or video file, transcribe with timing per sentence and, if you want, who is speaking. Download as JSON, SRT, VTT or text.

Create personas and swap the person in the video

Create a realistic person from traits, face photos or a ready-made character, and put them in any video or product photo.

On this page

Choose the modelUpload the images, if the mode requires themGenerateFollow alongImprove the promptUse the resultRate or ask for the credits backErrors