Quickstart

This guide walks you through submitting your first transcoding job. By the end, you will have converted a video to H.264 MP4 using the Transcodely API.

Prerequisites

A Transcodely account with an organization and app
An API key (create one from the dashboard or via the API)
A video file accessible via a public HTTPS URL, or stored in a GCS/S3 bucket with an Origin configured

Step 1: Get Your API Key

If you do not have an API key yet, create one from the dashboard under Settings > API Keys. You will receive a key that looks like this:

ak_test_AbCdEf1234567890GhIjKlMn

Test keys (ak_test_) work against the sandbox environment. Use live keys (ak_live_) for production workloads.

Step 2: Create an Origin

Before submitting jobs, you need at least one storage Origin for outputs. Create an Origin pointing to your cloud storage bucket:

curl -X POST https://api.transcodely.com/transcodely.v1.OriginService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "My Output Bucket",
    "permissions": ["read", "write"],
    "gcs": {
      "bucket": "my-transcoded-videos",
      "credentials": {
        "service_account_json": "{...}"
      }
    }
  }'

const origin = await client.origins.create({
  name: "My Output Bucket",
  permissions: [OriginPermission.READ, OriginPermission.WRITE],
  gcs: {
    bucket: "my-transcoded-videos",
    credentials: {
      serviceAccountJson: "{...}",
    },
  },
});

origin = client.origins.create(
    name="My Output Bucket",
    permissions=["read", "write"],
    gcs={
        "bucket": "my-transcoded-videos",
        "credentials": {
            "service_account_json": "{...}",
        },
    },
)

origin, err := client.Origins.Create(ctx, &transcodely.OriginCreateParams{
	Name:        "My Output Bucket",
	Permissions: []transcodely.OriginPermission{transcodely.OriginPermissionRead, transcodely.OriginPermissionWrite},
	Gcs: &transcodely.GcsOriginConfig{
		Bucket: "my-transcoded-videos",
		Credentials: &transcodely.GcsCredentials{
			ServiceAccountJson: "{...}",
		},
	},
})

The response includes the origin ID (e.g., ori_x9y8z7w6v5) that you will use when creating jobs.

Step 3: Create a Job

Submit a transcoding job with an input video and one output specification:

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "Content-Type: application/json" 
  -d '{
    "input_url": "https://storage.example.com/source/video.mp4",
    "output_origin_id": "ori_x9y8z7w6v5",
    "outputs": [
      {
        "type": "mp4",
        "video": [
          {
            "codec": "h264",
            "resolution": "1080p",
            "quality": "standard"
          }
        ]
      }
    ],
    "priority": "standard"
  }'

const job = await client.jobs.create({
  inputUrl: "https://storage.example.com/source/video.mp4",
  outputOriginId: "ori_x9y8z7w6v5",
  outputs: [
    {
      type: OutputFormat.MP4,
      video: [
        {
          codec: VideoCodec.H264,
          resolution: Resolution.RESOLUTION_1080P,
          quality: QualityTier.STANDARD,
        },
      ],
    },
  ],
  priority: JobPriority.STANDARD,
});

job = client.jobs.create(
    input_url="https://storage.example.com/source/video.mp4",
    output_origin_id="ori_x9y8z7w6v5",
    outputs=[{
        "type": "mp4",
        "video": [{"codec": "h264", "resolution": "1080p", "quality": "standard"}],
    }],
    priority="standard",
)

job, err := client.Jobs.Create(ctx, &transcodely.JobCreateParams{
	InputUrl:       "https://storage.example.com/source/video.mp4",
	OutputOriginId: proto.String("ori_x9y8z7w6v5"),
	Outputs: []*transcodely.OutputSpec{{
		Type: transcodely.OutputFormatMP4,
		Video: []*transcodely.VideoVariant{{
			Codec:      transcodely.VideoCodecH264,
			Resolution: transcodely.Resolution1080P,
			Quality:    transcodely.QualityTierStandard,
		}},
	}},
	Priority: transcodely.JobPriorityStandard,
})

The response contains your job with its ID and initial status:

{
  "job": {
    "id": "job_a1b2c3d4e5f6",
    "status": "pending",
    "progress": 0,
    "priority": "standard",
    "outputs": [
      {
        "id": "out_g7h8i9j0k1",
        "status": "pending",
        "progress": 0
      }
    ],
    "created_at": "2026-02-28T10:30:00Z"
  }
}

Step 4: Check Job Status

Poll the job to monitor progress:

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/Get 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "Content-Type: application/json" 
  -d '{"id": "job_a1b2c3d4e5f6"}'

const job = await client.jobs.get("job_a1b2c3d4e5f6");

job = client.jobs.get(id="job_a1b2c3d4e5f6")

job, err := client.Jobs.Get(ctx, "job_a1b2c3d4e5f6")

The job progresses through these statuses: pending > probing > processing > completed.

Step 5: Retrieve the Output

Once the job reaches completed, each output includes the URL of the transcoded file:

{
  "job": {
    "id": "job_a1b2c3d4e5f6",
    "status": "completed",
    "progress": 100,
    "outputs": [
      {
        "id": "out_g7h8i9j0k1",
        "status": "completed",
        "progress": 100,
        "output_url": "gs://my-transcoded-videos/job_a1b2c3d4e5f6/out_g7h8i9j0k1.mp4",
        "output_size_bytes": 15728640,
        "duration_seconds": 120,
        "actual_cost": 0.045
      }
    ],
    "total_actual_cost": 0.045,
    "currency": "EUR"
  }
}

What’s Next

Authentication — Learn about API key environments and security best practices
Jobs API Reference — Explore the complete job lifecycle and all endpoints
Encoding Options — Understand codecs, quality tiers, and container formats

#Quickstart

#Prerequisites

#Step 1: Get Your API Key

#Step 2: Create an Origin

#Step 3: Create a Job

#Step 4: Check Job Status

#Step 5: Retrieve the Output

#What’s Next