API Reference
Gemini Omni Create-Character
Use the create character endpoint to receive a result in the same response.
01
Overview
Use the create character endpoint and read the result from the same response.
Quick start
- Create an API key and set it as RUNAPI_API_KEY.
- Send a POST request whose body matches the request schema.
- Read the result from the successful response body.
Endpoint
- Base URL
https://runapi.ai- API version
v1- Authentication
Authorization: Bearer YOUR_API_TOKEN
02
Supported models
Open a model page for current pricing, rate limits, and commercial-usage details.
03
JSON bodyRequest schema
Send only the fields declared for this endpoint.
gemini-omni-character4 fields
audio_idsarray
Optional
Audio preset IDs returned by create-audio.
character_namestring
Optional
Character display name.
Bound:210
descriptionsstring
Required
Character appearance, identity, style, clothing, or personality description.
Bound:20000
reference_image_urlstring
Required
Public character reference image URL.
04
HTTP 200Success response
POST /api/v1/gemini_omni/create_character
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"character": {
"properties": {
"id": {
"description": "Created character identifier.",
"type": "string"
},
"images": {
"description": "Character reference images.",
"items": {
"properties": {
"url": {
"type": "string"
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"name": {
"description": "Character display name.",
"type": "string"
}
},
"required": [
"id"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"description": "Created character identifier.",
"type": "string"
}
},
"required": [
"id",
"character",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"character": {
"id": "chr_reference_presenter",
"images": [
{
"url": "https://cdn.runapi.ai/public/samples/upscale.jpg"
}
],
"name": "Studio Presenter"
},
"id": "chr_reference_presenter"
}05
HTTP 401Errors
POST /api/v1/gemini_omni/create_character
This response has no body.
06
HTTP 400Errors
POST /api/v1/gemini_omni/create_character
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": {
"code": "descriptions_is_required",
"message": "descriptions is required"
}
}07
HTTP 402Errors
POST /api/v1/gemini_omni/create_character
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": {
"code": "insufficient_balance",
"message": "Insufficient balance"
}
}08
HTTP 403Errors
POST /api/v1/gemini_omni/create_character
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": {
"code": "api_token_credit_limit_exceeded",
"message": "API key credit limit exceeded"
}
}09
HTTP 409Errors
POST /api/v1/gemini_omni/create_character
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": {
"code": "request_conflict",
"message": "The request uses features that are not supported for the selected model"
}
}10
HTTP 429Errors
POST /api/v1/gemini_omni/create_character
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": {
"code": "rate_limited",
"message": "Rate limit reached. Please retry later."
}
}11
HTTP 503Errors
POST /api/v1/gemini_omni/create_character
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"error": {
"code": "service_unavailable",
"message": "Service under maintenance, please try again later"
}
}12
HTTP 504Errors
POST /api/v1/gemini_omni/create_character
Response schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": {
"code": "timeout_error",
"message": "The request timed out"
}
}13
Generated Code Samples
Use cURL directly, or install an SDK for your language. Each sample submits the validated request shown in this reference.
CURL
curl -X POST https://runapi.ai/api/v1/gemini_omni/create_character \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"descriptions":"A presenter wearing a blue jacket in a bright studio.","reference_image_url":"https://cdn.runapi.ai/public/samples/upscale.jpg","character_name":"Studio Presenter"}'Install
BASH
npm install @runapi.ai/gemini-omni
JAVASCRIPT
import { GeminiOmniClient } from "@runapi.ai/gemini-omni";
const client = new GeminiOmniClient({ apiKey: process.env.RUNAPI_API_KEY });
const result = await client.createCharacter.run({
"descriptions": "A presenter wearing a blue jacket in a bright studio.",
"reference_image_url": "https://cdn.runapi.ai/public/samples/upscale.jpg",
"character_name": "Studio Presenter"
});Install
BASH
pip install runapi-gemini-omni
PYTHON
import os
from runapi.gemini_omni import GeminiOmniClient
client = GeminiOmniClient(api_key=os.environ["RUNAPI_API_KEY"])
result = client.create_character.run(
descriptions="A presenter wearing a blue jacket in a bright studio.",
reference_image_url="https://cdn.runapi.ai/public/samples/upscale.jpg",
character_name="Studio Presenter"
)Install
BASH
go get github.com/runapi-ai/gemini-omni-sdk/go@latest
GO
package main
import (
"context"
"log"
"os"
"github.com/runapi-ai/core-sdk/go/option"
geminiomni "github.com/runapi-ai/gemini-omni-sdk/go/geminiomni"
)
func main() {
client, err := geminiomni.NewClient(option.WithAPIKey(os.Getenv("RUNAPI_API_KEY")))
if err != nil {
log.Fatal(err)
}
result, err := client.CreateCharacter.Run(context.Background(), geminiomni.CreateCharacterParams{
Descriptions: "A presenter wearing a blue jacket in a bright studio.",
ReferenceImageURL: "https://cdn.runapi.ai/public/samples/upscale.jpg",
CharacterName: "Studio Presenter",
})
if err != nil {
log.Fatal(err)
}
_ = result
}Install
BASH
gem install runapi-gemini-omni
RUBY
require "runapi/gemini_omni"
client = RunApi::GeminiOmni::Client.new(api_key: ENV.fetch("RUNAPI_API_KEY"))
result = client.create_character.run(
descriptions: "A presenter wearing a blue jacket in a bright studio.",
reference_image_url: "https://cdn.runapi.ai/public/samples/upscale.jpg",
character_name: "Studio Presenter"
)Install
KOTLIN
implementation("ai.runapi:runapi-gemini-omni")
JAVA
import ai.runapi.geminiomni.GeminiOmniClient;
import ai.runapi.geminiomni.types.CreateCharacterParams;
import ai.runapi.geminiomni.types.CreateCharacterResponse;
public final class Example {
public static void main(String[] args) {
GeminiOmniClient client = GeminiOmniClient.builder()
.apiKey(System.getenv("RUNAPI_API_KEY"))
.build();
CreateCharacterResponse result = client.createCharacter().run(
CreateCharacterParams.builder()
.descriptions("A presenter wearing a blue jacket in a bright studio.")
.referenceImageUrl("https://cdn.runapi.ai/public/samples/upscale.jpg")
.characterName("Studio Presenter")
.build()
);
}
}Install
BASH
composer require runapi-ai/gemini-omni
PHP
<?php
require __DIR__ . '/vendor/autoload.php';
use RunApi\Core\ClientOptions;
use RunApi\GeminiOmni\GeminiOmniClient;
$client = new GeminiOmniClient(new ClientOptions(apiKey: getenv('RUNAPI_API_KEY')));
$result = $client->createCharacter->run([
"descriptions" => "A presenter wearing a blue jacket in a bright studio.",
"reference_image_url" => "https://cdn.runapi.ai/public/samples/upscale.jpg",
"character_name" => "Studio Presenter"
]);