Go SDK
Convert files between 240+ formats from Go. One call uploads your file, converts it, waits and downloads the result; jobs, webhooks and the format list are there when you need more. Go 1.21+, standard library only, every call takes a context.
Installing
Install it with your package manager. Go 1.21+.
$ go get github.com/runconvert/runconvert-goInitializing
runconvert.New(apiKey string, opts ...Option) *ClientCreate one client and reuse it. Without an API key it reads the RUNCONVERT_API_KEY environment variable. Get a key in Dashboard → API Keys, and keep it on your server: never put it in browser or mobile app code. Pass "" to read the environment variable.
Example
import runconvert "github.com/runconvert/runconvert-go"
rc := runconvert.New("") // reads RUNCONVERT_API_KEYrc := runconvert.New(os.Getenv("RUNCONVERT_API_KEY"),
runconvert.WithTimeout(60*time.Second),
runconvert.WithMaxRetries(2),
)Parameters
apiKeystringYour API key, or "" to read RUNCONVERT_API_KEY.RequiredWithBaseURL(u)OptionDefaults to https://api.runconvert.com/v3.WithTimeout(d)OptionTime limit per API request. Default 60s. Uploads and downloads have none.WithMaxRetries(n)OptionRetries for network errors, 429 and 5xx. Default 2.WithHTTPClient(h)OptionYour own *http.Client, e.g. for proxies.
Quick start
Convert a file in one call: the SDK uploads it, converts it, waits for the job and saves the result.
Example
package main
import (
"context"
"fmt"
"log"
runconvert "github.com/runconvert/runconvert-go"
)
func main() {
rc := runconvert.New("")
res, err := rc.Convert(context.Background(), "report.docx",
runconvert.ConvertOptions{To: "pdf", OutDir: "out"})
if err != nil {
log.Fatal(err)
}
fmt.Println(res.Saved) // [out/report.pdf]
}[out/report.pdf]Convert
Convert a file
rc.Convert(ctx, input any, o ConvertOptions) (*ConvertResult, error)Converts one file in one call: uploads a local file (or imports a URL), converts it, waits for the job and, when an output folder is given, downloads the result. Uses credits. Limit the wait with the context's deadline.
Example
res, err := rc.Convert(ctx, "report.docx",
runconvert.ConvertOptions{To: "pdf", OutDir: "out"})
if err != nil {
return err
}
fmt.Println(res.Saved)// Imported by RunConvert: nothing to upload
res, err := rc.Convert(ctx, "https://example.com/talk.mp4",
runconvert.ConvertOptions{To: "mp3", OutDir: "out"})res, err := rc.Convert(ctx, "talk.mp4", runconvert.ConvertOptions{
To: "mp3",
Options: map[string]any{"audioBitrate": "192k"},
OutDir: "out",
})ctx, cancel := context.WithTimeout(ctx, 10*time.Minute)
defer cancel()
res, err := rc.Convert(ctx, "movie.mov", runconvert.ConvertOptions{
To: "mp4",
OutDir: "out",
OnUpdate: func(j *runconvert.Job) { fmt.Println(j.Status) },
})[out/report.pdf][out/talk.mp3]waiting
processing
finishedParameters
inputanyA local path, an http(s) URL (imported by RunConvert), or an io.Reader (then set Filename or From).RequiredTostringThe target format, e.g. "pdf" or "mp3".RequiredFromstringThe source format. Read from the file name or URL when left out; needed for bytes or streams without a filename.Optionsmap[string]anyEngine options for the conversion, e.g. audioBitrate or image_quality. List them with Formats → engines for a pair.OutDirstringSave the results in this folder (created if needed). Without it nothing is downloaded; use the result's files.FilenamestringThe file's name for an io.Reader input (also sets From).TagstringA label to find the job later, e.g. "invoices".OnUpdatefunc(*Job)Called with the job after every check, e.g. to show progress.
Returns
*ConvertResult with Job (the finished job), Files (each with Filename, URL and Size) and Saved (local paths, when OutDir is set).
Jobs
Create a job
rc.Jobs.Create(ctx, runconvert.JobCreate{Tasks, Tag, Metadata}) (*Job, error)Creates a job from named tasks that run in order: import → convert → export. Tasks refer to each other by name in input. The job comes back with its tasks; an upload task carries the upload_url to send your file to. Build tasks with ImportURL, ImportUpload, ConvertTask and ExportURL.
Example
job, err := rc.Jobs.Create(ctx, runconvert.JobCreate{
Tag: "merge",
Tasks: map[string]runconvert.TaskDefinition{
"a": runconvert.ImportURL("https://example.com/cover.pdf"),
"b": runconvert.ImportURL("https://example.com/body.pdf"),
"merge": runconvert.ConvertTask("pdf", "pdf", []string{"a", "b"}, nil),
"export": runconvert.ExportURL("merge"),
},
})job, err := rc.Jobs.Create(ctx, runconvert.JobCreate{
Tasks: map[string]runconvert.TaskDefinition{
"upload": runconvert.ImportUpload(),
"convert": runconvert.ConvertTask("png", "webp", "upload", map[string]any{"image_quality": 80}),
"export": runconvert.ExportURL("convert"),
},
})
err = rc.Files.Upload(ctx, job.Task("upload").UploadURL, "image.png", "")Parameters
Tasksmap[string]TaskDefinitionNamed task definitions. Names use letters, digits, - or _ (up to 64 characters).RequiredTagstringA label to find the job later, e.g. "invoices".Metadatamap[string]anyYour own key-value data, returned with the job and in webhooks.
Returns
The job, with its tasks.
Get a job
rc.Jobs.Get(ctx, id string) (*Job, error)Gets one job with its tasks: status, credits used, and the result files of its export tasks.
Example
job, err := rc.Jobs.Get(ctx, "job_01hx4k9m2p7w")
fmt.Println(job.Status){
"id": "job_01hx4k9m2p7w",
"status": "finished",
"tag": "invoices",
"credits_used": 2,
"created_at": "2026-11-16T09:12:04Z",
"ended_at": "2026-11-16T09:12:09Z",
"tasks": [
{ "name": "import-1", "operation": "import/direct/upload", "status": "finished" },
{ "name": "convert-1", "operation": "convert", "status": "finished" },
{ "name": "export-1", "operation": "export/url", "status": "finished",
"result": { "files": [
{ "filename": "report.pdf", "size": 72841, "url": "https://storage.runconvert.com/…/report.pdf" }
] } }
]
}Parameters
idstringThe job's ID.Required
Returns
The job, with its tasks.
List jobs
rc.Jobs.List(ctx, runconvert.ListParams{Status, Tag, Page, PerPage, IncludeTasks}) ([]*Job, ListMeta, error)One page of jobs, newest first, with paging details. Filter by status or tag.
Example
jobs, meta, err := rc.Jobs.List(ctx, runconvert.ListParams{Status: "finished", PerPage: 20})
for _, j := range jobs {
fmt.Println(j.ID)
}
fmt.Println(meta.TotalPages){
"data": [ { "id": "job_01hx4k9m2p7w", "status": "finished", … } ],
"meta": { "page": 1, "per_page": 20, "total": 42, "total_pages": 3 }
}Parameters
StatusstringOnly jobs with this status: waiting, processing, finished, error or canceled.TagstringA label to find the job later, e.g. "invoices".PageintPage number, from 1.PerPageintJobs per page (max 100).IncludeTasksboolInclude each job's tasks.
Returns
The page's jobs and ListMeta (Page, PerPage, Total, TotalPages).
Every job
rc.Jobs.All(ctx, p ListParams, fn func(*Job) bool) errorEvery job, page by page, so you can loop over all of them without handling pages yourself. Return false from fn to stop early.
Example
err := rc.Jobs.All(ctx, runconvert.ListParams{Tag: "invoices"}, func(j *runconvert.Job) bool {
fmt.Println(j.ID, j.Status)
return true
})Parameters
pListParamsThe same filters as List, without Page.fnfunc(*Job) boolCalled for each job; return false to stop.Required
Wait for a job
rc.Jobs.Wait(ctx, id string, runconvert.WaitOptions{Timeout, OnUpdate, NoErrorOnFail}) (*Job, error)Polls a job until it finishes (every 0.7 s, slowing to 3 s). Fails with the task's code and reason if the job fails, and stops after the timeout if you give one.
Example
done, err := rc.Jobs.Wait(ctx, job.ID, runconvert.WaitOptions{Timeout: 5 * time.Minute})
if err != nil {
return err
}
for _, f := range done.ExportedFiles() {
rc.Files.Download(ctx, f.URL, "out", "")
}_, err := rc.Jobs.Wait(ctx, job.ID, runconvert.WaitOptions{})
var failed *runconvert.JobFailedError
if errors.As(err, &failed) {
fmt.Println(failed.Task.Code, failed.Task.Reason, failed.Task.Message)
}Parameters
idstringThe job's ID.RequiredTimeouttime.DurationGive up after this long; the error wraps ErrWaitTimeout. 0: no limit besides ctx.OnUpdatefunc(*Job)Called with the job after every check, e.g. to show progress.NoErrorOnFailboolReturn a failed job instead of *JobFailedError.
Returns
The finished job.
Cancel a job
rc.Jobs.Cancel(ctx, id string) (*Job, error)Cancels a job's pending tasks. Credits for tasks that didn't finish are refunded.
Example
job, err := rc.Jobs.Cancel(ctx, "job_01hx4k9m2p7w")Parameters
idstringThe job's ID.Required
Returns
The canceled job.
Delete a job
rc.Jobs.Delete(ctx, id string) errorDeletes a job and its files.
Example
err := rc.Jobs.Delete(ctx, "job_01hx4k9m2p7w")Parameters
idstringThe job's ID.Required
Result files
job.ExportedFiles() []FileThe files produced by a finished job's export tasks: file name, a temporary download URL and size.
Example
for _, f := range job.ExportedFiles() {
fmt.Println(f.Filename, f.URL)
}[
{ "filename": "report.pdf", "size": 72841, "url": "https://storage.runconvert.com/…/report.pdf" }
]Files
Upload a file
rc.Files.Upload(ctx, uploadURL string, file any, filename string) errorSends a file to an import/direct/upload task before its deadline. Use it with a job you created yourself.
Example
err := rc.Files.Upload(ctx, job.Task("upload").UploadURL, "image.png", "")Parameters
uploadURLstringThe upload task's UploadURL: job.Task("upload").UploadURL.RequiredfileanyA local path or an io.Reader.RequiredfilenamestringThe file's name when you pass bytes or a stream.
Download a result
rc.Files.Download(ctx, fileURL, dir, filename string) (string, error)Saves a result file into a folder, keeping its name, and returns the path. Streams, so big files use little memory.
Example
for _, f := range job.ExportedFiles() {
path, err := rc.Files.Download(ctx, f.URL, "out", "")
if err != nil {
return err
}
fmt.Println(path)
}out/report.pdfParameters
fileURLstringA result file's URL (File.URL).RequireddirstringThe folder to save into.RequiredfilenamestringSave under this name, or "" to keep the original.
Returns
The saved file's path.
Formats
List formats
rc.Operations.List(ctx, category string) (*OperationsCatalog, error)Every input format and what it converts to. Public: no API key needed.
Example
catalog, err := rc.Operations.List(ctx, "audio")
fmt.Println(len(catalog.Formats))Parameters
categorystringOnly one category: document, image, video, audio, ebook, archive, font, cad, … "" for all.
Targets for a format
rc.Operations.ForInput(ctx, input string) (*InputFormat, error)What one format converts to, with the credit cost of each conversion. Public.
Example
mp4, err := rc.Operations.ForInput(ctx, "mp4")
for _, o := range mp4.Outputs {
fmt.Println(o.Format, o.Credits)
}{
"format": "mp4",
"category": "video",
"outputs": [
{ "format": "mp3", "category": "audio", "engine": "ffmpeg", "credits": 1 },
{ "format": "gif", "category": "image", "engine": "ffmpeg", "credits": 4 },
…
]
}Parameters
inputstringThe input format, e.g. "mp4".Required
Engines for a pair
rc.Operations.ForPair(ctx, input, output string) (*PairEngines, error)The engines for one conversion and the options its convert task accepts, e.g. bitrate or quality. Public.
Example
pair, err := rc.Operations.ForPair(ctx, "mp4", "mp3")
for _, opt := range pair.Engines[0].Options {
fmt.Println(opt.Name)
}{
"input": "mp4",
"output": "mp3",
"engines": [
{ "name": "ffmpeg", "credits": 1,
"options": [
{ "name": "audioBitrate", "type": "string",
"description": "Target audio bitrate in kbps.",
"supported_values": ["32k", "48k", "64k", "80k", …] },
…
] }
]
}Parameters
inputstringThe input format, e.g. "mp4".RequiredoutputstringThe output format, e.g. "mp3".Required
Account
Credits and team
rc.Me(ctx) (*Me, error)The account, team and credit balance behind the API key.
Example
me, err := rc.Me(ctx)
fmt.Println(me.Credits.TotalRemaining){
"user": { "email": "[email protected]", "full_name": "Ada Lovelace" },
"team": { "name": "Acme" },
"credits": { "mode": "wallet", "total_remaining": 4820 }
}Webhooks
Verify a signature
runconvert.VerifySignature(rawBody []byte, signature, secret string) boolChecks that a webhook delivery really came from RunConvert: an HMAC-SHA256 of the raw request body with your webhook secret, compared with the X-RunConvert-Signature header in constant time.
Example
body, _ := io.ReadAll(r.Body)
ok := runconvert.VerifySignature(body, r.Header.Get("X-RunConvert-Signature"), os.Getenv("RUNCONVERT_WEBHOOK_SECRET"))Parameters
rawBody[]byteThe raw request body, exactly as received (not parsed JSON).RequiredsignaturestringThe X-RunConvert-Signature header.RequiredsecretstringYour webhook's signing secret.Required
Parse an event
runconvert.ConstructEvent(rawBody []byte, signature, secret string) (*WebhookEvent, error)Verifies the signature and parses the event in one step. Fails if the signature is wrong.
Returns an error when the signature doesn't match: answer 400 and ignore the request.
Example
http.HandleFunc("/webhooks/runconvert", func(w http.ResponseWriter, r *http.Request) {
body, _ := io.ReadAll(r.Body)
event, err := runconvert.ConstructEvent(body,
r.Header.Get("X-RunConvert-Signature"), os.Getenv("RUNCONVERT_WEBHOOK_SECRET"))
if err != nil {
http.Error(w, "bad signature", http.StatusBadRequest)
return
}
if event.Event == "job.finished" {
log.Println("done", event.Job.ID)
}
}){
"event": "job.finished",
"job": { "id": "job_01hx4k9m2p7w", "status": "finished", … }
}Parameters
rawBody[]byteThe raw request body, exactly as received (not parsed JSON).RequiredsignaturestringThe X-RunConvert-Signature header.RequiredsecretstringYour webhook's signing secret.Required
More
Errors
Every failure is a typed error. The API's code tells you what happened, for example BILLING_INSUFFICIENT_CREDITS, UNAUTHORIZED or INVALID_DATA.
Example
_, err := rc.Convert(ctx, "report.docx", runconvert.ConvertOptions{To: "pdf", OutDir: "out"})
var apiErr *runconvert.Error
var failed *runconvert.JobFailedError
switch {
case errors.As(err, &failed):
fmt.Println("conversion failed:", failed.Task.Reason)
case errors.As(err, &apiErr):
fmt.Println(apiErr.Status, apiErr.Code, apiErr.Message)
case errors.Is(err, runconvert.ErrWaitTimeout):
fmt.Println("still running")
}422 BILLING_INSUFFICIENT_CREDITS Insufficient credits.Error types
*runconvert.ErrorerrorThe API said no: Status (HTTP status), Code (e.g. BILLING_INSUFFICIENT_CREDITS), Message.*runconvert.JobFailedErrorerrorThe job ended in error: Job, and Task with Code, Reason and Message.runconvert.ErrWaitTimeouterrorWait ran past its Timeout. Check with errors.Is.
Retries and timeouts
Network errors, rate limits (429) and server errors (5xx) are retried twice with backoff, honouring Retry-After. Creating a job is only retried when the request never reached the API, so a job is never created twice.
Example
rc := runconvert.New("",
runconvert.WithMaxRetries(4),
runconvert.WithTimeout(30*time.Second),
)