> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Go SDK Integrationsanleitung

> Platform API guide - Ace Data Cloud

[`github.com/AceDataCloud/SDK/go`](https://pkg.go.dev/github.com/AceDataCloud/SDK/go) ist das offizielle Go SDK von Ace Data Cloud, das die Chat-Vervollständigungen / Bilder / Videos / Musik / Suche von `api.acedata.cloud` in eine Methode im Stil von `client.OpenAI().Chat().Completions().Create(...)` kapselt, mit eingebautem SSE-Streaming (basierend auf Channels), automatischem Retry-Backoff und typisierten Fehlern.

Stilistisch ausgerichtet auf `context.Context` + funktionale Optionen, geeignet für jede Go-Backend-Service oder CLI.

Quellcode und Dokumentation:

* SDK-Repository: [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK)
* Go-Modul: [https://pkg.go.dev/github.com/AceDataCloud/SDK/go](https://pkg.go.dev/github.com/AceDataCloud/SDK/go)

## Installation

```bash theme={null}
go get github.com/AceDataCloud/SDK/go
```

Ausgabe der Versionsprüfung für saubere Go-Module:

```text theme={null}
$ go list -m github.com/AceDataCloud/SDK/go
github.com/AceDataCloud/SDK/go v0.0.0-20260505072132-4a3d921f9bb4
```

Erklärung der Ergebnisse:

* Derzeit gibt es kein semver-Tag, `go get` zieht die Commit-Pseudoversion `v0.0.0-<timestamp>-<sha>`; diese Version wird in `go.sum` gesperrt, sodass Teammitglieder beim Abrufen des gleichen Codes identische Abhängigkeiten erhalten.
* Das Go SDK ist derzeit stabil mit `chat.completions` (synchron + streamend) als Hauptpfad, während Multimedia-Ressourcen (`images` / `video` / `audio`) und `TaskHandle`-Polling sich in der Alpha-Phase befinden. Für Szenarien, die diese Fähigkeiten benötigen, wählen Sie bitte zuerst das [TypeScript SDK](https://platform.acedata.cloud/documents/sdk-typescript) oder das [Python SDK](https://platform.acedata.cloud/documents/sdk-python).

## API-Token vorbereiten

Siehe [SDK-Übersicht - API-Token beantragen](https://platform.acedata.cloud/documents/acedatacloud-sdk#申请-api-token) um ein Token zu erhalten, und dann im Shell `export`:

```bash theme={null}
export ACEDATACLOUD_API_TOKEN={token}
```

Beim Erstellen des Clients wird das Token explizit über die Option `WithAPIToken(...)` injiziert; das Go SDK liest Umgebungsvariablen nicht automatisch, sodass der Anwendungscode `os.Getenv` verwenden muss, was in Szenarien mit mehreren Konten oder Selbsttests besser kontrollierbar ist.

## Beispiel 1: chat.completions (nicht streamend)

```go theme={null}
package main

import (
    "context"
    "fmt"
    "os"
    "time"

    adc "github.com/AceDataCloud/SDK/go"
)

func main() {
    client, err := adc.NewClient(adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_TOKEN")))
    if err != nil {
        panic(err)
    }
    ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
    defer cancel()

    t0 := time.Now()
    res, err := client.OpenAI().Chat().Completions().Create(ctx, adc.ChatCompletionRequest{
        Model:     "gpt-4o-mini",
        Messages:  []map[string]any{{"role": "user", "content": "Antworten Sie genau mit: ADC_GO_SDK_OK"}},
        MaxTokens: 20,
    })
    if err != nil {
        panic(err)
    }
    fmt.Println("elapsed_ms", time.Since(t0).Milliseconds())
    fmt.Println("id", res["id"])
    fmt.Println("model", res["model"])
    choices := res["choices"].([]any)
    msg := choices[0].(map[string]any)["message"].(map[string]any)
    fmt.Println("content", msg["content"])
    usage := res["usage"].(map[string]any)
    fmt.Printf("usage prompt=%v completion=%v total=%v\n",
        usage["prompt_tokens"], usage["completion_tokens"], usage["total_tokens"])
}
```

Ausgabe des Programms:

```text theme={null}
elapsed_ms 6436
id chatcmpl-89DHExvFvBc4ciIPfolZYUOy7ivxv
model gpt-4o-mini
content ADC_GO_SDK_OK
usage prompt=16 completion=5 total=21
```

Erklärung der Ergebnisse:

* `id` ist die OpenAI-kompatible Antwort-ID, die im [Nutzungsverlauf](https://platform.acedata.cloud/console/usages) in der Konsole gefunden werden kann.
* `content ADC_GO_SDK_OK` ist die tatsächliche Ausgabe des Modells, die beweist, dass das SDK die Antwort nicht verändert hat.
* In 6,4 Sekunden war der größte Teil die erste TLS-Handschlag + Modellerzeugung, nach der Wiederverwendung der Client-Instanz sind die Latenzen mit TS / Python konsistent (ca. 2\~3 Sekunden).
* Die Antwort ist einheitlich `map[string]any`, was Typassertionen erfordert; dies ist das aktuelle Design des Go SDK — die Nicht-Einführung von generischen Structs soll verhindern, dass die Multi-Modell-Routing stark von einem einzigen Antwortschema abhängt.

## Beispiel 2: chat.completions (SSE streamend)

`CreateStream` gibt zwei Channels zurück: `&lt;-chan map[string]any` ist der schrittweise analysierte SSE-Chunk, `&lt;-chan error` hat erst nach dem Ende des Streams (normal oder fehlerhaft) lesbare Elemente.

```go theme={null}
package main

import (
    "context"
    "fmt"
    "os"
    "time"

    adc "github.com/AceDataCloud/SDK/go"
)

func main() {
    client, err := adc.NewClient(adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_TOKEN")))
    if err != nil {
        panic(err)
    }
    ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
    defer cancel()

    t0 := time.Now()
    chunks, errs := client.OpenAI().Chat().Completions().CreateStream(ctx, adc.ChatCompletionRequest{
        Model:     "gpt-4o-mini",
        Messages:  []map[string]any{{"role": "user", "content": "Zähle von 1 bis 5, getrennt durch Leerzeichen. Nur die Zahlen."}},
        MaxTokens: 30,
    })

    first := int64(-1)
    cnt := 0
    collected := ""
    for chunk := range chunks {
        if first < 0 {
            first = time.Since(t0).Milliseconds()
        }
        cnt++
        if ch, ok := chunk["choices"].([]any); ok && len(ch) > 0 {
            if c0, ok := ch[0].(map[string]any); ok {
                if d, ok := c0["delta"].(map[string]any); ok {
                    if s, ok := d["content"].(string); ok {
                        collected += s
                    }
                }
            }
        }
    }
    if e, ok := <-errs; ok && e != nil {
        fmt.Println("stream_err", e)
    }
    fmt.Println("total_elapsed_ms", time.Since(t0).Milliseconds())
    fmt.Println("first_chunk_ms", first)
    fmt.Println("chunks", cnt)
    fmt.Println("collected", collected)
}
```

Ausgabe des Programms:

```text theme={null}
total_elapsed_ms 1816
first_chunk_ms 1633
chunks 13
collected 1 2 3 4 5
```

Erklärung der Ergebnisse:

* Der erste Frame benötigte 1633 ms, alle 13 Chunks zusammen benötigten 1816 ms — die letzten 12 Frames benötigten nur 183 ms.
* `range chunks` wird natürlich beim Ende des Streams die Schleife verlassen; der `errs`-Channel gibt immer maximal ein Element aus, das mit `ok` überprüft werden kann, um den Fehler zu erhalten.
* Der Vorteil dieses Channel-Stils ist, dass er direkt mit `select` in Verbindung mit `context.Context` für Timeout / Abbruch verwendet werden kann, ohne zusätzliche Verpackung.

## Beispiel 3: Typisierte Fehlerbehandlung

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"

    adc "github.com/AceDataCloud/SDK/go"
)

func main() {
    bad, _ := adc.NewClient(adc.WithAPIToken("definitiv-nicht-ein-echter-token"))
    _, err := bad.OpenAI().Chat().Completions().Create(context.Background(), adc.ChatCompletionRequest{
        Model:    "gpt-4o-mini",
        Messages: []map[string]any{{"role": "user", "content": "hi"}},
        MaxTokens: 5,
    })
    if err != nil {
        var apiErr *adc.APIError
        if errors.As(err, &apiErr) {
            fmt.Println("status:", apiErr.StatusCode)
            fmt.Println("code:", apiErr.Code)
            fmt.Println("message:", apiErr.Message)
        } else {
            fmt.Println("andere Fehler:", err)
        }
    }
}
```

`adc.APIError` deckt gleichzeitig 401 / 403 / 404 / 422 / 429 / 5xx ab, der Geschäftscode verwendet `errors.As`, um die strukturierten Felder zu erhalten. HTTP-Statuscodes, Server `code` und `message` bleiben unverändert. Netzwerkfehler (DNS-Fehler, Verbindungsabbruch usw.) verwenden Standard-Go-Fehler wie `context.DeadlineExceeded`, `net.OpError` usw. und werden nicht unterdrückt.

## Konfigurationsoptionen (funktionale Optionen)

```go theme={null}
client, err := adc.NewClient(
    // Pflichtfeld: API-Token; empfohlen aus Umgebungsvariablen zu lesen
    adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_TOKEN")),

    // Plattform-API-Stammadresse, standardmäßig https://api.acedata.cloud
    adc.WithBaseURL("https://api.acedata.cloud"),

    // Timeout für eine einzelne Anfrage, standardmäßig 5 Minuten
    adc.WithTimeout(60*time.Second),

    // Anzahl der automatischen Wiederholungen, standardmäßig 2
    adc.WithMaxRetries(2),

    // Benutzerdefinierte Anfrageheader
    adc.WithHeader("x-app", "mein-dienst/1.0"),
)
```

`NewClient` gibt `(*Client, error)` zurück: Wenn der Token leer ist **und** `WithPaymentHandler` nicht übergeben wurde (X402), wird sofort ein Fehler ausgegeben, um fehlende Konfigurationen bereits beim Start des Dienstes zu erkennen.

## Fortgeschritten: Client wiederverwenden

Das Go SDK verwendet intern einen `*http.Client` + `http.Transport`, der einen Verbindungspool und HTTP/2-Wiederverwendung mitbringt. **Es wird empfohlen, innerhalb des Lebenszyklus des Prozesses nur einen `*adc.Client` zu erstellen** und diesen dann zwischen Goroutinen zu teilen – alle Methoden sind nebenläufig sicher.

```go theme={null}
// pkg/acelearn/client.go
var sharedClient *adc.Client

func init() {
    var err error
    sharedClient, err = adc.NewClient(adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_TOKEN")))
    if err != nil {
        log.Fatal(err)
    }
}

func Chat(ctx context.Context, model, prompt string) (string, error) {
    res, err := sharedClient.OpenAI().Chat().Completions().Create(ctx, adc.ChatCompletionRequest{
        Model:    model,
        Messages: []map[string]any{{"role": "user", "content": prompt}},
    })
    if err != nil {
        return "", err
    }
    return res["choices"].([]any)[0].(map[string]any)["message"].(map[string]any)["content"].(string), nil
}
```

## Einschränkungen und Fahrplan

Aktuell stabil / für die Produktion empfohlen:

* ✅ `client.OpenAI().Chat().Completions().Create` synchron nicht-streaming
* ✅ `client.OpenAI().Chat().Completions().CreateStream` SSE-streaming
* ✅ `errors.As` + `APIError` Fehlerbehandlung
* ✅ Automatische Wiederholungen + exponentielles Backoff

Noch in Alpha:

* 🚧 `client.Images()` / `client.Video()` / `client.Audio()` — Schnittstellen sind in Entwicklung, empfohlen wird, zunächst direkt über HTTP zu arbeiten
* 🚧 `TaskHandle` asynchrone Abfrage — noch nicht im Go SDK sichtbar
* 🚧 `WithPaymentHandler` (X402 On-Chain-Zahlung) — in Planung, derzeit unterstützt X402 nur [TypeScript](https://platform.acedata.cloud/documents/x402-typescript-sdk) und [Python](https://platform.acedata.cloud/documents/x402-python-sdk)

## So überprüfen Sie das verbleibende Guthaben

Über [Ace Data Cloud Konsole - Anwendungsübersicht](https://platform.acedata.cloud/console/applications) können Sie das aktuelle Guthaben Ihres Kontos einsehen.

Über [Ace Data Cloud Konsole - Nutzungshistorie](https://platform.acedata.cloud/console/usages) können Sie alle Nutzungshistorien und Abrechnungsdetails einsehen.

## Mehr erfahren

* 🟦 [`github.com/AceDataCloud/SDK/go` auf pkg.go.dev](https://pkg.go.dev/github.com/AceDataCloud/SDK/go)
* 🗂 [SDK Quellcode](https://github.com/AceDataCloud/SDK/tree/main/go)
* 📘 [TypeScript SDK Integrationsanleitung](https://platform.acedata.cloud/documents/sdk-typescript)
* 🐍 [Python SDK Integrationsanleitung](https://platform.acedata.cloud/documents/sdk-python)
* 🔌 [SDK + X402 Zahlungs-Hooks](https://platform.acedata.cloud/documents/sdk-x402-payment)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.