Edit a Music Video storyboard shot | BeatAPI API Documentation

curl -X POST https://api.beatapi.io/v1/music-video/tasks/task_8K2qA/shots/shot_xxx/edit \
     -H "Idempotency-Key: music-edit-task_8K2qA-shot_xxx-01" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "prompt": "Night city chorus with brighter face lighting.",
  "images": [
    "https://media.beatapi.io/samples/stage.png"
  ]
}'

{
  "data": {
    "id": "task_8K2qA",
    "object": "task",
    "task_kind": "workflow",
    "capability_id": "string",
    "capability_version": 1,
    "status": "queued",
    "stage": "queued",
    "created_at": 1,
    "updated_at": 1,
    "completed_at": 1,
    "output": null,
    "usage": {
      "credits_reserved": 1.1,
      "credits_charged": 1.1,
      "credits_settled": 1.1,
      "credits_refunded": 1.1,
      "billable_duration_seconds": 1
    },
    "request_id": "req_abc123",
    "error_code": "processing_timeout",
    "error_message": "string",
    "workflow": "music-video",
    "effect_id": "video-muscle-max",
    "effect_version": 1,
    "media_type": "image",
    "model": "string",
    "storyboard": {
      "shots": [
        {
          "id": "shot_xxx",
          "index": 0,
          "status": "queued",
          "created_at": 1782210000,
          "updated_at": 1782210300,
          "duration_seconds": 5,
          "prompt": "Opening lyric shot.",
          "lyric_text": "Intro",
          "media": {
            "type": "video",
            "url": "https://media.beatapi.io/outputs/task_8K2qA/shots/0.mp4",
            "mime_type": "video/mp4"
          }
        }
      ]
    }
  }
}

Edit one storyboard shot using its BeatAPI shot_id. This operation charges the customer USD balance using the applicable task tier and shot duration. Standard edits accept only prompt. Premium edits accept prompt plus up to 6 optional replacement images. Generation quality, resolution, and shot duration are inherited from the original task and are not editable request fields. When the edit finishes, BeatAPI stores the edited shot media and exposes it on that shot. The existing final Music Video is not replaced until you call compose with the selected shot ids.

Edit one storyboard shot using its BeatAPI `shot_id`. This operation charges the customer USD balance using the applicable task tier and shot duration. Standard edits accept only `prompt`. Premium edits accept `prompt` plus up to 6 optional replacement `images`. Generation quality, resolution, and shot duration are inherited from the original task and are not editable request fields. When the edit finishes, BeatAPI stores the edited shot media and exposes it on that shot. The existing final Music Video is not replaced until you call compose with the selected shot ids.

Authentication

AuthorizationBearer

Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.

Path parameters

task_idstringRequired

shot_idstringRequired

Request

This endpoint expects an object.

promptstringRequired<=3000 characters

imageslist of stringsOptional

Premium tasks only. Optional replacement scene images; an empty array is treated as omitted. Standard tasks reject this field.

Response

Shot edit accepted

dataobject

Accepted or current BeatAPI task state.

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

404

Not Found Error

409

Conflict Error

429

Too Many Requests Error

500

Internal Server Error

502

Bad Gateway Error

Authentication

Path parameters

Headers

Request

Response

Errors