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"
          }
        }
      ]
    },
    "poll_after_seconds": 8,
    "typical_seconds": {
      "p50": 1,
      "p90": 1,
      "samples": 1,
      "window": "string"
    },
    "retryable": true
  }
}

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.

認証

AuthorizationBearer

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

パスパラメータ

task_idstring必須

shot_idstring必須

リクエスト

This endpoint expects an object.

promptstring必須<=3000 characters

imageslist of stringsオプション

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

レスポンス

Shot edit accepted

dataobject

Accepted or current BeatAPI task state.

エラー

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

503

Service Unavailable Error

認証

パスパラメータ

ヘッダー

リクエスト

レスポンス

エラー