Overview

Google Cloud Storage (GCS) is a scalable object storage service provided by Google Cloud. Bitmovin's Encoding API supports GCS buckets as an output destination, allowing the encoder to write encoded segments and manifests directly to your buckets, ready to be served as an origin for a CDN or for direct playback.

There are two authentication methods available when using GCS as a Bitmovin output:

• HMAC keys (legacy gcs resource type): uses an Access Key and Secret Key pair generated from a GCP user account. See Creating Access and Secret Keys for Google Cloud Storage for this approach.
• Service Account (gcs-service-account resource type): uses a GCP IAM Service Account and a JSON key file. This is the recommended approach, as it follows GCP security best practices, scopes permissions precisely to the bucket, and avoids tying credentials to a personal user account.

This guide covers the Service Account method.

Prerequisites

Before creating a Bitmovin GCS Service Account output, you need:

• An active Google Cloud project with billing enabled
• Permission to create and manage Service Accounts in GCP IAM

If you are also setting up a GCS input with Service Account auth, you can follow the GCP setup steps in Setting Up a GCS Input (Service Account) and reuse a single Service Account for both, or create separate ones per bucket depending on your security requirements.

Step 1: Create a Service Account and Generate a JSON Key

1. In the Google Cloud Console, navigate to IAM & Admin → Service Accounts
2. Click Create Service Account, give it a descriptive name (e.g. bitmovin-encoding-output-service-account), and click Create and Continue
3. Skip the optional "Grant this service account access to project" step. You will grant access at the bucket level instead
4. Click Done
5. Click on your new Service Account and go to the Keys tab
6. Click Add Key → Create new key, select JSON, and click Create
7. The JSON key file containing your Service Account Credentials downloads automatically. Store it securely by following the Best practices for managing service account keys
8. Note the Service Account email address from the list, as you will need it in the next step

Step 2: Create a GCS Bucket and Grant Access

Granting access at the bucket level (rather than the project level) is both safer and does not require project-wide IAM admin permissions. For full details see Required Permissions for GCS Buckets for Encoding Input and Output.

1. Navigate to Cloud Storage → Buckets and click Create
2. Enter a globally unique bucket name (e.g. bitmovin-encoding-output-bucket ). Note this down, as you will need it in the next step

⚠️

Avoid using underscore characters (_) in bucket names. While Google Cloud Storage allows underscores when creating a bucket, such buckets cannot be accessed using a standard URI string, which will cause the entire setup to fail.

3. Select a region appropriate for your workload
4. Configure the Access Control setting. Output buckets support both Public and Private access
   1. If you select Uniform access control all ACLs in EncodingOutput.acl[*].permission will need to set to private
   2. If you select Fine-Grained access control, you will be able to set both private and public-read for your EncodingOutput.acl[*].permission
5. Click Create
6. With your new bucket open, go to the Permissions tab and click Grant Access
7. In the New principals field, paste the Service Account email address noted before
8. Assign the Storage Object Admin role (roles/storage.objectAdmin). This grants the write access Bitmovin needs to upload encoded files
9. Click Save

Step 3: Create a Bitmovin GCS Service Account Output

Note: The Bitmovin Dashboard does not support the gcs-service-account resource type. When creating a GCS output via the Dashboard, it uses the legacy HMAC-based gcs type, which asks for an Access Key and Secret Key. To use Service Account authentication, create the output via the API or an SDK as shown below.

You will need:

• A Bitmovin account and API key (Get started with the Bitmovin API)
• The JSON key file containing your Service Account Credentials (e.g, YOUR_JSON_SERVICE_ACCOUNT_CREDENTIALS.json)
• Your bucket name (e.g. bitmovin-encoding-output-bucket)

Use the Bitmovin API

Go to Create Service Account based GCS Output and fill in the required fields. Note that:

• X-Api-Key is your Bitmovin API Key
• serviceAccountCredentials is the entire content of your JSON key file
• bucketName is your GCS output bucket name

Fill in any other desired fields and click Try it!.

ℹ️

Sub-Organizations: If you are working within a Bitmovin sub-organization, add the X-Tenant-Org-Id header to the generated API request, set to the ID of the target organization.

Congratulations! Your GCS Service Account Output is now ready to use!
The ID contained in the result field of the response is your output ID, which you can use in future encoding jobs.

Use a Bitmovin SDK

Each of our Open API SDKs implements the Bitmovin API, making it easy to integrate with your project. Use them to create reusable input resources for your encodings:

from bitmovin_api_sdk import BitmovinApi, GcsServiceAccountOutput

bitmovin_api = BitmovinApi(api_key='YOUR_BITMOVIN_API_KEY')
# bitmovin_api = BitmovinApi(api_key='YOUR_BITMOVIN_API_KEY', tenant_org_id='YOUR_TENANT_ORG_ID')

with open('YOUR_JSON_SERVICE_ACCOUNT_CREDENTIALS.json', 'r') as f:
    gcs_output = GcsServiceAccountOutput(
        name='YOUR-BITMOVIN-GSC-OUTPUT-NAME',
        bucket_name='bitmovin-encoding-output-bucket',
        service_account_credentials=f.read()
    )

gcs_output = bitmovin_api.encoding.outputs.gcs_service_account.create(gcs_output)
print(f'Successfully created GCS Service Account with Output ID: {gcs_output.id}')

import com.bitmovin.api.sdk.BitmovinApi;
import com.bitmovin.api.sdk.model.GcsServiceAccountOutput;
import java.nio.file.Files;
import java.nio.file.Paths;

BitmovinApi bitmovinApi = BitmovinApi.builder()
    .withApiKey("YOUR_BITMOVIN_API_KEY")
    // .withTenantOrgId("YOUR_TENANT_ORG_ID")
    .build();

String credentials = new String(Files.readAllBytes(Paths.get("YOUR_JSON_SERVICE_ACCOUNT_CREDENTIALS.json")));

GcsServiceAccountOutput gcsOutput = new GcsServiceAccountOutput();
gcsOutput.setName("YOUR-BITMOVIN-GCS-OUTPUT-NAME");
gcsOutput.setBucketName("bitmovin-encoding-output-bucket");
gcsOutput.setServiceAccountCredentials(credentials);

gcsOutput = bitmovinApi.encoding.outputs.gcsServiceAccount.create(gcsOutput);
System.out.println("Successfully created GCS Service Account with Output ID: " + gcsOutput.getId());

For more examples, see the Bitmovin API SDK Examples repository on GitHub.

ℹ️

Sub-Organizations: If you are working within a Bitmovin sub-organization, add the tenantOrgId option on the API client, set to the ID of the target organization.

Congratulations! Your GCS Service Account Input is now ready to use!

The ID contained in gcs_output.id the response is your input ID, which you can use in future encoding jobs.

(Optional) Step 4: Configure Public Access and CORS (If Serving Directly from the Bucket)

The Service Account we configured above only grants Bitmovin the ability to write files to your bucket. Note that, if you set your Google Cloud Storage bucket to Private access, you will not be able to immediately play the resulting DASH/HLS URLs in a web browser.

For Production: The most common option is to keep the bucket private and place a CDN (like Google Cloud CDN or Cloudflare) in front of it to securely and efficiently deliver the video segments to your users.

For Quick Testing: If you want to verify your encoding job, you can temporarily grant the Storage Object Viewer permission to allUsers on your output bucket and configure CORS. Without it, browsers will block cross-origin requests for segments and manifests.

1. Create a CORS configuration file (e.g. cors-config.json):

[
  {
    "origin": ["*"],
    "method": ["GET", "HEAD"],
    "responseHeader": ["Content-Type"],
    "maxAgeSeconds": 3600
  }
]

You can replace "*" with the specific domain(s) of the website that will host your video player for additional security.

2. Apply it to your bucket using the gsutil CLI:

gsutil cors set cors-config.json gs://YOUR-BUCKET-NAME

3. To verify the configuration was applied:

gsutil cors get gs://YOUR-BUCKET-NAME

For more details, see Setting Up CORS for Your GCS Bucket.

Common Issues

Authentication failure on encoding start

Ensure the serviceAccountCredentials JSON key file is correctly serialized as a compact single-line string with all newlines inside the private_key escaped as \n. This should be the default format when the file is automatically downloaded.

403 Forbidden / upload fails mid-encoding

Ensure the Service Account has the Storage Object Admin role. Note that the Storage Object Viewer role (sufficient for inputs) is not enough for outputs. Verify the IAM bindings in the GCP Console under IAM & Admin → IAM. Also confirm that the role is assigned to the correct Service Account email.

Encoding fails to write output file

Verify that bucketName exactly matches your bucket name (case-sensitive) and that the name does not contain underscores (_).

Objects written but not accessible for playback

If you are trying to access your GCS bucket directly, ensure the bucket is configured for public access and verify that CORS is configured correctly if the content will be accessed from a web browser. See Setting Up CORS for Your GCS Bucket.

Further Reading

• Setting Up a GCS Input (Service Account)
• Service accounts overview  |  Identity and Access Management (IAM)  |  Google Cloud Documentation
• About Cloud Storage buckets  |  Google Cloud Documentation
• Required Permissions for GCS Buckets for Encoding Input and Output
• Setting Up CORS for Your GCS Bucket
• Troubleshooting Output Transfer Failures