Technical

Automating Your Closed Caption Workflows Part 3

Closed Caption Converter API: Creating and Submitting Jobs with Postman

This is the final article in our three-part series on automating closed caption workflows. We've covered clean JSON profiles and frame-accurate segment timings. Now we'll dive deep into using Postman to interact with the Closed Caption Converter API, enabling robust production workflows and automated batch processing.

TLDR:

This guide walks you through using Postman to submit caption conversion jobs to the Closed Caption Converter API, transforming the clean JSON profiles from Parts 1-2 into production-ready automated workflows. You'll learn to configure API authentication, set up conversion requests using form-data (source file + JSON config), handle responses and downloads, and implement advanced techniques like environment variables and batch processing. By the end, you'll have a scalable system for converting caption formats programmatically, whether for single files or enterprise-level automation pipelines.

Why Use Postman for Closed Caption Conversion API?

Postman has become the industry standard for API development and testing, offering powerful features that make it ideal for caption conversion workflows:

• Visual interface for complex API interactions
• Collection organization for managing multiple conversion profiles
• Environment variables for streamlined batch processing
• Response handling and automated file downloads
• Team collaboration features for shared workflows
• Request history for debugging and optimization

Whether you're building automated pipelines or need reliable manual processing capabilities, Postman provides the flexibility and power required for professional caption workflows.

Prerequisites and Setup

Before we begin, ensure you have:

• Postman account with access to either the web GUI or desktop application (desktop recommended for file handling)
• CCC API access with valid authorization credentials
• Source caption files for testing
• JSON profiles from our previous articles

Note: If your organization has a client-specific Closed Caption Converter API URL with custom features, use that instead of the generic endpoints shown in this guide.

Part 1: API Health Check and Version Verification

Before submitting conversion jobs, it's good practice to verify the API is operational and check which version is running.

Creating a Version Check Request

1. Open Postman and create a new collection (optional but recommended for organization)
2. Add a new request by clicking the '+' button
3. Configure the basic request:
   • Method: Keep as GET (default)
   • URL: https://api.closedcaptionconverter.com
   • Name: "Check CCC Version" (optional, for organization)
4. Send the request - no additional parameters or authorization required

Expected Response

A successful response will look like this:

Success! We see that CCC version 3.4.51 is running. Other handy intel is also supplied.

This is a quick method of checking that the Closed Caption Converter API is running and ensuring that you are running on the version of CCC that is expected.

Part 2: Creating a Conversion Job Request

Now we'll build a complete conversion job request using the JSON profiles and techniques from our previous articles.

Example Scenario: PAC to SRT Conversion

For this demonstration, we'll convert a PAC file (Poliscript format, common in European broadcast) to SRT (SubRip Text, widely supported web format).

Step-by-Step Request Configuration

1. Create New POST Request

• Add new request to your collection
• Change method from GET to POST
• Set URL: https://api.closedcaptionconverter.com/jobs
• Name: "Submit CCC Job" (optional)

2. Configure Authorization

Navigate to the Authorization tab and configure API key authentication:

Obtaining Your API Key:

1. Open the CCC web GUI
2. Navigate to API Keys tab
3. Copy your existing key or generate a new one

Postman Authorization Settings:

• Auth Type: API Key
• Key: x-api-key
• Value: [paste your API key from CCC GUI]
• Add to: Header

3. Set Required Headers

Navigate to the Headers tab and add:

• Key: username
• Value: [your email address associated with CCC account]

This header is required for job authorization and billing purposes.

4. Configure Request Body

Navigate to the Body tab and select form-data format. Add two required fields:

Source File:

• Key: source
• Type: File (select from dropdown)
• Value: [select your source caption file]

Configuration:

• Key: config
• Type: text
• Value: [paste your JSON configuration - see example below]

JSON Configuration Example

Here's a complete JSON profile for PAC to SRT conversion:

{
  "source_frameRate": 25,
  "target_frameRate": 25,
  "segments": [],
  "encoding_options": [
    {"name": "Encode Position", "selected": true},
    {"name": "Encode Formatting", "selected": true},
    {"name": "Encode Font Styles", "selected": false},
    {
      "name": "Position Template",
      "type": "list",
      "values": [
        "Default", "Standard", "YouTube", 
        "MUFI", "Custom01", "Custom02"
      ],
      "selected": "Default"
    }
  ],
  "decoding_options": [
    {
      "name": "Code Page",
      "type": "list", 
      "values": [
        "ISO 8859-1 Latin 1", "ISO 8859-2 Latin 2",
        "ISO 8859-3 Latin 3", "ISO 8859-4 Baltic",
        "ISO 8859-5 Cyrillic", "ISO 8859-6 Arabic",
        "ISO 8859-7 Greek", "ISO 8859-8 Hebrew",
        "ISO 8859-9 Turkish"
      ],
      "selected": "ISO 8859-1 Latin 1"
    },
    {
      "name": "Ignore Metadata",
      "type": "list",
      "values": [true, false],
      "selected": true
    }
  ],
  "target_profile": "subRip",
  "source_profile": "ssPoliscript"
}

Configuration Notes

Frame Rate Settings:

• Both source and target set to 25fps (common PAC frame rate)
• No frame rate conversion needed for this example

Encoding Options:

• Position and formatting preserved
• Font styles disabled (not typically supported in SRT)
• Default position template used

Decoding Options:

• ISO 8859-1 Latin 1 character encoding (standard for Western European languages)
• Metadata ignored will ignore the first Event in the PAC File if it contains metadata

Empty Segments Array:

• No segment timing modifications needed
• Original timecode structure preserved

Part 3: Submitting and Handling Responses

Sending the Request

With all parameters configured, click the Send button to submit your conversion job.

Success Response

A successful conversion returns a JSON response with download information:

To download your converted file:

• Ctrl+click (or Cmd+click on Mac) on the download_url
• Or copy the URL and open in a new browser tab
• Save the file with your desired filename

Error Response Handling

Common error scenarios and solutions:

Invalid API Key (401 Unauthorized):

{
  "error": "invalid_api_key",
  "message": "Please check your API key and try again"
}

Solution: Verify API key in CCC web GUI and update Postman authorization

Unsupported Format (400 Bad Request):

{
  "error": "unsupported_format",
  "message": "Source format not recognized or target format unavailable"
}

Solution: Check source_profile and target_profile values in your JSON

Invalid JSON (400 Bad Request):

{
  "error": "invalid_api_key",
  "message": "Please check your API key and try again"
}

Solution: Validate JSON syntax (no extra commas or missing quotes) and verify all required fields are present

Conversion Results Example

Source PAC File Sample

& €€€þþCCC03:BLD_CCC3_35þCOPY2022 `è-è
€€€þcaption 1þHello `èXèú
€€€þcaption 2þHello `è^è  
€€€þcaption 3þHello `èEè4

Converted SRT File Sample

1
10:00:03,040 --> 10:00:05,919
caption 1
Hello

2
10:00:06,000 --> 10:00:10,720
caption 2  
Hello

3
10:00:11,720 --> 10:00:14,959
caption 3
Hello

Advanced Postman Techniques

Using Environment Variables

For production workflows, leverage Postman environment variables:

{
  "api_base": "{{ccc_api_url}}",
  "api_key": "{{ccc_api_key}}",
  "username": "{{ccc_username}}"
}

This enables:

• Environment switching (development, staging, production)
• Secure credential management
• Team collaboration without exposing sensitive data

Collection-Level Authorization

Set authorization at the collection level to avoid configuring each request individually:

• Collection Settings → Authorization
• Configure API key authentication
• Individual requests inherit collection auth

Response Processing Scripts

Automatically handle successful responses:

// Test for successful conversion
pm.test("Conversion successful", function () {
    pm.response.to.have.status(200);
    pm.expect(pm.response.json().status).to.equal("completed");
});

// Extract download URL for automated processing
if (pm.response.code === 200) {
    const response = pm.response.json();
    pm.environment.set("download_url", response.download_url);
    console.log("Conversion completed. Download URL:", response.download_url);
}

Conclusion and Next Steps

Throughout this three-part series, we've built a comprehensive foundation for professional caption conversion automation:

Part 1 established clean, maintainable JSON profiles that eliminate unnecessary complexity and improve workflow reliability.

Part 2 demonstrated frame-accurate segment timing control, essential for professional delivery specifications and complex content structures.

Part 3 provided the API integration techniques needed for production-scale automation and reliable batch processing.

Key Achievements

You now have the knowledge to:

• Create caption conversion job configurations
• Handle complex timing requirements with frame-accurate precision
• Build robust API workflows using industry-standard tools
• Implement production-grade error handling and monitoring
• Scale from single conversions to enterprise batch processing

Recommended Next Steps

1. Start small: Begin with simple format conversions using the techniques from Part 1
2. Add complexity gradually: Implement segment timing as needed for your content
3. Build automation: Use Postman collections and environment variables for repeated workflows
4. Monitor and optimize: Track conversion success rates and processing times
5. Expand integration: Connect CCC API to your existing media workflows

Final Thoughts

Professional caption conversion can require more than just changing file formats—it sometimes demands adjustments to timing, and formatting to meet new technical requirements introduced by the format. The programmatic approach we've outlined provides a basis, enabling you to build workflows that meet the exacting standards of modern media production workflows.

Whether you're processing a single file or managing thousands of assets, these techniques provide the foundation for success. The key is starting with clean, understandable configurations and building complexity only as needed.

Happy captioning, and welcome to the world of media supply chain.