The Giotto API lets developers add Giotto-powered responses and agentic workflows to applications. Use the Python SDK to authenticate, send a request, and retrieve the completed response.
This page explains the available integration paths and directs you to the appropriate setup guide. If you want to send your first request immediately, see Quick start: Make your first API request with Python.
What you can build
- Question-answering and developer-assistance experiences
- Content generation and transformation workflows
- Asynchronous jobs that do not block your application
- Interfaces that display Giotto orchestration events
- Questions about specific public web pages using the deployed URL-crawling tool
For complete examples, see Giotto API use cases.
Choose an integration path
| Path | Recommended for | Next step |
|---|---|---|
| Giotto Python SDK | New Python applications and services | Complete the Python quick start |
| OpenAI-compatible integration | Tools that support a configurable OpenAI-compatible endpoint | Connect an OpenAI-compatible tool to Giotto |
| On-prem agent configuration | Giotto deployments that manage their own agent topology and infrastructure | Giotto on-prem documentation |
Availability: Some SDK features, including defining and deploying agent topologies, are intended for on-prem deployments and are not available on Giotto Cloud. Each reference section identifies its availability.
How requests work
- Your application authenticates with a Giotto client ID and client secret.
- Your application sends input to a Giotto model or deployed orchestrator.
- Giotto starts the request and assigns it a request ID.
- The SDK waits for completion by default and returns a response object.
- Your application reads the generated text and, where applicable, other response data.
The Python SDK handles authentication and orchestration polling for you. You can also start a request without waiting or iterate over orchestration events.
Before you begin
To use Giotto Cloud, you need:
- a Giotto account with API access;
- a positive by-token API credit balance;
- a client ID and client secret for the API product you intend to use;
- Python (3.10 or later) for the Python SDK; and
- a supported model name, such as
giotto-alto.
Credentials and security
Credentials are created in the API management tab of the Giotto API section. Create a credential for your by-token API credits.
Store the client secret in environment variables or a secrets manager. Do not place it directly in source code, send it to a browser, share it publicly, or commit it to a repository. If a secret is exposed, rotate it in Giotto and update the applications that use it.
API surfaces
Responses API
The Responses API is the recommended high-level interface for new integrations. It accepts an input and optional reusable instructions, then returns a response object with helpers such as output_text.
Chat Completions compatibility
The Python SDK provides a chat-completions-style interface for applications that already use message arrays. For new applications, prefer the Responses API.
Synchronous, deferred, and event-streaming requests
By default, the SDK waits for the final response. You can instead return after the request starts and wait later, or iterate over normalized orchestration events. Event streaming reports model calls, handoffs, tool activity, and the final event; it is not token-by-token text streaming.
Comments
0 comments
Please sign in to leave a comment.