Clips API

Create, manage, and retrieve video clips programmatically.

Create a Clip

POST
/v1/clips

Creates a new clip from a video source. The clip will be processed asynchronously and you'll receive a webhook notification when it's ready.

Request Body

ParameterTypeRequiredDescription
video_urlstringYesURL of the source video
durationintegerNoClip duration in seconds (default: 60, max: 300)
stylestringNoEditing style: "viral", "professional", or "casual"
titlestringNoTitle for the clip
descriptionstringNoDescription for the clip
Request Example
interface CreateClipRequest {
  video_url: string;
  duration?: number;
  style?: 'viral' | 'professional' | 'casual';
  title?: string;
  description?: string;
}

const createClip = async (data: CreateClipRequest) => {
  const response = await fetch('https://api.clip.fm/v1/clips', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    throw new Error(`Error: ${response.status}`);
  }

  return response.json();
};

// Usage
const clip = await createClip({
  video_url: 'https://s3.amazonaws.com/my-bucket/video.mp4',
  duration: 60,
  style: 'viral',
  title: 'My Amazing Clip',
  description: 'Check out this awesome moment!'
});

Response

Returns the created clip object with a 201 Created status code.

Response Example
{
  "id": "clip_1a2b3c4d5e",
  "url": "https://clip.fm/c/abc123",
  "video_url": "https://s3.amazonaws.com/my-bucket/video.mp4",
  "duration": 60,
  "style": "viral",
  "title": "My Amazing Clip",
  "description": "Check out this awesome moment!",
  "status": "processing",
  "thumbnail_url": null,
  "views": 0,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Errors

  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Invalid or missing API key
  • 402 Payment Required - Insufficient credits
  • 422 Unprocessable Entity - Invalid video URL or format

Retrieve a Clip

GET
/v1/clips/:id

Retrieves details about a specific clip.

Path Parameters

  • id - The unique identifier of the clip
Request Example
const response = await fetch('https://api.clip.fm/v1/clips/clip_1a2b3c4d5e', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const clip = await response.json();

List Clips

GET
/v1/clips

Returns a paginated list of your clips.

Query Parameters

  • limit - Number of clips to return (default: 20, max: 100)
  • offset - Number of clips to skip
  • status - Filter by status: "processing", "ready", or "failed"
Request Example
const params = new URLSearchParams({
  limit: '20',
  status: 'ready'
});

const response = await fetch(`https://api.clip.fm/v1/clips?${params}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const clips = await response.json();

Delete a Clip

DELETE
/v1/clips/:id

Permanently deletes a clip and all associated data.