YouVersion PlatformYouVersion Platform
PlatformContent LibraryDev Docs
CommunityPartnersSupport

YouVersion Platform

Build applications and integrate with the world's most popular Bible platform.

Platform Products

  • Platform Portal
  • Developer Documentation
  • App Management

Resources

  • Support
  • Press inquiries

Legal

  • Privacy Policy
  • Terms of Use

© 2026 YouVersion. All rights reserved.

  • Overview
  • API Reference
  • SDKs
  • Changelog
<  Back to Platform
SDK Introduction
Swift SDK
Kotlin SDK
    Quick StartComponents
    Guides
      SearchVerse imagesCopyright & AttributionMigrating to 3.0
JavaScript SDK
React SDK
React Native (Expo) SDK
Guides

Verse images

Use the Images APIs to show verse art for the Verse of the Day, a search query, or a passage. This guide covers the Kotlin SDK. For direct HTTP requests and the rules that apply to every platform, see Verse Images. For other SDKs, see the image guides for JavaScript, React, React Native Expo, and Swift.

Images APIs

Overview

Use YouVersionApi.verseImages to find verse art for a passage and to load an image that search returns. The Images APIs need platform-core 2.7.0 or later. Configure the SDK with your app key as shown in the Quick Start.

Code
import com.youversion.platform.core.api.YouVersionApi val page = YouVersionApi.verseImages.verseImages( passageId = "JHN.3.16", languageRanges = listOf("en"), ) page.data.forEach { image -> println("${image.imageUrl} ${image.attribution}") }

Each VerseImage has an imageUrl that you load with Coil, Glide, or your own image loader, and an optional attribution credit line that you can show with the image.

Validation and errors

All image methods are suspend functions. pageSize must be from 1 through 99. Invalid inputs that the SDK checks throw IllegalArgumentException. Requests can also throw YouVersionNetworkException for an error response or a response the SDK cannot read, with a reason described in Error handling, and java.io.IOException when no response arrives.

Images methods

MethodReturnsUse case
verseImagesPaginatedResponse<VerseImage>List images for a passage or language. passageId, languageRanges, pageSize, and pageToken are optional.
verseImage(imageId)VerseImageThe full record for an image id from search results or the Verse of the Day

List images for a passage

verseImages(passageId) lists the art for a passage that you already know. To find art that matches freeform text, such as "love", use Page through image results instead.

Code
import com.youversion.platform.core.api.YouVersionApi val page = YouVersionApi.verseImages.verseImages( passageId = "1CO.13.4-7", languageRanges = listOf("en"), pageSize = 10, ) val images = page.data.toMutableList() page.nextPageToken?.let { pageToken -> val nextPage = YouVersionApi.verseImages.verseImages( passageId = "1CO.13.4-7", languageRanges = listOf("en"), pageSize = 10, pageToken = pageToken, ) images += nextPage.data }

passageId is one verse, such as JHN.3.16, or a verse range, such as 1CO.13.4-7. A verse range returns images for any verse in the range. Chapters, such as JHN.3, are not supported. To show art for a whole chapter, pass a verse range that covers the chapter. Omit passageId to browse art across all passages.

pageSize accepts values from 1 through 99. When omitted, the page size is 25. To load another page, pass nextPageToken as pageToken, with the same passageId and languageRanges. You can change pageSize between pages. A null nextPageToken means there are no more pages. If no images match, data is empty. totalSize is the number of matching images across all pages. It is set only when you pass passageId, and it is null otherwise.

Display an image

This example loads the image with Coil's AsyncImage. Coil 3 loads URLs only with a network artifact, and by default it saves every response to its disk cache, whatever the Cache-Control header says. To follow the caching rules, add the coil-network-cache-control artifact as well:

build.gradle.kts
dependencies { implementation("io.coil-kt.coil3:coil-compose:3.6.3") implementation("io.coil-kt.coil3:coil-network-okhttp:3.6.3") implementation("io.coil-kt.coil3:coil-network-cache-control:3.6.3") }

If your app supports Android API 25 or lower, coil-network-cache-control also needs core library desugaring.

Your app also needs the android.permission.INTERNET permission in AndroidManifest.xml. Then give Coil an image loader that honors Cache-Control. Your Application class can provide it:

Code
import android.app.Application import coil3.ImageLoader import coil3.PlatformContext import coil3.SingletonImageLoader import coil3.annotation.ExperimentalCoilApi import coil3.network.cachecontrol.CacheControlCacheStrategy import coil3.network.okhttp.OkHttpNetworkFetcherFactory class SampleApp : Application(), SingletonImageLoader.Factory { @OptIn(ExperimentalCoilApi::class) override fun newImageLoader(context: PlatformContext): ImageLoader = ImageLoader.Builder(context) .components { add(OkHttpNetworkFetcherFactory(cacheStrategy = { CacheControlCacheStrategy() })) } .build() }

Add a size to the image URL, reserve space with aspectRatio, and, if you want a credit line, show attribution with the image:

Code
import android.net.Uri import androidx.compose.foundation.background import androidx.compose.foundation.layout.Arrangement import androidx.compose.foundation.layout.Column import androidx.compose.foundation.layout.aspectRatio import androidx.compose.foundation.layout.fillMaxWidth import androidx.compose.foundation.shape.RoundedCornerShape import androidx.compose.material3.MaterialTheme import androidx.compose.material3.Text import androidx.compose.runtime.Composable import androidx.compose.ui.Modifier import androidx.compose.ui.draw.clip import androidx.compose.ui.unit.dp import coil3.compose.AsyncImage import com.youversion.platform.core.verseimages.models.VerseImage @Composable fun VerseImageCard(image: VerseImage, contentDescription: String?) { val cardUrl = Uri.parse(image.imageUrl).buildUpon() .appendQueryParameter("size", "card") .build() Column(verticalArrangement = Arrangement.spacedBy(8.dp)) { AsyncImage( model = cardUrl, contentDescription = contentDescription, modifier = Modifier .fillMaxWidth() .aspectRatio(image.aspectRatio.toFloat()) .clip(RoundedCornerShape(12.dp)) .background(MaterialTheme.colorScheme.surfaceVariant), ) Text( text = image.attribution, style = MaterialTheme.typography.bodySmall, color = MaterialTheme.colorScheme.onSurfaceVariant, ) } }

VerseImage has passageId and languageTag, but not verse text, an accessibility description, or a Bible version id. When the art conveys content that is not already on screen, pass a passage label as contentDescription or show nearby text from a Bible component. When equivalent verse text is already accessible, pass null so TalkBack skips the redundant art.

Set the URL's size query parameter to thumb, card, or full, preserving existing parameters. See Picking a size for width presets and image sizes.

Verse of the Day art

Requesting the day's selected image requires platform-core 2.8.0 or later.

Request the day's passage and selected image with verseOfTheDay(dayOfTheYear, languageRanges). Pass language ranges in order of preference. When the day has art, pass its imageId to verseImage(imageId):

Code
import com.youversion.platform.core.api.YouVersionApi import com.youversion.platform.core.verseimages.models.VerseImage suspend fun votdImage(dayOfYear: Int, languageRanges: List<String>): VerseImage? { val votd = YouVersionApi.votd.verseOfTheDay( dayOfTheYear = dayOfYear, languageRanges = languageRanges, ) val imageId = votd.imageId if (imageId == null) { // No image is available for this day. return null } return YouVersionApi.verseImages.verseImage(imageId = imageId) }

Pass the returned image to VerseImageCard from Display an Image. imageId is null when no art matches the requested languages. If you do not provide language ranges, you get no image data.

To fetch the full year's calendar, call YouVersionApi.votd.verseOfTheDays(languageRanges). It returns a list of YouVersionVerseOfTheDay records. See Images in Verse of the Day for language selection.

To find other art for the passage, use verseImages(passageId = votd.passageUsfm). Those images can differ from the day's selected image.

Images in unified search

Unified search finds verses, topics, and related images for a text query in one request. Use it for a combined search screen. Use verseImages(passageId) when you already know the passage. To load a related image from unified search, pass its id to verseImage(imageId). The Search guide shows the request.

Parameters

Language ranges

For YouVersionApi.verseImages.verseImages, languageRanges selects the language of the text on the art. Each range is a language tag, such as en or es. Unified search has different rules. See Language ranges in the search guide. For how the Images API resolves ranges, see Language selection.

Kotlin callers often need these details:

  • Use base language tags, such as es. A regional tag such as es-MX returns no results, and the ranges after it are not tried, so listOf("es-MX", "es") returns no results.
  • Chinese art uses region tags. Use zh-CN, zh-TW, or zh-HK, not zh.
  • Only the first language that the service recognizes is used. When that language has no art for the passage, the next range is not tried.
  • Pass listOf("*"), or omit languageRanges, to include every language.

This helper makes a range from the user's locale:

Code
import java.util.Locale fun artLanguageRange(locale: Locale = Locale.getDefault()): String { // toLanguageTag() uses current codes, such as "he" rather than "iw". val language = locale.toLanguageTag().substringBefore('-') if (language == "und") return "en" if (language != "zh" && language != "yue") return language val region = locale.country val isHongKong = region == "HK" || region == "MO" val isTraditional = locale.script == "Hant" || (locale.script.isEmpty() && (language == "yue" || isHongKong || region == "TW")) if (!isTraditional) return "zh-CN" return if (isHongKong) "zh-HK" else "zh-TW" }

Image fields

PropertyTypeDescription
idStringThe image id.
imageUrlStringThe URL of the image file.
passageIdStringThe verse or verse range that the image shows, such as JHN.3.16.
attributionStringThe credit line for the image. Showing it is optional.
languageTagStringThe language of the text on the art, such as en.
width, heightIntThe original size in pixels.
aspectRatioDoublewidth divided by height.

PaginatedResponse<VerseImage> has data (List<VerseImage>), totalSize (Int?), and nextPageToken (String?).

Last modified on November 16, 2026
SearchCopyright & Attribution
On this page
  • Images APIs
    • Overview
    • List images for a passage
    • Display an image
    • Verse of the Day art
    • Images in unified search
  • Parameters
    • Language ranges
    • Image fields
Kotlin
Kotlin
Kotlin
Kotlin
Kotlin
Kotlin
Kotlin